Créer des fiches interactives

En plus de présenter des données, la plupart des modules complémentaires nécessitent 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 la barre d'outils ou des cases à cocher pour demander à l'utilisateur les données dont votre module complémentaire a besoin ou fournir d'autres commandes d'interaction.

Ajouter des actions aux widgets

Pour la plupart, vous rendez les widgets interactifs en les liant à des actions spécifiques et en implémentant le comportement requis dans une fonction de rappel. Pour en savoir plus, consultez la section Actions des 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 widgets appropriée.
3. Mettez en œuvre la fonction de rappel pour appliquer le comportement requis.

Exemple

L'exemple suivant définit un bouton qui affiche une notification utilisateur lorsqu'un utilisateur clique dessus. 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 fiches interactives, tenez compte des points suivants:

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

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

• Lorsque vous utilisez les fonctions de gestionnaire de widgets 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.

• Plusieurs widgets peuvent utiliser le même objet Action. Toutefois, vous devez définir différents objets Action si vous souhaitez fournir à la fonction de rappel différents paramètres.

• Optez pour des fonctions de rappel simples. Pour que les modules complémentaires restent réactifs, le service de cartes limite la durée d'exécution des fonctions de rappel à 30 secondes maximum. Si l'exécution prend plus de temps, l'interface utilisateur du module complémentaire risque de ne pas mettre à jour l'affichage de sa carte correctement en réponse à Action .

• Si un état de données sur un backend tiers change à la suite d'une interaction de l'utilisateur avec l'interface utilisateur de votre module complémentaire, il est recommandé de définir un bit "é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().