Visites guidées : client

  • Rversion finale: Zurich
  • Mis à jour 31 juil. 2025
  • 5 minutes de lecture

    • L’API Visites guidées fournit des méthodes pour lancer et arrêter des visites guidées.

    Cette API inclut les méthodes utilisées dans Concepteur de visite guidée.

    Visites guidées : applyListFilter(Fonction filter_func)

    Définit une fonction permettant de récupérer les résultats de visite filtrés lorsque la méthode getAllTours() est appelée.

    La signature complète comprend le haut. NOW.guided_tours.api précédant le nom de la méthode.

    Tableau 1. Paramètres
    Nom Type Description
    filter_func Fonction Fonction de filtre qui prend un seul objet de tour du tableau tours[] renvoyé par la méthode getAllTours( ).
    Tableau 2. Renvoie
    Type Description
    Aucun

    L’exemple suivant montre l’utilisation de base de l’API.

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

    L’exemple suivant montre comment utiliser le champ options de l’objet de visite guidée pour ajouter JSON avec des identificateurs de visite guidée personnalisés pour la lecture et le filtrage des visites guidées à l’intérieur de la fonction filter_func( ).

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

    Visites guidées : endTour()

    Arrête une tournée en cours de lecture. Cette méthode existe silencieusement si aucune tournée n’est en cours.

    La signature complète comprend le haut. NOW.guided_tours.api précédant le nom de la méthode.

    Tableau 3. Paramètres
    Nom Type Description
    Aucun
    Tableau 4. Renvoie
    Type Description
    Zéro 
    //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);

    Visites guidées : events.off(String event_name, Fonction listener_function)

    Supprime un écouteur d’événement existant.

    La signature complète comprend le haut. NOW.guided_tours.api précédant le nom de la méthode.

    Tableau 5. Paramètres
    Nom Type Description
    event_name Chaîne Nom de l’événement à supprimer de l’écouteur.
    Noms d’événements valides :
    • tourStarted
    • tourEnded
    • visite guidée terminée
    • tourÉchec
    • tourAbandonné
    • tourRejeté
    • étape démarrée
    listener_function Fonction Facultatif. Si elle est fournie, la fonction d’écouteur spécifiée est supprimée des écouteurs d’événements restants associés à cet événement. Si cette option n’est pas fournie, toutes les fonctions d’écouteur associées à cet événement sont supprimées.
    Tableau 6. Renvoie
    Type Description
    Aucun 
    //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);

    Visites guidées : events.on(String event_name, Fonction listener_function)

    Joint un auditeur d’événement à un événement de visite guidée.

    La signature complète comprend le haut. NOW.guided_tours.api précédant le nom de la méthode.

    Tableau 7. Paramètres
    Nom Type Description
    event_name Chaîne Nom de l’événement à joindre à l’écouteur.
    Noms d’événements valides :
    • étape démarrée
    • tourStarted
    • tourEnded
    • visite guidée terminée
    • tourÉchec
    • tourAbandonné
    • tourRejeté
    listener_function Fonction Écouteur à ajouter.
    Remarque :
    Effacer tout écouteur d’événement une fois qu’il a atteint son objectif.
    listener_function.obj Objet Passé à listener_function() par chaque événement au format suivant :
    • Pour les événements stepStarted : 
      {tour: '<tour_sys_id>', step: step_num}
    • Pour tous les autres événements :
      {tour: '<tour_sys_id>'}
    Paramètres JSON :
    • tour_sys_id : Chaîne. ID de visite guidée de la table Visites guidées [sys_embedded_tour_guide]
    • step_num : Numéro. Valeur comprise entre 0 (première étape) et n (étape finale)

    L’exemple suivant montre l’utilisation de base de l’API.

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

    L’exemple suivant montre comment utiliser le paramètre listener_function avec obj comme argument.

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

    Visites guidées : getAllTours(Fonction cb_function)

    Obtient une liste des visites guidées sur la page actuelle à partir de laquelle cette méthode est appelée. Comme cette méthode est asynchrone, une fonction de rappel doit être transmise pour déterminer la réussite de l’opération et obtenir une liste des présentations.

    La signature complète comprend le haut. NOW.guided_tours.api précédant le nom de la méthode.

    Tableau 8. Paramètres
    Nom Type Description
    cb_function Fonction Fonction de rappel appelée par getAllTours() après la tentative d’extraction de toutes les visites guidées de la page actuelle à partir de laquelle la méthode getAllTours() est appelée.
    cb_function.err Objet Pointe vers l’objet d’erreur si une erreur s’est produite pendant l’opération :

    err = { réussite : faux, message : 'chaîne contenant l’objet d’erreur' }

    Nul dans le cas contraire.
    cb_function.visites Tableau Liste des visites disponibles pour la page.

    Si aucune visite guidée n’est présente sur la page, cb_function.tours renvoie une valeur non définie.

    if( !tours) console.log('Aucune visite présente')
    Tableau 9. Renvoie
    Type Description
    Aucun 
    //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);

    Visites guidées : loadPlayer()

    Charge le lecteur de visites guidées sur une page dans laquelle le lecteur de visites guidées n’est pas présent par défaut.

    Signature complète : 
    NOW.guided_tours.api.loadPlayer()
    Tableau 10. Paramètres
    Nom Type Description
    Aucun
    Tableau 11. Renvoie
    Type Description
    Aucun

    Visites guidées : startTour(String tour_id, Number step_number, Function cb_function)

    Démarre une visite guidée. Étant donné que cette méthode est asynchrone, vous devez transmettre une fonction de rappel pour déterminer la réussite de l’opération.

    La signature complète comprend le haut. NOW.guided_tours.api précédant le nom de la méthode.

    Tableau 12. Paramètres
    Nom Type Description
    tour_id Chaîne ID système de la visite guidée de la table Visites guidées [sys_embedded_tour_guide].
    step_number Numéro Facultatif. Étape à laquelle commencer la visite guidée. Si ce n’est pas fourni (ou si le numéro d’étape est 0), la visite guidée commence depuis le début.
    cb_function Fonction Facultatif. Fonction de rappel appelée par la méthode startTour() après la tentative de lancement de la visite guidée.
    cb_function.err Objet Pointe vers l’objet d’erreur si une erreur s’est produite pendant l’opération :

    err = { réussite : faux, message : 'chaîne contenant l’objet d’erreur' }

    Nul dans le cas contraire.
    Tableau 13. Renvoie
    Type Description
    Aucun 
    //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);