spUtil : Client

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

    • L’API spUtil fournit des méthodes utilitaires permettant d’exécuter des fonctions courantes dans un Portail de services script client de widget.

    Ces fonctions sont les suivantes :

    Pour en savoir plus sur les widgets, consultez Widgets du portail de services.

    spUtil : addErrorMessage(message de chaîne)

    Affiche un message d’erreur de notification.

    Tableau 1. Paramètres
    Nom Type Description
    message Chaîne Message d’erreur à afficher.
    Tableau 2. Renvoie
    Type Description
    nul 
    spUtil.addErrorMessage("There has been an error processing your request")

    spUtil : addInfoMessage(message de chaîne)

    Affiche un message d’informations de notification.

    Tableau 3. Paramètres
    Nom Type Description
    message Chaîne Message à afficher.
    Tableau 4. Renvoie
    Type Description
    nul 
    spUtil.addInfoMessage("Your order has been placed")

    spUtil : addTrivialMessage(message de chaîne)

    Affiche un message de notification trivial.

    Les messages anodins disparaissent après un court laps de temps.

    Tableau 5. Paramètres
    Nom Type Description
    message Chaîne Message à afficher.
    Tableau 6. Renvoie
    Type Description
    nul 
    spUtil.addTrivialMessage("Thanks for your order")

    spUtil : createUid()

    Créez un identificateur unique.

    Tableau 7. Paramètres
    Nom Type Description
    Aucun
    Tableau 8. Renvoie
    Type Description
    Chaîne Un ID unique de 32 caractères.

    spUtil : obtenir (String, widgetId, Objet, données)

    Incorpore un modèle de widget dans un script client de widget.

    La fonction de rappel renvoie le modèle de widget complet. Pour en savoir plus sur les widgets, consultez Widgets du portail de services.

    Tableau 9. Paramètres
    Nom Type Description
    widgetId (en anglais seulement) Chaîne ID ou sys_id du widget à incorporer.
    données Objet Facultatif. Paires nom/valeur de paramètres à transmettre au modèle de widget.
    Tableau 10. Renvoie
    Type Description
    Objet Modèle du widget incorporé.

    Sans transmission de données.

    spUtil.get("widget-cool-clock").then(function(response) {
  c.coolClock = response;
});

    Une fois les données transmises.

    spUtil.get('pps-list-modal', {title: c.data.editAllocations, 
  table: 'resource_allocation', 
  queryString: 'GROUPBYuser^resource_plan=' + c.data.sysId, 
  view: 'resource_portal_allocations' }).then(function(response) {
    var formModal = response;
    c.allocationListModal = response;
  });

    spUtil : getHeaders()

    Récupère tous les en-têtes à utiliser pour les appels d’API.

    Tableau 11. Paramètres
    Nom Type Description
    Aucun
    Tableau 12. Renvoie
    Type Description
    Objet Tous les en-têtes à utiliser pour les appels d’API.

    spUtil : getHost()

    Renvoie le domaine hôte complet.

    Tableau 13. Paramètres
    Nom Type Description
    Aucun
    Tableau 14. Renvoie
    Type Description
    Chaîne Le domaine hôte complet, par exemple hi.servicenow.com

    spUtil : getPreference(Préférence de chaîne, rappel de fonction)

    Exécute le rappel avec la réponse de préférence utilisateur en transmettant le nom de la préférence.

    Tableau 15. Paramètres
    Nom Type Description
    préférence Chaîne Nom de la préférence.
    rappel Fonction Définissez la fonction de rappel.
    Tableau 16. Renvoie
    Type Description
    nul

    spUtil : getURL()

    Renvoie les informations URL actuelles du portail de services.

    Tableau 17. Paramètres
    Nom Type Description
    Aucun
    Tableau 18. Renvoie
    Type Description
    Chaîne URL actuelle du portail de services.

    spUtil - format(chaîne, modèle, objet, données)

    Met en forme une chaîne qui contient des variables.

    Utilisez cette méthode comme alternative à la concaténation de chaînes.

    Tableau 19. Paramètres
    Nom Type Description
    modèle Chaîne Modèle de chaîne qui contient des valeurs pour la substitution de variables.
    données Objet Objet contenant les valeurs des variables définies dans la chaîne de modèle.
    Tableau 20. Renvoie
    Type Description
    Chaîne Chaîne contenant les valeurs variables au lieu de la nomenclature des variables. 
    spUtil.format('An error ocurred: {error} when loading {widget}', {error: '404', widget: 'sp-widget'})

    Sortie :

    'An error occurred: 404 when loading sp-widget'

    spUtil : isMobile()

    Vérifie si le client actuel est un équipement mobile.

    Tableau 21. Paramètres
    Nom Type Description
    Aucun
    Tableau 22. Renvoie
    Type Description
    Booléen Marqueur indiquant si le client actuel est un équipement mobile.
    Valeurs valides :
    • true : le client actuel est un équipement mobile.
    • false : le client actuel n’est pas un équipement mobile.

    spUtil : parseAttributes(attributs de chaîne)

    Analyse les attributs séparés par des virgules dans une chaîne spécifiée.

    Tableau 23. Paramètres
    Nom Type Description
    attributs Chaîne Chaîne contenant des attributs séparés par des virgules, tels que le champ Attributs d’un enregistrement de dictionnaire.
    Tableau 24. Renvoie
    Type Description
    Tableau Tableau d’objets contenant les attributs analysés. 
    function getRefQualElements() {
  var refQualElements = [];
  if (field && field.attributes && field.attributes.indexOf('ref_qual_elements') > -1) {
    var attributes = spUtil.parseAttributes(field.attributes);
    refQualElements = attributes['ref_qual_elements'].split(';');
  }
  return refQualElements;
}

    spUtil : recordWatch($scope d’objet, table de chaînes, filtre de chaîne, rappel de fonction)

    Surveille les mises à jour d’une table ou d’un filtre et renvoie la valeur à partir de la fonction de rappel.

    Permet à un développeur de widget de répondre aux mises à jour de table en temps réel. Par exemple, en utilisant recordWatch(), le widget Simple List peut écouter les modifications apportées à sa table de données. Si des enregistrements sont ajoutés, supprimés ou mis à jour, le widget se met à jour automatiquement.

    Remarque :
    Lorsque vous passez l’argument $scope dans la fonction recordWatch(),injectez-$scope dans les paramètres de votre fonction de script client.
    Tableau 25. Paramètres
    Nom Type Description
    $scope Objet Périmètre de l’objet de données mis à jour par la fonction de rappel.
    table Chaîne Table surveillée.
    filtre Chaîne Filtrez les champs à surveiller.
    rappel Fonction Facultatif. Paramètre permettant de définir la fonction de rappel.
    Tableau 26. Renvoie
    Type Description
    Promesse Valeur de retour de la fonction de rappel. 
    //A simple recordWatch function.
