aides : UI Builder

L’API helpers fournit des fonctionnalités générales communes à tous les scripts de page, éliminant ainsi la nécessité d’écrire des scripts pour des fonctionnalités simples telles que l’ouverture et la fermeture d’un modal.

Cette API n’est disponible que pour les scripts de page, elle n’est pas disponible dans les autres scripts du générateur d’IU, notamment :

• Scripts des valeurs des propriétés des composants
• Scripts de visibilité des composants
• Scripts de charge utile d’événement
• Includes de script client UX

helpers : helpers.modal.close(String modalId)

Ferme le modal spécifié sur la page actuelle.

Tableau 1. Paramètres

Nom	Type	Description
modalId	Chaîne	ID de composant modal du modal à fermer. Les ID de composant sont générés automatiquement lorsqu’un composant est glissé et déplacé sur l’étape Générateur d'IU . Vous pouvez localiser l’ID sur la page de la propriété.

Tableau 2. Renvoie

Type	Description
Aucun

Cet exemple montre la fermeture d’un modal avec un ID de composant qui se termine par alert-modal.

function handler({api, event, imports, helpers}) {
  helpers.modal.close("[component-id$='alert_modal']")
}

helpers : helpers.modal.open(String modalId, options d’objet)

Ouvre le modal spécifié sur la page actuelle.

Vous ne pouvez afficher qu’un seul modal à la fois dans une page. Si une fenêtre modale est actuellement ouverte et que vous appelez cette méthode, la fenêtre modale existante est masquée et la nouvelle fenêtre modale apparaît.

Tableau 3. Paramètres

Nom	Type	Description
modalId	Chaîne	ID de composant du modal à ouvrir. Les ID de composant sont générés automatiquement lorsqu’un composant est glissé et déplacé sur l’étape Générateur d'IU . Vous pouvez localiser l’ID sur la page de la propriété.
options	Objet	Facultatif. "options": { "content": "String", "contentFullWidth": Boolean, "headerLabel": "String", "size": "String" }
options.content	Chaîne	Contenu textuel pour le modal.
options.contentFullWidth	Booléen	Marqueur indiquant s’il faut supprimer le remplissage horizontal autour du corps du modal afin d’adapter le contenu plus large. Valeurs valides : vrai : Retirez le remplissage. faux : Ne retirez pas le rembourrage. Valeur par défaut : false
options.headerLabel	Chaîne	Contenu du texte de l’en-tête du modal.
Options.Taille	Chaîne	Taille du conteneur modal. La plupart des tailles s’agrandissent automatiquement pour remplir la fenêtre d’affichage lorsque la taille de l’écran est petite. Valeurs valides : sm md lg Plein écran Par défaut : sm

Tableau 4. Renvoie

Type	Description
Aucun

Cet exemple montre l’ouverture d’un modal avec l’ID de l’omponent ca qui se termine par alert-modal.

function handler({api, event, imports, helpers}) {
  helpers.modal.open("[component-id$='alert_modal']")
}

helpers : helpers.navigate.setRouteParams (paramètres d’objet)

Transmet les paramètres spécifiés à d’autres composants sur la même page.

Utilisez cette méthode dans n’importe quel composant de page qui souhaite ajouter un paramètre dans une URL. Vous pouvez ajouter un paramètre à une URL lorsqu’un autre composant a besoin de connaître la valeur actuelle de ce paramètre lorsqu’il change, afin de pouvoir y réagir. Par exemple, utilisez cette méthode pour transmettre le selectedIndex d’un composant d’onglet afin qu’il soit reflété dans l’URL pour donner le focus à cet onglet.

Tableau 5. Paramètres

Nom	Type	Description
paramètres	Objet	Paires clé-valeur de paramètres facultatifs à transmettre à d’autres composants. Il doit s’agir d’un objet simple et plat avec uniquement des valeurs primitives. Les références de tableau ou d’objet sont ignorées et ne sont pas ajoutées à l’URL. Toutes les clés spécifiées doivent faire partie des paramètres facultatifs de la configuration de l’itinéraire, sinon elles sont également ignorées. Pour plus d’informations sur les paramètres facultatifs, consultez Créer une page dans Générateur d’IU.

Tableau 6. Renvoie

Type	Description
Aucun

