Exemples de développement et d’utilisation d’une fonction personnalisée

Cet article fournit des exemples détaillés de fonctions personnalisées pour un formulaire adaptatif basé sur les composants principaux, offrant ainsi des informations précieuses sur leur implémentation efficace dans divers scénarios. Les fonctions personnalisées sont utilisées dans l’éditeur de règles d’un AEM Forms. Elles permettent aux développeurs et aux développeuses de définir et de contrôler la logique qui régit le comportement des formulaires.
Cet article explore différentes implémentations des fonctions personnalisées, en montrant comment elles peuvent être utilisées pour personnaliser les formulaires afin de répondre à des besoins spécifiques et d’améliorer les fonctionnalités globales.

Remplir les options de liste déroulante à l’aide de fonctions personnalisées

L’éditeur de règles dans les composants principaux ne prend pas en charge la propriété Définir les options pour renseigner les options de liste déroulante de manière dynamique au moment de l’exécution. Cependant, vous pouvez remplir les options de liste déroulante à l’aide de fonctions personnalisées, qui vous permettent de récupérer des options en fonction d’une logique spécifique. Les fonctions personnalisées offrent une plus grande flexibilité et un meilleur contrôle sur la façon dont les options de liste déroulante sont renseignées, améliorant ainsi l’expérience utilisateur.

