Guided Tours- Client
The Guided Tours API provides methods for launching and stopping guided tours.
This API includes methods used in Guided Tour Designer.
Parent Topic:Client API reference
Guided Tours - applyListFilter(Function filter_func)
Sets a function to retrieve filtered tour results when the getAllTours() method is called.
Complete signature includes top.NOW.guided_tours.api preceding the method name.
| Name | Type | Description |
|---|---|---|
| filter_func | Function | Filter function that takes a single tour object from the tours[] array returned from getAllTours() method. |
| Type | Description |
|---|---|
| None |
The following example shows basic API usage.
//create a filter function
var filtFunction = function(tour) {
//only return those tours whose name starts with 'my'
return tour.name.indexOf('my') === 0);
}
//apply the filter
top.NOW.guided_tours.api.applyListFilter (filtFunction);
//call the getAllTours method to observe the filtered tours
top.NOW.guided_tours.api.getAllTours (function(er, tours) {
if(!er) {
console.log('The filtered tours are: ');
console.log(tours);
}
});
The following example shows how to use the options field on the tour object to add JSON with custom tour identifiers for reading and filtering tours inside the filter_func() function.
top.NOW.guided_tours.api.applyListFilter(function(tour) {
var options = (tour.options)? JSON.parse(tour.options): null;
return (options && options.my_param) ? (options.my_param == my_value) : false;
});
Guided Tours - endTour()
Stops a currently playing tour. This method silently exits if no tours are playing.
Complete signature includes top.NOW.guided_tours.api preceding the method name.
| Name | Type | Description |
|---|---|---|
| None |
| Type | Description |
|---|---|
| Null |
//create a callback function to end the tour if it starts correctly
var cbFunction = function(err) {
if (err) {
console.log('Error Occurred');
}
else {
// tour has started so we can call endTour
top.NOW.guided_tours.api.endTour();
}
}
//calling the startTour method so that we can end the tour as soon as it starts
top.NOW.guided_tours.api.startTour('a297e04b732313007077edcc5ef6a780', 2, cbFunction);
Guided Tours - events.off(String event_name, Function listener_function)
Removes an existing event listener.
Complete signature includes top.NOW.guided_tours.api preceding the method name.
| Name | Type | Description |
|---|---|---|
| event\_name | String | Event name to be removed from the listener.Valid event names: - tourStarted - tourEnded - tourCompleted - tourFailed - tourAbandoned - tourDismissed - stepStarted |
| listener\_function | Function | Optional. If provided, specified listener function is removed from remaining event listeners attached with that event. If not provided, all listener functions attached to that event are removed. |
| Type | Description |
|---|---|
| None |
//create a callback function to handle the result of the api call
var eventListenerTourStarted = function() {
console.log('The tour has started');
}
var eventListenerTourEnded = function() {
console.log('The tour has ended');
}
//attaching event listeners for tourStarted and tourEnded Events
top.NOW.guided_tours.events.on('tourStarted',eventListenerTourStarted);
top.NOW.guided_tours.events.on('tourEnded', eventListenerTourEnded);
…
//start a tour
top.NOW.guided_tours.api.startTour ('a297e04b732313007077edcc5ef6a780', 2, cbFunction);
//As soon as the tour starts the eventListenerTourStarted gets fired
…
top.NOW.guided_tours.api.endTour();
// eventListenerTourEnded gets fired
….
//removing the event listeners top.NOW.guided_tours.events.off('tourStarted',eventListenerTourStarted);
top.NOW.guided_tours.events.off('tourEnded', eventListenerTourEnded);
Guided Tours - events.on(String event_name, Function listener_function)
Attaches an event listener to a guided tour event.
Complete signature includes top.NOW.guided_tours.api preceding the method name.
| Name | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| event\_name | String | Event name to be attached to the listener.Valid event names: - stepStarted - tourStarted - tourEnded - tourCompleted - tourFailed - tourAbandoned - tourDismissed | |||||||||||||||||||||||||||||||||||||||||||||
| listener\_function | Function | Listener to be added.Note: Clear any event listener after it solves its purpose. | |||||||||||||||||||||||||||||||||||||||||||||
| listener\_function.obj | Object | Passed to `listener_function()` by each event in the following format:- For stepStarted events: ``` {tour: ' The following example shows basic API usage. The following example shows how to use the Guided Tours - getAllTours(Function cb_function)Gets a list of tours on the current page from which this method is called. Because this method is asynchronous, a callback function must be passed to determine operation success and get a list of tours. Complete signature includes
Guided Tours - loadPlayer()Loads the guided tours player on a page in which guided tours player is not present by default. Complete signature:
Guided Tours - startTour(String tour_id, Number step_number, Function cb_function)Starts a tour. Because this method is asynchronous, you must pass a callback function to determine operation success. Complete signature includes
|