When you use widget and have set Recommend On Pages within your content for contextual help, when a reader goes to a new page, the widget grabs the page URL and uses it to suggest content in the Recommended tab. This method works fine for applications that use full page reloads during navigation.
However, most single page applications never fully reload the page. Without that page reload, the widget won't update the Recommended tab, which can cause confusion for your reader.
To solve this problem, call the widget's updatedRecommended method to proactively tell the widget that the current URL has changed:
//method to update the current URL used for contextual help
_ko19.updateRecommended('currentUrl');
Reset first
If you using this method repeatedly in a Single Page Application, we recommend calling _ko19.reset(); before updateRecommended to clear the widget's existing state. Refer to Widget methods and functions dictionary for more information on all available widget methods
Example simple usage
Here's a sample of how you might use the updateRecommended method:
var _ko19 = _ko19 || {};
_ko19.__pc = 'xxxxxxxxxxx-xxxxxxxxxxxxx';
_ko19.base_url = '//mykb.knowledgeowl.com';
!function() {
var ko = document.createElement('script');
ko.type = 'text/javascript';
ko.async = true;
ko.src = _ko19.base_url + '/widget/load';
document.head.appendChild(ko);
// Called when the widget is toggled open
_ko19.onOpen = function () {
var currentPage = 'some-page';
_ko19.updateRecommended(currentPage);
}
}();Example dynamic usage
Ideally, rather than manually setting the currentUrl all the time, you'd create a controller or some other method to dynamically populate the currentUrl value so you can always feed that value into the widget.
Here's a very simple example HTML page for https://myapp.com/app/users/user/id/123123abasd/reports/data-usage where the currentUrl value is passed to the view from a controller dynamically:
<!DOCTYPE html>
<html>
<head>
<title>Data Usage Report for John Smith</title>
</head>
<body>
<!-- is passed to view via the controller or otherwise populated dynamically -->
<input type="hidden" id="currentUrl" value="">
</body>
</html>
The below code uses the value of the HTML element #currentUrl that we populated above:
!function() {
var ko = document.createElement('script');
ko.type = 'text/javascript';
ko.async = true;
ko.src = _ko19.base_url + '/widget/load';
document.head.appendChild(ko);
// Called when the widget is toggled open
_ko19.onOpen = function () {
var currentPage = document.getElementById('currentUrl').value;
_ko19.updateRecommended(currentPage);
}
}();
Other reasons to use this method
Even if you don't have a single page application, you may want to use this method for other reasons:
- Complex page paths or URLs: Even with a multi-page application, sometimes your app URLs might not play well with Recommend on Pages. Use this method to convert those URLs to strings the widget can handle.
- Simplify your authors' lives: The updateRecommended method accepts any string value as the currentUrl parameter, so you can replace actual URLs with far simpler things, like single words or simpler strings, rather than a long, complicated URL.
Sample usage
Let's say that you have an application URL that looks like this:
https://myapp.com/app/users/edit-user/abcd123354/id/123151ajsdfa?p=12sdfsd12&q=12154aba
The widget supports two general patterns for Suggested content in KB settings > Widget > Admin Settings:
- Suggest content based off of the page path (default): This setting would use this portion of the URL:
/app/users/edit-user/abcd123354/id/123151ajsdfa
- Use the page query strings to suggest content: This setting would only use one or more of the query strings:
p=12sdfsd12&q=12154aba
But maybe we'd recommend different articles depending on both the page path and the query strings--maybe those query strings only appear when our user is an admin or subscribes to a certain plan. So we'd need some combination of the page path AND the query string. The widget's default logic can't handle that.
In this case, we can use updateRecommended to set a much simpler text string that our authors could use. Our script might start with something like this:
//define current page and send to widget
var currentUrl = 'edit-user';
_ko19.updateRecommended(currentUrl);
We could include logic to set the currentUrl to edit-user when no query strings are present, and edit-admin-user when they are.
Then our authors can use those simplified strings in the Recommend On Pages field, for example:
The updateRecommended function accepts any string value, so we could set currentUrl to a slightly more complex string, like edit-user: normal and edit-user: admin, too!
