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 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 commandes 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 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 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é génère 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 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 d'avoir à définir un objet et une fonction de rappel Action. Si vous devez d'abord créer l'URL ou effectuer d'autres étapes avant de l'ouvrir, définissez un Action et utilisez plutôt setOnClickOpenLinkAction().

• 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 à la fonction de rappel différents paramètres.

• Faites en sorte que vos fonctions de rappel soient simples. Pour que les modules complémentaires restent réactifs, le service de carte limite les fonctions de rappel à un maximum de 30 secondes de temps d'exécution. Si l'exécution prend plus de temps, l'UI de votre module complémentaire risque de ne pas mettre à jour correctement l'affichage de sa fiche en réponse à Action .

• Si l'état des données d'un backend tiers change en raison d'une interaction utilisateur avec l'UI de votre module complémentaire, il est recommandé que le module complémentaire définisse 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().