spUtil.recordWatch($scope, "live_profile", "sys_id=" + liveProfileId);

//In a widget client script
function(spUtil, $scope) {
  /* widget controller */
  var c =this;

  // Registers a listener on the incident table with the filter active=true, 
  // meaning that whenever something changes on that table with that filter, 
  // the callback function is executed.    
  // The callback function takes a single parameter 'response', which contains 
  // the property 'data'. The 'data' property contains information about the changed record. 
  spUtil.recordWatch($scope, "incident", "active=true", function(response) {
        
    // Returns the data inserted or updated on the table 
    console.log(response.data);   
    
    });
}

    spUtil : refresh(objet $scope)

    Appelle le serveur et remplace les options et données actuelles par la réponse du serveur.

    L’appel de spUtil.refresh() est similaire à l’appel de server.refresh(). Cependant, lorsque vous appelez spUtil.refresh(), vous pouvez définir l’objet $scope.

    Tableau 27. Paramètres
    Nom Type Description
    $scope Objet Champ d’application défini pour la mise à jour.
    Tableau 28. Renvoie
    Type Description
    Objet Options et objets de données mis à jour.

    spUtil : scrollTo(Sélecteur de chaîne, nombre d’heures)

    Défile jusqu’à l’élément avec le sélecteur spécifié, pendant une période de temps spécifiée.

    Tableau 29. Paramètres
    Nom Type Description
    sélecteur Chaîne Sélecteur vers lequel faire défiler.
    Diagramme des séries chronologiques Numéro Temps nécessaire pour faire défiler jusqu’au sélecteur spécifié.

    Unité : Millisecondes
    Tableau 30. Renvoie
    Type Description
    nul

    spUtil : setBreadCrumb(Object $scope, Tableau de fils d’Ariane)

    Met à jour le fil d’Ariane de l’en-tête.

    Tableau 31. Paramètres
    Nom Type Description
    $scope Objet Champ d’application défini pour la table.
    Fils d'Ariane Tableau Conditions utilisées pour créer le filtre de fils d’Ariane.
    Tableau 32. Renvoie
    Type Description
    nul

    spUtil : setPreference(String pref, valeur de chaîne)

    Définit une préférence utilisateur.

    Tableau 33. Paramètres
    Nom Type Description
    Pref Chaîne Nom de la préférence
    valide Chaîne Valeur de préférence
    Tableau 34. Renvoie
    Type Description
    nul

    spUtil : setSearchPage(String searchPage)

    Met à jour la page de recherche.

    Tableau 35. Paramètres
    Nom Type Description
    searchPage Chaîne Nom de la page de recherche.
    Tableau 36. Renvoie
    Type Description
    nul

    spUtil : mettre à jour (objet $scope)

    Met à jour l’objet de données sur le serveur dans un périmètre donné.

    Cette méthode est similaire à server.update(), mais inclut un paramètre $scope qui définit le périmètre à transmettre.

    Tableau 37. Paramètres
    Nom Type Description
    $scope Objet Champ d’application défini pour la mise à jour.
    Tableau 38. Renvoie
    Type Description
    Objet Objet de données mis à jour.

    L’exemple suivant inclut un widget P1 qui surveille les changements apportés au champ d’état et utilise un filtre pour surveiller tous les P1 actifs et laisser la fonction de rappel déterminer s’il faut actualiser les données. La data.changes propriété contient un tableau de tous les champs mis à jour. Si l’état d’un champ a changé, les données sont mises à jour dans le widget.

    var q = "priority=1^active=true^EQ";
spUtil.recordWatch($scope, "incident", q, function(event, data) {
   if (data.changes.includes("state")) { // only update if state was updated.
      spUtil.update($scope);
   }
});