Documentation AEM 6.5 Guide de l’utilisateur

Fonctions personnalisées dans les composants principaux des formulaires adaptatifs

Dernière mise à jour : 19 novembre 2024

S'applique à :
Experience Manager 6.5

Créé pour :

Administration
Utilisateur ou utilisatrice
Développeur

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 :

Fonction de mise en cache des fonctions personnalisées
Prise en charge des objets de champ et d’objet de portée globale pour les fonctions personnalisées
Prise en charge des fonctionnalités JavaScript modernes telles que les fonctions let et arrow (prise en charge d’ES10)

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.

Version	Lien de l’article
AEM 6.5	Cet article
AEM as a Cloud Service	Cliquez ici

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

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

Gestion des données : les fonctions personnalisées gèrent et traitent les données saisies dans les champs de formulaires.
Traitement des données : les fonctions personnalisées aident à traiter les données saisies dans les champs de formulaires.
Validation des données : les fonctions personnalisées vous permettent d’effectuer des vérifications personnalisées sur les entrées de formulaire et de fournir des messages d’erreur spécifiés.
Comportement dynamique : les fonctions personnalisées vous permettent de contrôler le comportement dynamique de vos formulaires en fonction de conditions spécifiques. Vous pouvez, par exemple, afficher/masquer des champs, modifier les valeurs de champ ou ajuster dynamiquement la logique du formulaire.
Intégration : vous pouvez utiliser des fonctions personnalisées pour intégrer des API ou des services externes. Cela permet de récupérer des données provenant de sources externes, d’envoyer des données à des points d’entrée Rest externes ou d’effectuer des actions personnalisées basées sur des événements externes.

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

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 :

@name [functionName] <Function Name>
@function [functionName] <Function Name>
@func [functionName] <Function Name>

NOTE

[functionName] est le nom de la fonction. Les espaces ne sont pas autorisés.
<Function Name> est le nom d’affichage de la fonction dans l’éditeur de règles des formulaires adaptatifs.
Si le nom de la fonction est identique au nom de la fonction elle-même, vous pouvez omettre [functionName] dans la syntaxe.

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 :

@param {type} name <Parameter Description>
@argument {type} name <Parameter Description>
@arg {type} name <Parameter Description>

{type} représente le type de paramètre. Les types de paramètre autorisés sont les suivants :
- Chaîne : représente une seule valeur de chaîne.
- Nombre : représente une seule valeur numérique.
- Booléen : représente une seule valeur booléenne (true ou false).
- Chaîne[] : représente un tableau de valeurs de chaîne.
- Nombre[] : représente un tableau de valeurs numériques.
- Booléen[] : représente un tableau de valeurs booléennes.
- Date : représente une seule valeur de date.
- Date[] : représente un tableau de valeurs de date.
- array : représente un tableau générique contenant des valeurs de différents types.
- object : représente l’objet de formulaire transmis à une fonction personnalisée au lieu de transmettre directement sa valeur.
- scope : représente l’objet globals, qui contient des variables en lecture seule telles que des instances de formulaire, des instances de champ cible et des méthodes permettant d’effectuer des modifications dans les fonctions personnalisées. Il est déclaré comme dernier paramètre dans les annotations JavaScript et n’est pas visible par l’éditeur de règles d’un formulaire adaptatif. Le paramètre scope accède à l’objet du formulaire ou du composant pour déclencher la règle ou l’événement requis pour le traitement du formulaire. Pour plus d’informations sur l’objet Globals et comment l’utiliser, cliquez ici.

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 :

@return {type}
@returns {type}
{type} représente le type de retour de la fonction. Les types de retour autorisés sont les suivants :
Chaîne : représente une seule valeur de chaîne.
Nombre : représente une seule valeur numérique.
Booléen : représente une seule valeur booléenne (true ou false).
string[] : représente un tableau de valeurs de chaîne.
number[] : représente un tableau de valeurs numériques.
boolean[] : représente un tableau de valeurs booléennes.
Date : représente une seule valeur de date.
date[] : représente un tableau de valeurs de date.
array : représente un tableau générique contenant des valeurs de différents types.
object : représente l’objet de formulaire au lieu de sa valeur directement.

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

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 :

Éditeur de texte brut (IDE) : bien que tout éditeur de texte brut puisse fonctionner, un environnement de développement intégré (IDE) comme Microsoft Visual Studio Code offre des fonctionnalités avancées pour faciliter la modification.
Git : ce système de gestion de versions est nécessaire pour gérer les modifications de code. Si vous ne l’avez pas installé, téléchargez-le à partir de https://git-scm.com.

Création d’une fonction personnalisée

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

Créez une bibliothèque côté client à l’aide de l’archétype de projet AEM et ajoutez une fonction personnalisée,
OU
Créez des fonctions personnalisées via CRXDE.
Ajout d’une bibliothèque cliente à un formulaire adaptatif
Utilisation d’une fonction personnalisée dans un formulaire adaptatif

