Créer des fiches interactives

La plupart des modules complémentaires, en plus de présenter des données, exigent que l'utilisateur saisisse des informations. Lorsque vous créez un module complémentaire basé sur des fiches, vous pouvez utiliser des widgets interactifs tels que des boutons, des éléments de menu de barre d'outils ou des cases à cocher pour demander à l'utilisateur les données dont votre module complémentaire a besoin ou pour fournir d'autres contrôles d'interaction.

Ajouter des actions aux widgets

Dans la plupart des cas, vous rendez les widgets interactifs en les associant à des actions spécifiques et en implémentant le comportement requis dans une fonction de rappel. Pour en savoir plus, consultez Actions de modules complémentaires.

Dans la plupart des cas, vous pouvez suivre cette procédure générale pour configurer un widget afin qu'il effectue une action spécifique lorsqu'il est sélectionné ou mis à jour :

1. Créez un objet Action en spécifiant la fonction de rappel à exécuter, ainsi que tous les paramètres requis.
2. Associez le widget à Action en appelant la fonction de gestionnaire de widget appropriée.
3. Implémentez la fonction de rappel pour mettre en œuvre le comportement requis.

Exemple

L'exemple suivant définit un bouton qui affiche une notification utilisateur après avoir été cliqué. Le clic déclenche la fonction de rappel notifyUser() avec un argument qui spécifie le texte de la notification. Le renvoi d'un ActionResponse intégré entraîne l'affichage d'une notification.

  /**
   * Build a simple card with a button that sends a notification.
   * @return {Card}
   */
  function buildSimpleCard() {
    var buttonAction = CardService.newAction()
        .setFunctionName('notifyUser')
        .setParameters({'notifyText': 'Button clicked!'});
    var button = CardService.newTextButton()
        .setText('Notify')
        .setOnClickAction(buttonAction);

    // ...continue creating widgets, then create a Card object
    // to add them to. Return the built Card object.
  }

  /**
   * Callback function for a button action. Constructs a
   * notification action response and returns it.
   * @param {Object} e the action event object
   * @return {ActionResponse}
   */
  function notifyUser(e) {
    var parameters = e.parameters;
    var notificationText = parameters['notifyText'];
    return CardService.newActionResponseBuilder()
        .setNotification(CardService.newNotification()
            .setText(notificationText))
        .build();      // Don't forget to build the response!
  }

Concevoir des interactions efficaces

Lorsque vous concevez des cartes interactives, tenez compte des points suivants :

• Les widgets interactifs ont généralement besoin d'au moins une méthode de gestionnaire pour définir leur comportement.

• Utilisez la fonction de gestionnaire de widget setOpenLink() lorsque vous disposez d'une URL et que vous souhaitez simplement l'ouvrir dans un onglet. Cela évite de devoir définir un objet Action et une fonction de rappel. Si vous devez d'abord créer l'URL ou effectuer d'autres étapes supplémentaires avant de l'ouvrir, définissez un Action et utilisez setOnClickOpenLinkAction() à la place.

• Lorsque vous utilisez les fonctions de gestionnaire de widget setOpenLink() ou setOnClickOpenLinkAction(), vous devez fournir un objet OpenLink pour définir l'URL à ouvrir. Vous pouvez également utiliser cet objet pour spécifier le comportement d'ouverture et de fermeture à l'aide des énumérations OpenAs et OnClose.

• Il est possible que plusieurs widgets utilisent le même objet Action. Toutefois, vous devez définir différents objets Action si vous souhaitez fournir des paramètres différents à la fonction de rappel.

• Vos fonctions de rappel doivent rester simples. Pour que les modules complémentaires restent réactifs, le service de cartes limite le temps d'exécution des fonctions de rappel à 30 secondes maximum. Si l'exécution prend plus de temps, l'interface utilisateur de votre module complémentaire risque de ne pas mettre à jour correctement l'affichage de ses fiches en réponse à Action .

• Si l'état des données d'un backend tiers change à la suite d'une interaction utilisateur avec l'UI de votre module complémentaire, il est recommandé que le module complémentaire définisse un bit "state changed" (état modifié) sur true afin que tout cache côté client existant soit effacé. Pour en savoir plus, consultez la description de la méthode ActionResponseBuilder.setStateChanged().