Cet exemple de code montre comment ajouter l’URL params/selected-tab-index/2. Notez que le paramètre de l’URL réelle est passé de camel case à snake, donc selectedTabIndex devient selected-tab-index.

function handler({api, event, helpers, imports}) {  
  helpers.navigate.setRouteParams({'params': {'selectedTabIndex':  2}});  
} 

helpers : helpers.navigate.to(String route, Object fields, Object params, Boolean redirect, Boolean passiveNavigation, String targetRoute)

Navigue d’un écran à l’autre en fonction de l’itinéraire spécifié et des informations de champ. Les changements d’URL et les chargements d’écran respectifs sont observés.

Tableau 7. Paramètres

Nom	Type	Description
acheminement	Chaîne	Nom de l’itinéraire. Doit être une entrée valide d’Itinéraires d’applications UX (sys_ux_app_route.list). Cette valeur est reflétée dans l’URL, et l’URL est créée en fonction des valeurs de route colonne et : /<route>/<field1Value>/{<field2Value>/params/<optionalParamKey1>/<optionalParamValue1>/<optionalParamKey2>/<optionalParamValue2>fieldsoptionalParams Par exemple : /record/incident/12345/params/selectedTabIndex/4
champs	Objet	Facultatif. Paires clé-valeur des paramètres requis. Par exemple : 'fields' : {'table' : 'incident', 'sysId' : '12345'}.
paramètres	Objet	Facultatif. Paires clé-valeur de paramètres facultatifs. Par exemple : 'params' : {'selectedTabIndex' : 4}.
Redirection	Booléen	Marqueur indiquant s’il faut supprimer la dernière entrée d’historique de l’historique du navigateur. Par exemple, si vous accédez aux sites A, B puis C. Si redirect la valeur est définie sur vrai lors de la navigation vers C, l’entrée d’historique pour B est supprimée. L’historique du navigateur n’affiche que A et C. Valeurs valides : true : supprime la dernière entrée d’historique et redirige vers la dernière URL. faux : ne supprime aucune entrée d’historique. Valeur par défaut : false
passiveNavigation	Booléen	Marqueur indiquant s’il faut effectuer une navigation en arrière-plan. La navigation en arrière-plan se produit lorsqu’une page est ouverte mais qu’elle n’est pas active ou affichée. Par exemple, ouvrir un onglet inactif pour la page, mais il n’est pas visible mais chargé en arrière-plan. Valeurs valides : true : effectuer la navigation en arrière-plan. faux : ne pas effectuer de navigation en arrière-plan. Valeur par défaut : false
targetRoute	Chaîne ou objet	Sous-navigation vers une exploration vers le bas, un lien profond ou un sous-onglet. Si la valeur est actuelle, l’itinéraire actuel effectue une sous-navigation sous l’URL actuelle. Par exemple, si /record/incident/123 est l’URL actuelle et que l’appel suivant est effectué : helper.navigate.to('record', {'table' : 'problem', 'sysId' : '567'}, {}, false, false, 'current') ; L’URL suivante est générée : /record/incident/123/sub/record/problem/567 Remarque : targetRoute Il peut s’agir d’une chaîne telle que « current » ou d’un objet, tel que la navigation NAV_ITEM_SELECTED la charge utile.

Tableau 8. Renvoie

Type	Description
Aucun

Cet exemple montre comment naviguer vers une page en transmettant uniquement le route paramètre.

function handler({api, event, imports, helpers}) {
  helpers.navigate.to('test');
}

Cet exemple montre comment accéder à une page en transmettant les route paramètres and fields .

function handler({api, event, imports, helpers}) {
  helpers.navigate.to('test', {'key': 'value'});
}

Cet exemple montre comment accéder à une page en transmettant les routeparamètres , fields, et params .

function handler({api, event, helpers, imports}) {
  helpers.navigate.to('test', {'key': 'value'}, {'first': 'FirstName', 'last': 'Last Name'});
}

helpers : helpers.screen.updateStatus(Object statusObj)

Permet aux pages de signaler leurs mises à jour d’état, telles que le titre, l’icône, l’état erroné, le message et les changements d’erreur.

Les mises à jour de l’état sont signalées à WorkspaceChrome ou AppShell, quelle que soit la couche externe, et agissent en tant qu’hôte.

Tableau 9. Paramètres

Nom	Type	Description
statusObj	Objet	Charge utile à envoyer à la page actuelle pour signaler que le contenu a été mis à jour. Valeurs valides : dirtyModalId: (chaîne) ID du modal qui a changé. hasError: (booléen) Marqueur qui indique qu’il y a des erreurs sur la page. hasUpdate: (booléen) Marqueur indiquant que la page a été mise à jour. icon: (chaîne) nom de l’icône mise à jour ou nouvelle. isDirty: (booléen) Marqueur indiquant si la page est erronée (les valeurs ont changé). message: (chaîne) Mis à jour/nouveau message. screenKey: (chaîne) ID de l’écran sur lequel le changement s’est produit. Chaque écran a une screenKey propriété as sur le macroponent d’écran à l’intérieur de sn-canvas-screen. status: (chaîne) Opération de statut pour cette action. Cette valeur doit être l’une des suivantes : inséré, supprimé, enregistré ou fermé. title: (chaîne) Titre d’affichage mis à jour/nouveau. tooltipPreview: (JSON) Info-bulle mise à jour ou nouvelle. Par exemple, tooltipPreview : { primaryTitle, secondaryContent : {} }

Tableau 10. Renvoie

Type	Description
Aucun

screen.updateStatus({'dirtyModalId': 'customModalId', 'isDirty': true});

helpers : helpers.snHttp(String url, Object options)

Envoie une demande HTTP à l’instance ServiceNow et renvoie une promesse avec les résultats.

Remarque :

Il existe un problème connu où les objets nommés options sont omis de la réponse HTTP.

{
  options: {},
  otherFields: {}
}

becomes

{
  otherFields: {}
}

Tableau 11. Paramètres

Nom	Type	Description
URL	Chaîne	Point de terminaison HTTP par rapport à l’URL d’instance. Par exemple, /api/now/table/incident ou /api/now/table/incident/a83820b58f723300e7e16c7827bdeed.
options	Objet	Décrit le contenu de la demande HTTP. "options": { "batch": Boolean, "body": {Object}, "headers": {Object}, "method": "String" }
options.lot	Booléen	Facultatif. Marqueur indiquant si cette demande HTTP doit être regroupée par lots avec d’autres requêtes HTTP adressées à l’instance. Valeurs valides : vrai : effectuer une demande dans le cadre d’une demande par lots. faux : effectuer une demande dédiée. Par défaut : true
options.corps	Objet	Facultatif. Données à envoyer comme corps de demande. Applicable uniquement aux méthodes de demande PUT, POST et PATCH. Les éléments de l’objet dépendent du type de méthode HTTP. Pour plus de détails, reportez-vous aux exemples de code ci-dessous. Par défaut : {}
Options.En-têtes	Objet	Facultatif. En-têtes de demande HTTP supplémentaires. Par exemple : headers: { "Content-Type": "application/json", "Accept": "application/xml" }
Options.Méthode	Chaîne	Facultatif. Méthode HTTP. Valeurs valides : DELETE GET PATCH POST PUT Valeur par défaut : GET

Tableau 12. Renvoie

Type	Description
erreur	Objet qui décrit toute erreur renvoyée par l’API REST. Type de données : objet "error": { "data": "String", "message": "String", "options": {Object}, "status": Number, "statusText": "String" }
erreur.données	Réponse renvoyée par l’API HTTP. Type de données : Défini par l’API REST
message.erreur	Message décrivant l’erreur rencontrée lors de la tentative de traitement de la requête HTTP. Remarque : Ce paramètre n’est pas toujours renvoyé. Type de données : chaîne
error.options	Décrit la demande HTTP d’origine. Type de données : objet "options": { "headers": {Object}, "responseHeader": {Object} }
Erreur.Options.En-têtes	Objet contenant une liste de tous les en-têtes de demande envoyés dans la demande. Type de données : objet
error.options.responseHeaders	Objet contenant une liste de tous les en-têtes de réponse envoyés dans la demande. Type de données : objet
état de l’erreur	Code d’état d’erreur HTTP retourné, tel que 400, 405 ou 500. Type de données : nombre
error.statusText	Message d’état HTTP retourné, tel que Demande incorrecte. Type de données : chaîne
réponse	Renvoyé lorsque la requête HTTP est réussie. La réponse à la demande HTTP. Type de données : N’importe lequel

L’exemple suivant montre comment appeler snHttp() qui renvoie une promesse.

function handler({api, event, helpers, imports}) {
  helpers.snHttp('/api/now/table/u_movie', {method: 'GET'})
    .then(({response}) => {
      // do something with the table data
    })
    .catch(({error}) => {
      const message = `Error: ${error.data.error.message}`;
      console.error(message);
      api.emit('NOW_UXF_PAGE#ADD_NOTIFICATIONS', {
        id: 'alert5',
        status: 'high',
        icon: 'info-circle-outline',
        content: message,
        action: { type: 'dismiss' }
    });
  });
}

L’exemple suivant montre comment appeler snHttp() en utilisant async et await.

async function handler({helpers}) {
  try {
    const result = await helpers.snHttp('/api/now/table/u_movie', {method: 'GET'});
  } catch ({error}) {
      const message = `Error: ${error.data.error.message}`;
      console.error(message);
      api.emit('NOW_UXF_PAGE#ADD_NOTIFICATIONS', {
        id: 'alert5',
        status: 'high',
        icon: 'info-circle-outline',
        content: message,
        action: { type: 'dismiss' }
      });
  }
}

L’exemple suivant montre comment configurer une demande POST.

function handler({api, helpers, event, imports}) {
  helpers
    .snHttp("/api/now/table/incident", {
      method: "POST",
      body: {
        description: "Sample description",
        close_notes: "Sample close notes",
        order: "-1"
      }
    })
    .then(({ response }) => {
      // handle POST request response
    })
    .catch(({ error }) => {
      // handle POST request errors
    });
}

L’exemple suivant montre comment configurer une demande PUT.

function handler({api, helpers, event, imports}) {
  helpers
    .snHttp("/api/now/table/incident/a83820b58f723300e7e16c7827bdeed2", {
      method: "PUT",
      body: {
        activity_due: "1970-04-02 18:26:17"
      },
      headers: {
        "Content-Type": "application/json",
        "Accept": "application/xml"
      }
    })
    .then(({ response }) => {
      // handle PUT request response
    })
    .catch(({ error }) => {
      // handle PUT request errors
    });
}

helpers : helpers.timing.clearInterval(Number timeoutId)

Annule l’exécution de la fonction qui a été planifiée via un appel setInterval() précédent.

Tableau 13. Paramètres

Nom	Type	Description
timeoutId	Numéro	Identificateur unique de la fonction planifiée à effacer. Cette valeur est renvoyée par l’appel setInterval() correspondant.

Tableau 14. Renvoie

Type	Description
Aucun

Cet exemple montre l’utilisation de clearInterval() pour annuler une opération de synchronisation précédemment définie à l’aide de la méthodesetInterval( ). Cette fonction peut être invoquée par un utilisateur cliquant sur un bouton Désactiver l’actualisation automatique sur une page.

function handler({api, helpers}) {
  api.setState('intervalId', ({currentValue}) => {
    if (currentValue > -1) {
      helpers.timing.clearInterval(currentValue);
    }
    return -1;
  });
}

helpers : helpers.timing.clearTimeout(Number timeoutId)

Annule l’exécution de la fonction qui a été planifiée via un appel setTimeout() précédent.

Tableau 15. Paramètres

Nom	Type	Description
timeoutId	Numéro	Identificateur unique de la fonction planifiée à effacer. Cette valeur est renvoyée par l’appel setTimeout() correspondant.

Tableau 16. Renvoie

Type	Description
Aucun

Cet exemple de code montre comment arrêter un minuteur avec le timeoutId spécifié.

function handler({api, helpers}) {
  api.setState('timeoutId', ({currentValue}) => {
    if (currentValue > -1) {
      helpers.timing.clearTimeout(currentValue);
    }
    return -1;
  });
}

helpers : helpers.timing.setInterval(Fonction fn, délai de numéro)

Exécute à plusieurs reprises la fonction spécifiée, en utilisant la valeur de retard spécifiée comme intervalle entre les appels de fonction.

Contrairement à la méthode JavaScript native setInterval(), cette méthode ne prend pas en charge le passage d’une chaîne de code à évaluer comme premier argument. Tous les arguments supplémentaires sont transmis à la fonction elle-même.

Tableau 17. Paramètres

Nom	Type	Description
Fn	Fonction	Fonction à exécuter de manière répétée.
retarder	Numéro	Longueur de l’intervalle de temps entre chaque exécution de fonction. Unité : millisecondes

Tableau 18. Renvoie

Type	Description
Numéro	Identificateur unique de l’opération d’exécution de la fonction. Utilisez cette valeur dans la helpers : helpers.timing.clearInterval(Number timeoutId) méthode si vous devez annuler cette opération.

Cet exemple de code montre comment actualiser l’horodatage d’une page toutes les secondes. Cette fonction peut être invoquée par un utilisateur cliquant sur un bouton Activer l’actualisation automatique sur une page.

function handler({api, helpers}) {
  // Every one second, refresh the value of current timestamp client state parameter
  const intervalId = helpers.timing.setInterval(() => {
    api.setState('currentTimestamp', new Date().toString())
  }, 1000);

  // The interval ID is kept in state to use when calling the helpers.timing.clearInterval() method at a later point
  api.setState('intervalId', intervalId);
}

helpers : helpers.timing.setTimeout(Fonction fn, délai de numéro)

Exécute la fonction spécifiée, après le délai spécifié.

Contrairement à la méthode JavaScript native setTimeout(), cette méthode ne prend pas en charge le passage d’une chaîne de code à évaluer comme premier argument. Tous les arguments supplémentaires sont transmis à la fonction elle-même.

Tableau 19. Paramètres

Nom	Type	Description
Fn	Fonction	Fonction à exécuter.
retarder	Numéro	Durée d’attente avant d’appeler la fonction spécifiée. Unité : millisecondes

Tableau 20. Renvoie

Type	Description
Numéro	Identificateur unique de l’opération d’exécution de la fonction. Utilisez cette valeur dans la helpers : helpers.timing.clearTimeout(Number timeoutId) méthode si vous devez annuler cette opération.

Cet exemple de code montre comment régler une minuterie de 20 minutes. Vous pouvez associer cette fonction à un bouton Rappelez-moi dans 20 minutes.

function handler({api, helpers}) {
  const timeoutId = helpers.timing.setTimeout(() => {
    api.emit('NOW_UXF_PAGE#ADD_NOTIFICATIONS', {
      id: 'alert5',
      status: 'high',
      icon: 'info-circle-outline',
      content: 'Try to look away at something that is 20 feet away from you for a total of 20 minutes.',
      action: { type: 'dismiss' }
    });
  }, 20 * 60 * 1000);

  // The timeout ID is kept in state to use when calling the helpers.timing.clearTimeout() method at a later point
  api.setState('timeoutId', timeoutId);
}

helpers : helpers.translate(Message de chaîne, jetons de chaîne)

Récupère et traduit de façon asynchrone le message spécifié en fonction de la langue de la session de l’utilisateur actuel.

Vous pouvez utiliser cette méthode avec le api : setState(String, stateParam, n’importe quelle valeur) pour lier la valeur traduite à d’autres champs de la page.

Remarque :

Vous pouvez appeler cette méthode à l’aide d’une promesse ou d’une asynchrone et attendre. Les exemples de code ci-dessous montrent les deux implémentations.

Tableau 21. Paramètres

Nom	Type	Description
message	Chaîne	Message à traduire.
jetons	Chaîne	Facultatif. Liste de paramètres séparés par des virgules à utiliser pour remplacer les variables de chaîne. Par exemple : helpers.translate('Text {0} {1}', 'to', 'translate');

Tableau 22. Renvoie

Type	Description
Chaîne	Chaîne de texte traduite.

L’exemple suivant montre comment transmettre dans la table des références de champ à intégrer dans les variables correspondantes d’une chaîne, à l’aide d’une promesse.

function handler ({api, helpers}) {
  helpers.translate('Welcome {0} {1}!', user.firstName, user.lastName)
    .then((translatedText) => {
      api.setState('greeting', translatedText);
    });
}

L’exemple suivant montre comment utiliser async et await dans votre fonction au lieu d’une promesse.

async function handler ({api, helpers}) {
  const translatedText = await helpers.translate('Welcome to {0}', 'ServiceNow');
    api.setState('greeting', translatedText);
}