Fonctions personnalisées dans les composants principaux des formulaires adaptatifs

Cet article décrit la création de fonctions personnalisées avec le dernier composant principal de formulaire adaptatif, qui comporte les dernières fonctionnalités, telles que les suivantes :

Veillez à définir la dernière version de formulaire sur votre environnement de composant principal AEM Forms pour utiliser les dernières fonctionnalités des fonctions personnalisées.

Présentation

AEM Forms 6.5 comprend des fonctions JavaScript qui vous permettent de définir des règles métier complexes à l’aide de l’éditeur de règles. Bien qu’AEM Forms offre une variété de fonctions personnalisées prêtes à l’emploi, de nombreux cas d’utilisation nécessitent la définition de vos propres fonctions personnalisées à utiliser dans plusieurs formulaires. Ces fonctions personnalisées améliorent les fonctionnalités des formulaires en permettant la manipulation et le traitement des données saisies pour répondre à des besoins spécifiques. En outre, elles permettent une modification dynamique du comportement du formulaire en fonction de critères prédéfinis.

Utilisations des fonctions personnalisées uses-of-custom-function

Les avantages des fonctions personnalisées dans les composants principaux des formulaires adaptatifs sont les suivants :

Les fonctions personnalisées sont essentiellement des bibliothèques clientes ajoutées dans le fichier JavaScript. Une fois que vous avez créé une fonction personnalisée, elle est disponible dans l’éditeur de règles et peut être sélectionnée par l’utilisateur ou l’utilisatrice dans un formulaire adaptatif. Les fonctions personnalisées sont identifiées par les annotations JavaScript dans l’éditeur de règles.

Annotations JavaScript prises en charge pour la fonction personnalisée js-annotations

Les annotations JavaScript fournissent des métadonnées pour le code JavaScript. Cela comprend des commentaires commençant par des symboles spécifiques, par exemple /** et @. Les annotations fournissent des informations importantes sur les fonctions, variables et autres éléments du code. Le formulaire adaptatif prend en charge les annotations JavaScript suivantes pour les fonctions personnalisées :

Nom

Le nom est utilisé pour identifier la fonction personnalisée dans l’éditeur de règles d’un formulaire adaptatif. Les syntaxes suivantes sont utilisées pour nommer une fonction personnalisée :

Paramètre

Le paramètre est une liste d’arguments utilisés par des fonctions personnalisées. Une fonction peut prendre en charge plusieurs paramètres. Les syntaxes suivantes sont utilisées pour définir un paramètre dans une fonction personnalisée :

Le type de paramètre ne respecte pas la casse et les espaces ne sont pas autorisés dans le nom du paramètre.

<Parameter Description> contient des détails sur l’objectif du paramètre. Il peut contenir plusieurs mots.

Type de retour

Le type de retour spécifie le type de valeur que la fonction personnalisée renvoie après l’exécution. Les syntaxes suivantes sont utilisées pour définir un type de retour dans une fonction personnalisée :

Le type de retour ne respecte pas la casse.

Privée

La fonction personnalisée, déclarée comme privée, n’apparaît pas dans la liste des fonctions personnalisées de l’éditeur de règles d’un formulaire adaptatif. Par défaut, les fonctions personnalisées sont publiques. La syntaxe pour déclarer une fonction personnalisée en tant que privée est @private.

Instructions relatives à la création de fonctions personnalisées considerations

Pour répertorier les fonctions personnalisées dans l’éditeur de règles, vous pouvez utiliser l’un des formats suivants :

Instruction de fonction avec ou sans commentaires jsdoc

Vous pouvez créer une fonction personnalisée avec ou sans commentaires jsdoc.

    function functionName(parameters)
        {
            // code to be executed
        }

Si l’utilisateur ou l’utilisatrice n’ajoute aucune annotation JavaScript à la fonction personnalisée, elle est répertoriée dans l’éditeur de règles par son nom de fonction. Toutefois, il est recommandé d’inclure des annotations JavaScript pour améliorer la lisibilité des fonctions personnalisées.

Fonction arrow avec annotations ou commentaire JavaScript obligatoires

Vous pouvez créer une fonction personnalisée à l’aide d’une syntaxe de fonction arrow :

    /**
    * test function
    * @name testFunction
    * @param {string} a parameter description
    * @param {string=} b parameter description
    * @return {string}
    */
    testFunction = (a, b) => {
    return a + b;
    };
    /** */
    testFunction1=(a) => (return a)
    /** */
    testFunction2 = a => a + 100;

Si l’utilisateur ou l’utilisatrice n’ajoute aucune annotation JavaScript à la fonction personnalisée, celle-ci n’est pas répertoriée dans l’éditeur de règles d’un formulaire adaptatif.

Expression de fonction avec annotations ou commentaire JavaScript obligatoires

