Créer des fiches interactives

La plupart des modules complémentaires, en plus de la présentation des données, 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

Dans la plupart des cas, 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 complémentaires.

Dans la plupart des cas, vous pouvez suivre cette procédure générale pour configurer un widget afin d'effectuer 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 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 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)
        .build();      // Don't forget to build the response!
  }

Concevoir des interactions efficaces

Lorsque vous créez 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 widgets 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 suivre d'autres étapes avant d'ouvrir l'URL, définissez un élément Action et utilisez plutôt setOnClickOpenLinkAction().

• 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.

• 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.

• Simplifiez vos fonctions de rappel. Pour que les modules complémentaires restent responsifs, le service de carte limite les fonctions de rappel à un maximum de 30 secondes d'exécution. Si l'exécution prend plus de temps, il se peut que l'interface utilisateur de votre module complémentaire ne met pas à jour l'affichage de sa carte correctement en réponse à Action .

• Si l'état des données sur un backend tiers change à la suite d'une interaction utilisateur avec l'UI du module complémentaire, nous vous recommandons 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().