Création d’une bibliothèque cliente à l’aide de l’archétype de projet AEM

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 :

Ouvrez le [répertoire de projets AEM] dans un éditeur.
Localisez ui.apps.
Ajoutez un nouveau dossier. Par exemple, créez un dossier nommé experience-league.
Accédez au dossier /experience-league/ et ajoutez un ClientLibraryFolder. Par exemple, créez un dossier de bibliothèque cliente nommé customclientlibs.

L’emplacement est : [AEM project directory]/ui.apps/src/main/content/jcr_root/apps/.

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

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

.content.xml approuvé
Fichier js.txt
Dossier js

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

Dans .content.xml, ajoutez les lignes de code suivantes :

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
jcr:primaryType="cq:ClientLibraryFolder"
categories="[customfunctionscategory]"/>

NOTE

Vous pouvez choisir n’importe quel nom pour les propriétés client library folder et categories.

Dans js.txt, ajoutez les lignes de code suivantes :
#base=js function.js

Dans le dossier js, ajoutez le fichier javascript en tant que function.js qui comprend les fonctions personnalisées :

/**
    * 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;
}

Enregistrez les fichiers.

Structure de dossier de fonction personnalisée

Incluez le nouveau dossier dans filter.xml :

Accédez au fichier /ui.apps/src/main/content/META-INF/vault/filter.xml dans votre [répertoire de projet AEMaaCS].
Ouvrez le fichier et ajoutez la ligne suivante à la fin :

<filter root="/apps/experience-league" />
Enregistrez le fichier.
Créez le dossier de bibliothèque cliente nouvellement créé dans votre environnement AEM en suivant les étapes décrites dans la section Comment créer une section.

Créer et déployer des fonctions personnalisées via CRXDE

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 :

Connectez-vous à http://server:port/crx/de/index.jsp#.
Créez un dossier sous le dossier /apps. Par exemple, créez un dossier nommé experience-league.
Enregistrez vos modifications.
Accédez au dossier créé et créez un noeud de type cq:ClientLibraryFolder sous clientlibs.
Accédez au dossier clientlibs nouvellement créé et ajoutez les propriétés allowProxy et categories :

NOTE
Vous pouvez utiliser le nom de votre choix à la place de customfunctionsdemo.
Enregistrez vos modifications.
Créez un dossier appelé js sous le dossier clientlibs.
Créez un fichier JavaScript appelé functions.js sous le dossier js.
Créez un fichier appelé js.txt sous le dossier clientlibs.
Enregistrez vos modifications.
La structure de dossiers créée ressemble à ce qui suit :

Double-cliquez sur le fichier functions.js pour ouvrir l’éditeur. Le fichier comprend le code de la fonction personnalisée.
Ajoutons le code suivant au fichier JavaScript pour calculer l’âge en fonction de la date de naissance (AAAA-MM-JJ).

    /**
         * Calculates Age
         * @name calculateAge
         * @return {string}
    */

    function calculateAge(dateOfBirthString) {
    var dob = new Date(dateOfBirthString);
    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;
    }

Enregistrez function.js.
Accédez à js.txt et ajoutez le code suivant :
#base=js functions.js
Enregistrez le fichier js.txt.

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

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

Ouvrez votre formulaire en mode d’édition. Pour ouvrir un formulaire en mode d’édition, sélectionnez-le et cliquez sur Modifier.
Ouvrez l’explorateur de contenu, puis sélectionnez le composant Conteneur de guide de votre formulaire adaptatif.
Cliquez sur l’icône des propriétés du conteneur de guide. La boîte de dialogue du conteneur de formulaires adaptatifs s’ouvre.
Ouvrez l’onglet De base et sélectionnez le nom de la catégorie de bibliothèque cliente dans la liste déroulante (dans ce cas, sélectionnez customfunctionscategory).
Cliquez sur Terminé.

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

Ajout de la bibliothèque cliente de fonction personnalisée

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

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.

Fonction personnalisée Calculate Age (calcul de l’âge) dans l’éditeur de règles

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

Fonction personnalisée Calculate Age dans la prévisualisation de formulaire de l’éditeur de règles

NOTE

Vous pouvez vous référer au dossier de fonctions personnalisées suivant. Téléchargez et installez ce dossier dans votre instance AEM à l’aide du Gestionnaire de modules.

Prise en charge des fonctions asynchrones dans les fonctions personnalisées

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.

Fonction personnalisée synchrone et asynchrone

NOTE

L’avantage de l’appel de fonctions asynchrones dans les fonctions personnalisées est que les fonctions asynchrones permettent l’exécution simultanée de plusieurs tâches, avec le résultat de chaque fonction utilisée dans les fonctions personnalisées.

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.

Création d’une règle pour la fonction asynchrone

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 :

Fenêtre de console

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

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.

NOTE

Le paramètre param {scope} globals doit être le dernier paramètre et il ne s’affiche pas dans l’éditeur de règles d’un formulaire adaptatif.

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.