Pour répertorier les fonctions personnalisées dans l’éditeur de règles d’un formulaire adaptatif, créez des fonctions personnalisées au format suivant :

    /**
    * test function
    * @name testFunction
    * @param {string} input1 parameter description
    * @param {string=} input2 parameter description
    * @return {string}
    */
    testFunction = function(input1,input2)
        {
            // code to be executed
        }

Si l’utilisateur ou l’utilisatrice n’ajoute aucune annotation JavaScript à la fonction personnalisée, celle-ci n’est pas répertoriée dans l’éditeur de règles d’un formulaire adaptatif.

Conditions préalables pour créer une fonction personnalisée

Avant de commencer à ajouter une fonction personnalisée aux formulaires adaptatifs, assurez-vous que les logiciels suivants sont installés sur votre ordinateur :

Création d’une fonction personnalisée create-custom-function

Les étapes de création de fonctions personnalisées sont les suivantes :

Création d’une bibliothèque cliente à l’aide de l’archétype de projet AEM create-client-library-archetype

Vous pouvez ajouter des fonctions personnalisées en ajoutant une bibliothèque cliente au projet créé à l’aide de l’archétype de projet AEM.
Si vous disposez d’un projet , vous pouvez directement ajouter des fonctions personnalisées à votre projet local.

Après avoir créé un projet archétype ou utilisé un projet existant, créez une bibliothèque cliente. Pour créer une bibliothèque cliente, procédez comme suit :

Ajouter un dossier de bibliothèque cliente

Pour ajouter un nouveau dossier de bibliothèques clientes à votre [répertoire de projets AEM], procédez comme suit :

Ajouter des fichiers et des dossiers au dossier de bibliothèque cliente

Ajoutez ce qui suit au dossier de bibliothèque cliente ajouté :

Location is: [AEMaaCS project directory]/ui.apps/src/main/content/jcr_root/apps/experience-league/customclientlibs/

Incluez le nouveau dossier dans filter.xml  :

Créer et déployer des fonctions personnalisées via CRXDE create-add-custom-function

Si vous utilisez le dernier module complémentaire AEM Forms et Forms, vous pouvez créer une fonction personnalisée via CRXDE pour utiliser les dernières mises à jour des fonctions personnalisées. Pour cela, procédez comme suit :

Vous pouvez vous référer au dossier fonction personnalisée suivant. Téléchargez et installez ce dossier sur votre instance AEM.

Désormais, vous pouvez utiliser la fonction personnalisée dans votre formulaire adaptatif en ajoutant la bibliothèque cliente.

Ajout d’une bibliothèque cliente dans un formulaire adaptatif add-client-library

Une fois que vous avez déployé votre bibliothèque cliente dans votre environnement AEM Forms, utilisez ses fonctionnalités dans votre formulaire adaptatif. Pour ajouter la bibliothèque cliente dans votre formulaire adaptatif

Vous pouvez maintenant créer une règle pour utiliser des fonctions personnalisées dans l’éditeur de règles :

Maintenant, apprenons comment configurer et utiliser une fonction personnalisée à l’aide du service d’appel de l’éditeur de règles dans AEM Forms 6.5.

Utiliser une fonction personnalisée dans un formulaire adaptatif use-custom-functions

Dans un formulaire adaptatif, vous pouvez utiliser des fonctions personnalisées dans l’éditeur de règles.
Ajoutons le code suivant au fichier JavaScript (fichier Function.js) pour calculer l’âge en fonction de la date de naissance (AAAA-MM-JJ). Créez une fonction personnalisée calculateAge() qui prend la date de naissance comme entrée et renvoie l’âge :

    /**
        * Calculates Age
        * @name calculateAge
        * @param {object} field
        * @return {string}
    */

    function calculateAge(field) {
    var dob = new Date(field);
    var now = new Date();

    var age = now.getFullYear() - dob.getFullYear();
    var monthDiff = now.getMonth() - dob.getMonth();

    if (monthDiff < 0 || (monthDiff === 0 && now.getDate() < dob.getDate())) {
    age--;
    }

    return age;
    }

Dans l’exemple ci-dessus, lorsque la personne saisit la date de naissance au format (AAAA-MM-JJ), la fonction personnalisée calculateAge est appelée et renvoie l’âge.

Prévisualisons le formulaire pour observer comment les fonctions personnalisées sont implémentées par le biais de l’éditeur de règles :

Prise en charge des fonctions asynchrones dans les fonctions personnalisées support-of-async-functions

Les fonctions personnalisées asynchrones n’apparaissent pas dans la liste de l’éditeur de règles. Cependant, il est possible d’appeler des fonctions asynchrones dans des fonctions personnalisées créées à l’aide d’expressions de fonction synchrones.

