Fonctions JavaScript dans les formulaires d’enquête

La fonction pulldata("@javascript") peut servir à appeler des fonctions JavaScript, ce qui vous permet d’utiliser une logique et des techniques avancées qui dépassent ce qui est possible avec XLSForm seulement.

Vous pouvez gérer et mettre à jour les fonctions JavaScript sur l’onglet Scripts de Survey123 Connect. Cet onglet vous permet de créer un fichier JavaScript, d’examiner le code et de tester la fonction. Cet onglet ne remplace pas complètement l’environnement de développement intégré (IDE), dans lequel vous pouvez valider le code et analyser les pratiques conseillées pour faciliter le développement des fonctions JavaScript, mais il a été conçu pour vous aider à intégrer ces fonctions dans Survey123.

Outils de script dans Survey123 Connect

Les outils suivants sont disponibles dans le menu de l’onglet Scripts de Survey123 Connect :

• Script files (Fichiers de script) : affichez tous les fichiers JavaScript situés dans le dossier Scripts d’une enquête. Sélectionnez un fichier à afficher et à mettre à jour.
• Open scripts folder (Ouvrir le dossier des scripts) : lancez le navigateur de fichiers à l’emplacement du dossier Scripts d’une enquête.
• New script file (Nouveau fichier de script) : créez un fichier de script dans le dossier Scripts d’une enquête. Entrez le nom de fichier, puis cliquez sur Create (Créer).
• Sélectionner une fonction : mettez en évidence la première fonction dans le fichier ouvert et présentez les paramètres à tester.
• Enregistrer : enregistrez les modifications apportées au fichier ouvert.
• Launch external editor (Lancer l’éditeur externe) : lancez l’environnement de développement intégré (IDE) JavaScript par défaut du système avec le fichier ouvert.

Cliquez sur l’outil Sélectionner une fonction pour tester le comportement de la première fonction dans le fichier en entrant des valeurs pour chaque paramètre et en affichant la sortie. Une fois que vous avez fini d’utiliser la fonction, vous pouvez copier l’instruction pulldata présentée ici et la coller dans le XLSForm. Si vous êtes connecté à votre organisation, cliquez avec le bouton droit sur l’un des paramètres et sélectionnez Paste token (Coller le jeton), si nécessaire.

Remarque :

Les erreurs de syntaxe de base sont indiquées dans l’onglet Scripts (Scripts) avec un indicateur d’erreur en regard du numéro de ligne. Le traitement des erreurs doit être implémenté dans la fonction JavaScript. La sortie de la console s’affiche sur l’onglet Scripts ; en incluant les messages de la console dans votre fonction, vous pouvez donc voir les erreurs, les avertissements et les messages d’information avec la sortie.

Syntaxe de base

Vous pouvez appeler des fonctions JavaScript personnalisées pour renvoyer des valeurs. Utilisez la syntaxe suivante pour appeler des fonctions JavaScript personnalisées avec la fonction pulldata("@javascript") :

pulldata("@javascript", "yourJSFile.js", "yourFunction", "parameter1", "parameter2")

Vous devez stocker vos fichiers JavaScript personnalisés dans un dossier nommé scripts dans le répertoire de l’enquête. Dans l’exemple ci-dessus, la fonction JavaScript attend deux paramètres, mais vous pouvez ajouter autant de paramètres de fonction que vous le souhaitez.

Vous pouvez utiliser la fonction pulldata("@json") pour extraire des valeurs spécifiques d’un objet JSON produit par une fonction JavaScript. Pour plus d’informations, voir Extraire une valeur d’un objet JSON.

Parfois, en particulier si vous utilisez JavaScript pour accéder aux services Web et services ArcGIS sécurisés, vous pouvez avoir besoin d'accéder aux propriétés de l'appareil et de l'utilisateur. La fonction pulldata("@property") permet d’extraire des informations sur les appareils à partir desquels les réponses aux enquêtes sont envoyées, ainsi que sur les utilisateurs connectés qui envoient ces réponses. Pour plus d’informations, voir Propriétés concernant l’appareil et l’utilisateur.

Conseil :

Pour les requêtes spatiales et attributaires sur les couches d’entités ArcGIS, envisagez d’utiliser la fonction pulldata("@layer") au lieu de la fonction pulldata("@javascript"). La syntaxe pulldata("@layer") a été conçue spécifiquement pour les requêtes de couche d’entités et est prise en charge pour les enquêtes publiques. Pour plus d’informations, reportez-vous à la rubrique Interroger une couche d’entités.

Répétitions

Vous pouvez transmettre toutes les valeurs via une répétition à vos fonctions JavaScript. La fonction pulldata("@javascript") prend en charge deux styles d’implémentation pour extraire les valeurs d’une répétition. Celui qui doit être utilisé varie selon que vous souhaitez ou non que la fonction JavaScript interagisse avec un ou plusieurs champs dans une répétition.

Si une question provenant d’une répétition est transmise en tant que paramètre de fonction, la fonction JavaScript reçoit une matrice de valeurs à partir de la question spécifiée, comme suit :

pulldata("@javascript", "yourJSFile.js", "yourFunction", ${question1})

Si un nom de répétition est transmis en tant que paramètre de fonction, la fonction JavaScript reçoit ce paramètre en tant que matrice de lignes de toutes les valeurs dans la répétition, comme suit :

pulldata("@javascript", "yourJSFile.js", "yourFunction", ${repeat1}, "question1")

Chacun de ces styles produit un objet JSON avec des questions individuelles sous forme de propriétés de cet objet.

Remarque :

L’accès à ces valeurs dans les répétitions avec pulldata("@javascript") n’est pas pris en charge dans l’application Web Survey123. Vous pouvez collecter des valeurs pour une seule question dans une répétition dans l’application Web en utilisant join() pour convertir la liste de valeurs en chaîne de valeurs séparées par des caractères et fractionner les valeurs dans la fonction JavaScript.

Depuis Survey123 version 3.14, les valeurs vides transmises via une fonction JavaScript peuvent maintenant renvoyer undefined ou null. Vous devez ainsi écrire des fonctions JavaScript pour tenir compte de la possibilité d’une valeur undefined.

Limitations connues

Voici les limitations connues lorsque vous utilisez des fonctions JavaScript dans les formulaires d’enquête :

• DOM (Document Object Model) n’est pas pris en charge.
• Les structures telles que JQuery, Ember et Angular ne sont pas prises en charge.
• Vous ne pouvez pas accéder aux fichiers locaux.
• Les appels asynchrones ne sont pas pris en charge.
• Les fonctions JavaScript sont uniquement prises en charge dans les formulaires renseignés par des utilisateurs de la même organisation en tant qu’auteur du formulaire.
• Les fonctions JavaScript ne sont pas prises en charge pour les enquêtes publiques.
• Une fonction pulldata("@javascript") ne peut pas être appelée à l’intérieur d’une fonction pulldata("@json") dans l’application Web Survey123.