Formulaire de contact

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});
       }
    }

NOTE

Vous pouvez configurer les propriétés de champ à l’aide des propriétés disponibles situées dans [form-path]/jcr:content/guideContainer.model.json.
Les modifications apportées au formulaire à l’aide de la méthode setProperty de l’objet Globals sont de nature asynchrone et ne sont pas reflétées lors de l’exécution de la fonction personnalisée.

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.

Définir la propriété

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.

Définir la prévisualisation du formulaire de propriété

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.

Définir la prévisualisation du formulaire de propriété

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);

    }

NOTE

Si aucun argument n’est transmis dans la fonction validate(), le formulaire est validé.

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 :

Modèle de validation d’adresse e-mail

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.

Modèle de validation

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 :

Modèle de validation d’adresse e-mail

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 :

Modèle de validation d’adresse e-mail

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);

    }

NOTE

Si aucun argument n’est transmis dans la fonction reset(), le formulaire est validé.

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.

Bouton Effacer

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 :

Réinitialiser le formulaire

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 :

globals.functions.markFieldAsInvalid(field.$id,"[custom message]",{useId: true});
globals.functions.markFieldAsInvalid(field.$qualifiedName, "[custom message]", {useQualifiedName: true});
globals.functions.markFieldAsInvalid(field.$dataRef, "[custom message]", {useDataRef: true});

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 :

Marquer le champ comme non valide

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 :

Formulaire de prévisualisation Marquer le champ comme non valide

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é :

Formulaire de prévisualisation Marquer le champ comme valide

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.

Le premier argument est celui des données à envoyer.
Le deuxième argument indique si le formulaire doit être validé avant envoi. Il est optional et est défini sur true par défaut.
Le troisième argument est le contentType de l’envoi, qui est également facultatif avec la valeur par défaut multipart/form-data. Les autres valeurs peuvent être application/json et application/x-www-form-urlencoded.

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 :

Envoi de 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 :

Envoi de données dans la fenêtre de console

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

Analyse des données dans la fenêtre de console

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.

Fonction personnalisée avec prise en charge du cache

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

L’utilisateur ou l’utilisatrice doit s’assurer que la version du composant principal et de la spécification est définie sur la dernière version. Toutefois, pour les projets et formulaires AEM existants, d’autres étapes sont à suivre :
- Pour le projet AEM, l’utilisateur ou l’utilisatrice doit remplacer toutes les instances de submitForm('custom:submitSuccess', 'custom:submitError') par submitForm() et déployer le projet.
- Pour les formulaires existants, si les gestionnaires d’envoi personnalisés ne fonctionnent pas correctement, l’utilisateur ou l’utilisatrice doit ouvrir et enregistrer la règle submitForm sur le bouton Envoyer à l’aide de l’éditeur de règles. Cette action remplace la règle existante de submitForm('custom:submitSuccess', 'custom:submitError') par submitForm() dans le formulaire.
Si le fichier JavaScript contenant du code pour les fonctions personnalisées comporte une erreur, les fonctions personnalisées ne sont pas répertoriées dans l’éditeur de règles d’un formulaire adaptatif. Pour vérifier la liste des fonctions personnalisées, vous pouvez accéder au fichier error.log correspondant à l’erreur. En cas d’erreur, la liste des fonctions personnalisées apparaît vide :

En l’absence d’erreur, la fonction personnalisée est récupérée et apparaît dans le fichier error.log. Un message Fetched following custom functions list apparaît dans le fichier error.log :

Considérations

Les parameter type et return type ne prennent pas en charge None.
Les fonctions qui ne sont pas prises en charge dans la liste des fonctions personnalisées sont les suivantes :
- Fonctions du générateur
- Fonctions asynchrones/d’attente
- Définitions des méthodes
- Méthodes de classe
- Paramètres par défaut
- Paramètres REST

recommendation-more-help

Fonctions personnalisées dans les composants principaux des formulaires adaptatifs

Présentation

Utilisations des fonctions personnalisées

Annotations JavaScript prises en charge pour la fonction personnalisée

Nom

Paramètre

Type de retour

Privée

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

Instruction de fonction avec ou sans commentaires jsdoc

Fonction arrow avec annotations ou commentaire JavaScript obligatoires

Expression de fonction avec annotations ou commentaire JavaScript obligatoires

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

Création d’une fonction personnalisée

Création d’une bibliothèque cliente à l’aide de l’archétype de projet AEM

Créer et déployer des fonctions personnalisées via CRXDE

Ajout d’une bibliothèque cliente dans un formulaire adaptatif

Utiliser une fonction personnalisée dans un formulaire adaptatif

Prise en charge des fonctions asynchrones dans les fonctions personnalisées

Diverses fonctionnalités des fonctions personnalisées

Objets Field et Globals dans les fonctions personnalisées

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

Cas d’utilisation : valider le champ

Cas d’utilisation : réinitialiser un panneau

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

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

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

Résolution des problèmes

Considérations

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