Pour renseigner les options de la liste déroulante à l’aide d’une fonction personnalisée, ajoutez le code suivant comme décrit dans la section create-custom-function :

    /**
    * @name setEnums
    * @returns {string[]}
    **/
    function setEnums() {
    return ["0","1","2","3","4","5","6"];
    }

    /**
    * @name setEnumNames
    * @returns {string[]}
    **/
    function setEnumNames() {
    return ["Sunday","Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
    }

Dans le code ci-dessus, setEnums est utilisé pour définir la propriété enum et setEnumNames est utilisé pour définir la propriété enumNames de la liste déroulante.

Créons une règle pour le bouton Next, qui définit la valeur de l’option de liste déroulante lorsque l’utilisateur clique sur le bouton Next :

Reportez-vous à l’illustration ci-dessous pour indiquer où les options de la liste déroulante sont définies lorsque vous cliquez sur le bouton Afficher :

Afficher un panneau à l’aide de la règle de SetProperty

Découvrez comment les fonctions personnalisées utilisent des objets de champ et globaux à l’aide d’un formulaire Contact Us.

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.

Valider le champ

Découvrez comment les fonctions personnalisées utilisent des objets de champ et globaux pour valider le champ à l’aide d’un formulaire Contact Us.

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 :

Réinitialisation d’un panneau

Découvrez comment les fonctions personnalisées utilisent les objets de champ et globaux pour réinitialiser le champ à l’aide d’un formulaire Contact Us.

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 :

Pour afficher un message personnalisé au niveau du champ et marquer le champ comme non valide

Découvrez comment les fonctions personnalisées utilisent des objets de champ et globaux pour afficher un message personnalisé au niveau du champ et marquer le champ comme non valide à l’aide d’un formulaire Contact Us.

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

Envoyer les données modifiées au serveur

Découvrez comment les fonctions personnalisées utilisent des objets de champ et globaux pour envoyer des données manipulées au serveur à l’aide d’un formulaire Contact Us.

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

Remplacer les gestionnaires de succès et d’erreur d’envoi de formulaire

Découvrez comment les fonctions personnalisées utilisent des objets de champ et globaux pour remplacer les gestionnaires d’envoi à l’aide d’un formulaire Contact Us.

Ajoutez la ligne de code suivante, comme expliqué dans la section create-custom-functions, pour personnaliser le message d’envoi ou d’échec des envois de formulaire et afficher les messages d’envoi de formulaire dans une boîte modale :

/**
 * Handles the success response after a form submission.
 *
 * @param {scope} globals - This object contains a read-only form instance, target field instance, triggered event, and methods for performing form modifications within custom functions.
 * @returns {void}
 */
function customSubmitSuccessHandler(globals) {
    var event = globals.event;
    var submitSuccessResponse = event.payload.body;
    var form = globals.form;

    if (submitSuccessResponse) {
        if (submitSuccessResponse.redirectUrl) {
            window.location.href = encodeURI(submitSuccessResponse.redirectUrl);
        } else if (submitSuccessResponse.thankYouMessage) {
            showModal("success", submitSuccessResponse.thankYouMessage);
        }
    }
}

/**
 * Handles the error response after a form submission.
 *
 * @param {string} customSubmitErrorMessage - The custom error message.
 * @param {scope} globals - This object contains a read-only form instance, target field instance, triggered event, and methods for performing form modifications within custom functions.
 * @returns {void}
 */
function customSubmitErrorHandler(customSubmitErrorMessage, globals) {
    showModal("error", customSubmitErrorMessage);
}
function showModal(type, message) {
    // Remove any existing modals
    var existingModal = document.getElementById("modal");
    if (existingModal) {
        existingModal.remove();
    }

    // Create the modal dialog
    var modal = document.createElement("div");
    modal.setAttribute("id", "modal");
    modal.setAttribute("class", "modal");

    // Create the modal content
    var modalContent = document.createElement("div");
    modalContent.setAttribute("class", "modal-content");

    // Create the modal header
    var modalHeader = document.createElement("div");
    modalHeader.setAttribute("class", "modal-header");
    modalHeader.innerHTML = "<h2>" + (type === "success" ? "Thank You" : "Error") + "</h2>";

    // Create the modal body
    var modalBody = document.createElement("div");
    modalBody.setAttribute("class", "modal-body");
    modalBody.innerHTML = "<p class='" + type + "-message'>" + message + "</p>";

    // Create the modal footer
    var modalFooter = document.createElement("div");
    modalFooter.setAttribute("class", "modal-footer");

    // Create the close button
    var closeButton = document.createElement("button");
    closeButton.setAttribute("class", "close-button");
    closeButton.innerHTML = "Close";
    closeButton.onclick = function() {
        modal.remove();
    };

    // Append the elements to the modal content
    modalFooter.appendChild(closeButton);
    modalContent.appendChild(modalHeader);
    modalContent.appendChild(modalBody);
    modalContent.appendChild(modalFooter);

    // Append the modal content to the modal
    modal.appendChild(modalContent);

    // Append the modal to the document body
    document.body.appendChild(modal);
}

Dans cet exemple, lorsque l’utilisateur utilise les fonctions personnalisées customSubmitSuccessHandler et customSubmitErrorHandler, les messages de succès et d’échec s’affichent dans une boîte de dialogue modale. La fonction JavaScript showModal(type, message) permet de créer et d’afficher de manière dynamique une boîte de dialogue modale sur un écran.

Créez maintenant une règle pour l’envoi réussi du formulaire :

Reportez-vous à l’illustration ci-dessous pour montrer que lorsque le formulaire est envoyé avec succès, le message de réussite s’affiche en mode modal :

De même, créons une règle pour les envois de formulaire ayant échoué :

Reportez-vous à l’illustration ci-dessous pour démontrer que lorsque l’envoi du formulaire échoue, le message d’erreur s’affiche dans une boîte de dialogue modale :

Pour afficher les succès et les échecs d’envoi de formulaire par défaut, les fonctions Default submit Form Success Handler et Default submit Form Error Handler sont disponibles clé en main.

Si le gestionnaire d’envoi personnalisé ne s’exécute pas comme prévu dans les formulaires ou les projets AEM existants, consultez la section dépannage.

d’effectuer des actions dans une instance spécifique du panneau répétable ;

Les règles créées à l’aide de l’éditeur de règles visuel sur un panneau répétable s’appliquent à la dernière instance du panneau répétable. Pour créer une règle pour une instance spécifique du panneau répétable, nous pouvons utiliser une fonction personnalisée.

Créons un autre formulaire Booking Form pour collecter des informations sur les voyageurs se rendant à une destination. Un panneau de voyageur est ajouté sous la forme d’un panneau répétable, où l’utilisateur peut ajouter des détails pour 5 voyageurs à l’aide du bouton Add Traveler .

Ajoutez la ligne de code suivante, comme expliqué dans la section create-custom-function, pour effectuer des actions dans une instance spécifique du panneau répétable, autre que le dernier :

/**
* @name hidePanelInRepeatablePanel
* @param {scope} globals
*/
function hidePanelInRepeatablePanel(globals)
{
    var repeatablePanel = globals.form.travelerinfo;
    // hides a panel inside second instance of repeatable panel
    globals.functions.setProperty(repeatablePanel[1].traveler, {visible : false});
}

Dans cet exemple, la fonction personnalisée hidePanelInRepeatablePanel exécute une action dans une instance spécifique du panneau répétable. Dans le code ci-dessus, travelerinfo représente le panneau répétable. Le code repeatablePanel[1].traveler, {visible: false} masque le panneau dans la deuxième instance du panneau répétable.

Ajoutons un bouton intitulé Hide et une règle pour masquer la deuxième instance d’un panneau répétable.

Reportez-vous à la vidéo ci-dessous pour montrer que lorsque l’utilisateur clique sur le Hide, le panneau de la deuxième instance répétable est masqué :

Préremplir le champ avec une valeur lors du chargement du formulaire

Découvrez comment les fonctions personnalisées utilisent les objets de champ et globaux pour préremplir un champ à l’aide d’un Booking Form.

Ajoutez la ligne de code suivante, comme expliqué dans la section create-custom-function, pour charger la valeur préremplie dans un champ lors de l’initialisation du formulaire :

/**
 * Tests import data
 * @name testImportData
 * @param {scope} globals
 */
function testImportData(globals)
{
    globals.functions.importData(Object.fromEntries([['amount','10000']]));
}

Dans le code ci-dessus, la fonction testImportData préremplit le champ de zone de texte Booking Amount au chargement du formulaire. Supposons que le formulaire de réservation exige que le montant de réservation minimal soit 10,000.

Créons une règle à l’initialisation du formulaire, où la valeur du champ de zone de texte Booking Amount est préremplie avec une valeur spécifiée lors du chargement du formulaire :

Reportez-vous à la capture d’écran ci-dessous, qui montre que lorsque le formulaire se charge, la valeur de la zone de texte Booking Amount est préremplie avec une valeur spécifiée :

Définir le focus sur le champ spécifique

Découvrez comment les fonctions personnalisées utilisent des objets de champ et globaux pour définir la cible d’action sur un champ spécifique à l’aide d’un Booking Form.

Ajoutez la ligne de code suivante, comme expliqué dans la section create-custom-function, pour définir le focus sur le champ spécifié lorsque l’utilisateur clique sur le bouton Submit :

/**
 * @name testSetFocus
 * @param {object} emailField
 * @param {scope} globals
 */
    function testSetFocus(field, globals)
    {
        globals.functions.setFocus(field);
    }

Ajoutons une règle au bouton Submit pour définir le focus sur le champ de zone de texte Email ID lorsque l’utilisateur clique dessus :

Reportez-vous à la capture d’écran ci-dessous, qui montre que lorsque l’utilisateur clique sur le bouton Submit , le focus est défini sur le champ Email ID :

Ajout ou suppression d’un panneau répétable à l’aide de la propriété dispatchEvent

Découvrez comment les fonctions personnalisées utilisent des objets de champ et globaux pour ajouter ou supprimer un panneau répétable à l’aide de la propriété dispatchEvent à l’aide d’un Booking Form.

Ajoutez la ligne de code suivante, comme expliqué dans la section create-custom-function, pour ajouter un panneau lorsque l’utilisateur clique sur le bouton Add Traveler à l’aide de la propriété dispatchEvent :

/**
 * Tests add instance with dispatchEvent
 * @name testAddInstance
 * @param {scope} globals
 */
function testAddInstance(globals)
{
    var repeatablePanel = globals.form.traveler;
    globals.functions.dispatchEvent(repeatablePanel,'addInstance');
}

Ajoutons une règle au bouton Add Traveler pour ajouter le panneau répétable lorsqu’un utilisateur ou une utilisatrice clique dessus :

Reportez-vous au gif ci-dessous, qui montre que lorsque l’utilisateur clique sur le bouton Add Traveler , le panneau est ajouté à l’aide de la propriété dispatchEvent :

De même, ajoutez la ligne de code suivante, comme expliqué dans la section create-custom-function pour supprimer un panneau lorsque vous cliquez sur le bouton Delete Traveler à l’aide de la propriété dispatchEvent :

/**

 * @name testRemoveInstance
 * @param {scope} globals
 */
function testRemoveInstance(globals)
{
    var repeatablePanel = globals.form.traveler;
    globals.functions.dispatchEvent(repeatablePanel, 'removeInstance');
}

Ajoutons une règle au bouton Delete Traveler pour supprimer le panneau répétable lorsqu’un utilisateur ou une utilisatrice clique dessus :

Reportez-vous au gif ci-dessous, qui montre que lorsque l’utilisateur clique sur le bouton Delete Traveler , le panneau du voyageur est supprimé à l’aide de la propriété dispatchEvent :

Problème Connu

Résolution des problèmes

Voir également