Création de fiches interactives

La plupart des modules complémentaires, en plus de présenter des données, nécessitent que l'utilisateur saisisse des informations. Lorsque vous créez un module complémentaire basé sur des cartes, 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 il a besoin ou 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 mettant en œuvre le comportement requis dans une fonction de rappel. Pour en savoir plus, consultez Actions complémentaires.

Dans la plupart des cas, vous pouvez suivre cette procédure générale pour configurer un widget et y effectuer une action spécifique:

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 après un clic. Le clic déclenche la fonction de rappel notifyUser() avec un argument qui spécifie le texte de la notification. Le renvoi d'un objet ActionResponse créé 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)
            .setType(CardService.NotificationType.INFO))
        .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 le gestionnaire de widgets setOpenLink() lorsque vous avez 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 les comportements 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 des paramètres différents.

• Simplifiez vos fonctions de rappel. Pour que les modules complémentaires restent responsifs, le service Card limite les fonctions de rappel à un maximum de 30 secondes d'exécution. Si l'exécution prend plus de temps, l'interface utilisateur du module complémentaire risque de ne pas mettre à jour l'affichage de la carte correctement en réponse à la requête Action .

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