Consultez le code ci-dessous pour découvrir comment nous pouvons appeler des fonctions asynchrones à l’aide de fonctions personnalisées :

    async function asyncFunction() {
    const response = await fetch('https://petstore.swagger.io/v2/store/inventory');
    const data = await response.json();
    return data;
    }

    /**
    * callAsyncFunction
    * @name callAsyncFunction callAsyncFunction
    */
    function callAsyncFunction() {
    asyncFunction()
        .then(responseData => {
        console.log('Response data:', responseData);
        })
        .catch(error => {
         console.error('Error:', error);
    });
}

Dans l’exemple ci-dessus, la fonction asyncFunction est une asynchronous function. Elle effectue une opération asynchrone en effectuant une requête GET vers https://petstore.swagger.io/v2/store/inventory. Elle attend la réponse avec await, analyse le corps de la réponse en tant que JSON à l’aide de response.json(), puis renvoie les données. La fonction callAsyncFunction est une fonction personnalisée synchrone qui appelle la fonction asyncFunction et affiche les données de réponse dans la console. Bien que la fonction callAsyncFunction soit synchrone, elle appelle la fonction asynchrone asyncFunction et gère son résultat avec des instructions then et catch.

Pour en voir le fonctionnement, nous allons ajouter un bouton et créer une règle pour le bouton qui appelle la fonction asynchrone lors d’un clic sur un bouton.

Reportez-vous à l’illustration de la fenêtre de console ci-dessous pour démontrer que lorsque la personne clique sur le bouton Fetch, la fonction personnalisée callAsyncFunction est appelée, qui à son tour appelle une fonction asynchrone asyncFunction. Observez la fenêtre de la console pour voir la réponse lorsque vous cliquez sur le bouton :

Explorons les fonctionnalités des fonctions personnalisées.

Diverses fonctionnalités des fonctions personnalisées

Vous pouvez utiliser les fonctions personnalisées pour ajouter des fonctionnalités personnalisées aux formulaires. Ces fonctions prennent en charge diverses fonctionnalités, telles que l’utilisation de champs spécifiques, l’utilisation de champs globaux ou la mise en cache. Cette flexibilité vous permet de personnaliser les formulaires en fonction des besoins de votre entreprise.

Objets Field et Globals dans les fonctions personnalisées support-field-and-global-objects

Les objets Field font référence aux composants ou éléments individuels d’un formulaire, tels que les champs de texte et les cases à cocher. L’objet Globals contient des variables en lecture seule, telles que l’instance de formulaire, l’instance de champ cible et des méthodes permettant de modifier le formulaire dans des fonctions personnalisées.

Découvrez comment les fonctions personnalisées utilisent des objets Field et Globals à l’aide d’un formulaire Contact Us utilisant différents cas d’utilisation.

Cas d’utilisation  : afficher un panneau à l’aide de la règle SetProperty

Ajoutez le code suivant dans la fonction personnalisée, comme expliqué dans la section create-custom-function, pour définir le champ de formulaire sur Required.

    /**
    * enablePanel
    * @name enablePanel
    * @param {object} field1
    * @param {object} field2
    * @param {scope} globals
    */

    function enablePanel(field1,field2, globals)
    {
       if(globals.functions.validate(field1).length === 0)
       {
       globals.functions.setProperty(field2, {visible: true});
       }
    }

Dans cet exemple, la validation du panneau personaldetails se produit lorsque vous cliquez sur le bouton. Si aucune erreur n’est détectée dans le panneau, un autre panneau, le panneau feedback, devient visible lorsque l’utilisateur ou l’utilisatrice clique sur le bouton.

Créons une règle pour le bouton Next, qui valide le panneau personaldetails et rend le panneau feedback visible lorsque l’utilisateur ou l’utilisatrice clique sur le bouton Next.

Reportez-vous à l’illustration ci-dessous pour montrer où le panneau personaldetails est validé en cliquant sur le bouton Next. Si tous les champs personaldetails sont validés, le panneau feedback devient visible.

Si des erreurs sont présentes dans les champs du panneau personaldetails, elles s’affichent au niveau du champ lorsque vous cliquez sur le bouton Next et le panneau feedback reste invisible.

Cas d’utilisation  : valider le champ

Ajoutez le code suivant dans la fonction personnalisée, comme expliqué dans la section create-custom-function, pour valider le champ.

    /**
    * validateField
    * @name validateField
    * @param {object} field
    * @param {scope} globals
    */
    function validateField(field,globals)
    {

        globals.functions.validate(field);

    }

Dans cet exemple, un modèle de validation personnalisé est appliqué au champ contact. Les utilisateurs et utilisatrices doivent saisir un numéro de téléphone commençant par 10 suivi de 8 chiffres. Si l’utilisateur ou l’utilisatrice saisit un numéro de téléphone qui ne commence pas par 10 ou qui contient plus ou moins de 8 chiffres, un message d’erreur de validation s’affiche lorsque l’utilisateur ou l’utilisatrice clique sur le bouton :

