Visites guidées : client

  • Rversion finale: Xanadu
  • Mis à jour 1 août 2024
  • 5 minutes de lecture

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

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

    Visites guidées : applyListFilter(Function filter_func)

    Définit une fonction pour récupérer les résultats de visite guidée 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 visite guidée du tableau tours[] retourné 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 tour pour ajouter JSON avec des identificateurs de visite personnalisée 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 visite guidée en cours de lecture. Cette méthode se ferme silencieusement si aucune visite n’est en cours de lecture.

    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 (chaîne 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 d’événement à supprimer de l’écouteur.
    Noms d’événements valides :
    • tourStarted
    • tourTerminé
    • visite guidéeterminée
    • TourFailed (en anglais seulement)
    • tourAbandonné
    • tourRejeté
    • stepStarted
    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 elles ne sont pas fournies, toutes les fonctions d’écouteur attaché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(chaîne event_name, fonction listener_function)

    Joint un écouteur 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 d’événement à joindre à l’écouteur.
    Noms d’événements valides :
    • stepStarted
    • tourStarted
    • tourTerminé
    • visite guidéeterminée
    • TourFailed (en anglais seulement)
    • tourAbandonné
    • tourRejeté
    listener_function Fonction Écouteur à ajouter.
    Remarque :
    Effacez tout écouteur d’événement une fois qu’il a résolu 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 à partir de la table Visites guidées [sys_embedded_tour_guide]
    • step_num : Nombre. Valeur comprise entre 0 (première étape) et n (dernière étape)

    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(Function cb_function)

    Obtient une liste de visites guidées sur la page actuelle à partir de laquelle cette méthode est appelée. Étant donné que 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 de visites.

    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 une tentative d’extraction de toutes les visites pour la page actuelle à partir de laquelle la méthode getAllTours() est appelée.
    cb_function.err Objet Pointe vers l’objet d’erreur s’il s’est produit pendant l’opération :

    err = { success : false, message : 'chaîne contenant l’objet d’erreur' }

    Null dans le cas contraire.
    cb_function.tours Tableau Liste des visites guidées disponibles pour la page.

    Si aucune visite n’est présente sur la page, cb_function.tours renvoie non défini.

    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(chaîne tour_id, numéro step_number, fonction 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 à partir de la table Visites guidées [sys_embedded_tour_guide].
    step_number Numéro Facultatif. Étape à laquelle commencer la visite. S’il n’est pas fourni (ou si le numéro d’étape est 0), la visite commence depuis le début.
    cb_function Fonction Facultatif. Fonction de rappel appelée par la méthode startTour() après une tentative de lancement de la visite guidée.
    cb_function.err Objet Pointe vers l’objet d’erreur s’il s’est produit pendant l’opération :

    err = { success : false, message : 'chaîne contenant l’objet d’erreur' }

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