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.

<table id=“table_iwb_kbs_xhb” class=“parameters”><thead><tr><th>

Name

</th><th>

Type

</th><th>

Description

</th></tr></thead><tbody><tr><td>

event_name

</td><td>

String

</td><td>

Event name to be removed from the listener.Valid event names:

• tourStarted

• tourEnded

• tourCompleted

• tourFailed

• tourAbandoned

• tourDismissed

• stepStarted

</td></tr><tr><td>

listener_function

</td><td>

Function

</td><td>

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.

</td></tr></tbody> </table>|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.

<table id=“table_iwb_kbs_xhb” class=“parameters”><thead><tr><th>

Name

</th><th>

Type

</th><th>

Description

</th></tr></thead><tbody><tr><td>

event_name

</td><td>

String

</td><td>

Event name to be attached to the listener.Valid event names:

• stepStarted

• tourStarted

• tourEnded

• tourCompleted

• tourFailed

• tourAbandoned

• tourDismissed

</td></tr><tr><td>

listener_function

</td><td>

Function

</td><td>

Listener to be added.Note: Clear any event listener after it solves its purpose.

</td></tr><tr><td>

listener_function.obj

</td><td>

Object

</td><td>

Passed to listener_function() by each event in the following format:- For stepStarted events:

```

{tour: ‘<tour_sys_id>’, step: step_num} “‘

• For all other events:

  {tour: '<tour_sys_id>'}
  

JSON parameters:

• tour_sys_id: String. Guided tour ID from the Guided Tours [sys_embedded_tour_guide] table

• step_num: Number. Value between 0 (first step) and n (final step)

</td></tr></tbody> </table>The following example shows basic API usage.

//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);

The following example shows how to use the listener_function parameter with obj as an argument.

top.NOW.guided_tours.events.on("tourStarted", function (obj){console.log(obj);});

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 top.NOW.guided_tours.api preceding the method name.

<table id=“table_nrj_bbs_xhb” class=“parameters”><thead><tr><th>

Name

</th><th>

Type

</th><th>

Description

</th></tr></thead><tbody><tr><td>

cb_function

</td><td>

Function

</td><td>

Callback function called by getAllTours() after attempt to fetch all tours for the current page from which getAllTours() method is called.

</td></tr><tr><td>

cb_function.err

</td><td>

Object

</td><td>

Points to the error object if any occurred during the operation:err = { success: false, message: 'string containing the error object' }

Null otherwise.

</td></tr><tr><td>

cb_function.tours

</td><td>

Array

</td><td>

List of available tours for the page.If no tours are present on the page, cb_function.tours returns undefined.

if(!tours) console.log('No tour present')

</td></tr></tbody> </table>|Type|Description| |—-|———–| |None| |

//create a callback function to handle the result of the API call
var cbFunction = function(err, tours) {
	if (err) {
   console.log('Error Occurred');
}
	else {
	    if(!tours) console.log('No tour present')
   else {
      tours.forEach(function(t) {
               console.log(t);
             });
          }
}
}
//calling the getTours method
top.NOW.guided_tours.api.getAllTours(cbFunction);

Guided Tours - loadPlayer()

Loads the guided tours player on a page in which guided tours player is not present by default.

Complete signature:

NOW.guided_tours.api.loadPlayer()

Name Type Description None     Type Description None  

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 top.NOW.guided_tours.api preceding the method name.

<table id=“table_wh5_w1s_xhb” class=“parameters”><thead><tr><th>

Name

</th><th>

Type

</th><th>

Description

</th></tr></thead><tbody><tr><td>

tour_id

</td><td>

String

</td><td>

Sys ID of the tour from the Guided Tours [sys_embedded_tour_guide] table.

</td></tr><tr><td>

step_number

</td><td>

Number

</td><td>

Optional. Step at which to start the tour. If not provided (or step number is 0), tour starts from the beginning.

</td></tr><tr><td>

cb_function

</td><td>

Function

</td><td>

Optional. Callback function called by startTour() method after attempt to launch the tour.

</td></tr><tr><td>

cb_function.err

</td><td>

Object

</td><td>

Points to the error object if any occurred during the operation:err = { success: false, message: 'string containing the error object' }

Null otherwise.

</td></tr></tbody> </table>|Type|Description| |—-|———–| |None| |

//create a callback function to handle the result of the API call
var cbFunction = function(err) {
	if (err) {
   console.log('Error Occurred');
}
	else {
   console.log('The tour with tourid=%s was successfully launched', tourId);
}
}

//calling the startTour method
top.NOW.guided_tours.api.startTour('a297e04b732313007077edcc5ef6a780', 2, cbFunction);