L’étape suivante consiste à créer une règle pour le bouton Next qui valide le champ contact au moment du clic sur le bouton.

Reportez-vous à l’illustration ci-dessous pour montrer que si l’utilisateur ou l’utilisatrice saisit un numéro de téléphone qui ne commence pas par 10, un message d’erreur s’affiche au niveau du champ :

Si l’utilisateur ou l’utilisatrice saisit un numéro de téléphone valide et que tous les champs du panneau personaldetails sont validés, le panneau feedback s’affiche à l’écran :

Cas d’utilisation  : réinitialiser un panneau

Ajoutez le code suivant dans la fonction personnalisée, comme expliqué dans la section create-custom-function, pour réinitialiser le panneau.

    /**
    * resetField
    * @name  resetField
    * @param {string} input1
    * @param {object} field
    * @param {scope} globals
    */
    function  resetField(field,globals)
    {

        globals.functions.reset(field);

    }

Dans cet exemple, le panneau personaldetails se réinitialise lorsque vous cliquez sur le bouton Clear. L’étape suivante consiste à créer une règle pour le bouton Clear qui réinitialise le panneau au moment du clic sur le bouton.

Consultez l’illustration ci-dessous pour afficher que si l’utilisateur ou l’utilisatrice clique sur le bouton clear, le panneau personaldetails se réinitialise :

Cas d’utilisation  : afficher un message personnalisé au niveau du champ et marquer le champ comme non valide

Vous pouvez utiliser la fonction markFieldAsInvalid() pour définir un champ comme non valide et définir un message d’erreur personnalisé au niveau du champ. La valeur fieldIdentifier peut être fieldId, field qualifiedName ou field dataRef. La valeur de l’objet nommé option peut être {useId: true}, {useQualifiedName: true} ou {useDataRef: true}.
Les syntaxes utilisées pour marquer le champ comme non valide et définir un message personnalisé sont les suivantes :

Ajoutez le code suivant dans la fonction personnalisée, comme expliqué dans la section create-custom-function, pour activer le message personnalisé au niveau du champ.

    /**
    * customMessage
    * @name customMessage
    * @param {object} field
    * @param {scope} globals
    */
    function customMessage(field, globals) {
    const minLength = 15;
    const comments = field.$value.trim();
    if (comments.length < minLength) {
        globals.functions.markFieldAsInvalid(field.$id, "Comments must be at least 15 characters long.", { useId: true });
    }
}

Dans cet exemple, si l’utilisateur ou l’utilisatrice saisit moins de 15 caractères dans la zone de texte des commentaires, un message personnalisé s’affiche au niveau du champ.

L’étape suivante consiste à créer une règle pour le champ comments :

Consultez la démonstration ci-dessous pour voir que la saisie de commentaires négatifs dans le champ comments déclenche l’affichage d’un message personnalisé au niveau du champ :

Si l’utilisateur ou l’utilisatrice saisit plus de 15 caractères dans la zone de texte des commentaires, le champ est validé et le formulaire est envoyé :

Cas d’utilisation  : envoyer des données modifiées au serveur

La ligne de code suivante :
globals.functions.submitForm(globals.functions.exportData(), false); est utilisée pour envoyer les données de formulaire après la manipulation.

Ajoutez le code suivant dans la fonction personnalisée, comme expliqué dans la section create-custom-function, pour envoyer les données manipulées sur le serveur :

    /**
    * submitData
    * @name submitData
    * @param {object} field
    * @param {scope} globals
    */
    function submitData(globals)
    {

    var data = globals.functions.exportData();
    if(!data.comments) {
    data.comments = 'NA';
    }
    console.log('After update:{}',data);
    globals.functions.submitForm(data, false);
    }

Dans cet exemple, si l’utilisateur ou l’utilisatrice laisse la zone de texte comments vide, NA est envoyé au serveur lors de l’envoi du formulaire.

Créez maintenant une règle pour le bouton Submit qui envoie les données :

Reportez-vous à l’illustration console window ci-dessous pour montrer que si l’utilisateur ou l’utilisatrice laisse la zone de texte comments vide, la valeur NA est envoyée au serveur :

Vous pouvez également vérifier la fenêtre de la console pour visualiser les données envoyées au serveur :

Prise en charge de la mise en cache d’une fonction personnalisée

Les formulaires adaptatifs implémentent la mise en cache pour les fonctions personnalisées afin d’améliorer le temps de réponse lors de la récupération de la liste des fonctions personnalisées dans l’éditeur de règles. Un message Fetched following custom functions list from cache apparaît dans le fichier error.log.

Si les fonctions personnalisées sont modifiées, la mise en cache est invalidée et elle est analysée.

Résolution des problèmes troubleshooting

Considérations