Vous consultez actuellement l'aide de la version:

Introduction

Les formulaires adaptatifs exploitent le cadre de l’apparence pour vous aider à créer des apparences personnalisées pour des champs de formulaire adaptatif et offrir une expérience différente à l’utilisateur. Par exemple, remplacez des boutons radio et des cases à cocher par les boutons de basculement ou utilisez des modules externes jQuery pour limiter les entrées d’utilisateurs dans les champs tels que les numéros de téléphone ou l’ID de courrier électronique.

Ce document explique comment utiliser un module externe jQuery pour créer ces expériences différentes pour les champs de formulaire adaptatif. En outre, il présente un exemple pour créer une apparence personnalisée de façon à ce que le composant de champ numérique s’affiche sous forme d’exécution numérique pas à pas ou de curseur.

Tout d’abord, examinons les termes et concepts clés utilisés dans cet article.

Apparence

Se rapporte au style, à l’apparence et à l’organisation des différents éléments d’un champ de formulaire adaptatif. Il comprend généralement un intitulé, une zone interactive pour saisir des données, une icône d’aide et des descriptions longues et courtes du champ. La personnalisation de l’apparence abordée dans cet article s’applique à l’apparence de la zone de saisie du champ.

Module externe jQuery

Offre un mécanisme standard, en fonction de la structure de widget jQuery, pour mettre en oeuvre une autre apparence.

ClientLib

Système de bibliothèques côté client dans le traitement côté client d’AEM piloté par un code Javascript et CSS complexe. Pour en savoir plus, voir Utilisation des bibliothèques côté client.

Archétype

Palette d’outils de création de modèles de projet Maven définie comme motif ou modèle d’origine pour des projets Maven. Pour en savoir plus, voir Présentation des archétypes.

Contrôle utilisateur

Fait référence à l’élément principal dans un widget qui contient la valeur du champ ; il est utilisé par le cadre d’apparence pour associer l’interface utilisateur du widget personnalisé au modèle de formulaire adaptatif.

Procédure à suivre pour créer une apparence personnalisée

Les étapes, à un niveau élevé, pour créer une apparence personnalisée sont les suivantes :

  1. Créer un projet : créez un projet Maven qui génère un package de contenu à déployer sur AEM.
  2. Etendre une classe de widget existante : étendez une classe de widget existante et écrasez les classes requises.
  3. Créer une bibliothèque cliente : créez une bibliothèque clientLib: af.customwidget et ajoutez les fichiers Javascript et CSS requis.
  4. Générer et installer le projet : générez le projet Maven et installez le package de contenu généré sur AEM.
  5. Mettre à jour le formulaire adaptatif : mettez à jour les propriétés de champ de formulaire adaptatif pour utiliser l’apparence personnalisée.

Création d’un projet

Un archétype d’expert est un point de départ pour créer une apparence personnalisée. Les détails de l’archétype à utiliser sont les suivants :

  • Référentiel : http://repo.adobe.com/nexus/content/groups/public/
  • Id d’artefact : personnalisé-apparence-archétype
  • Id de groupe : com.adobe.aemforms
  • Version : 1.0.4

Exécutez la commande suivante pour créer un projet local en fonction de l’archétype :

 mvn archetype:generate -DarchetypeRepository=http://repo.adobe.com/nexus/content/groups/public/ -DarchetypeGroupId=com.adobe.aemforms -DarchetypeArtifactId=custom-appearance-archetype -DarchetypeVersion=1.0.4

La commande télécharge les modules externes experts et des informations sur l’archétype du référentiel et génère un projet basé sur les informations suivantes :

  • groupid : Id de groupe utilisée par le projet expert généré
  • artifactId : Id de l’artefact utilisé par le projet expert généré.
  • version : version du projet expert généré.
  • package : package utilisé pour la structure des fichiers.
  • artifactName : nom de l’artefact du package AEM généré.
  • packageGroup : groupe de packages du package AEM généré.
  • widgetName : nom de l’apparence utilisé comme référence.

Le projet généré présente la structure suivante :

─<artifactId>

 └───src

     └───main

         └───content

             └───jcr_root

                 └───etc

                     └───clientlibs

                         └───custom

                             └───<widgetName>

                                 ├───common [client library - af.customwidgets which encapsulates below clientLibs]

                                 ├───integration [client library - af.customwidgets.<widgetName>_widget which contains template files for integrating a third-party plugin with Adaptive Forms]

                                 │   ├───css

                                 │   └───javascript

                                 └───jqueryplugin [client library - af.customwidgets.<widgetName>_plugin which holds the third-party plugins and related dependencies]

                                     ├───css

                                     └───javascript

Étendre une classe de widget existante

Une fois le modèle de projet créé, effectuez les modifications suivantes, selon vos besoins :

  1. Incluez la dépendance de module externe tiers au projet.

    1. Définissez les modules externes jQuery tiers ou personnalisés dans le dossier jqueryplugin/javascript et les fichiers CSS associées dans le dossier jqueryplugin/css. Pour en savoir plus, voir les fichiers JS et CSS sous le dossier jqueryplugin/javascript et jqueryplugin/css.
    2. Modifiez les fichiers js.txt et css.txt pour inclure les fichiers Javascript et CSS supplémentaires du module externe jQuery.
  2. Intégrez le module externe tiers au cadre pour permettre une interaction entre le cadre d’apparence personnalisée et le module externe jQuery. Le nouveau widget sera fonctionnel uniquement après avoir étendu ou remplacé les fonctions suivantes.

    Fonction Description
    rendu La fonction de rendu renvoie l’objet jQuery à l’élément HTML par défaut du widget. L’élément HTML par défaut doit être d’un type pouvant être actif. Par exemple, <a>, <input> et <li>. L’élément renvoyé est utilisé comme $userControl. Si le $userControl indique la contrainte ci-dessus, les fonctions de la classe AbstractWidget fonctionnent comme prévu, sinon une partie des API communes (focus, clic) nécessitent des modifications. 
    getEventMap Renvoie un mappage pour convertir les événements HTML en événements XFA. 
    {
    blur: XFA_EXIT_EVENT,
    }

    Cet exemple indique que le flou est un événement HTML et que XFA_EXIT_EVENT est l’événement XFA correspondant. 
    getOptionsMap Renvoie un mappage qui fournit des détails sur l’action à exécuter lors de la modification d’une option. Les touches sont les options fournies au widget et les valeurs sont les fonctions qui sont appelées à chaque fois qu’un changement de cette option est détecté. Le widget fournit des gestionnaires pour toutes les options courantes (à l’exception de value et displayValue).
    getCommitValue Le cadre de widget jQuery charge la fonction à chaque fois que la valeur du widget jQuery est enregistrée dans le modèle XFA (par exemple sur l’événement de sortie d’un champ de texte). L’implémentation doit renvoyer la valeur qui est enregistrée dans le widget. Le gestionnaire est fourni avec la nouvelle valeur pour l’option.
    showValue Par défaut, lors de l’événement d’entrée dans XFA, la rawValue du champ s’affiche. Cette fonction est appelée pour afficher la rawValue à l’utilisateur. 
    showDisplayValue Par défaut, sur l’événement de sortie dans XFA, la formattedValue du champ s’affiche. Cette fonction est appelée pour afficher la formattedValue à l’utilisateur. 
  3. Mettez le fichier Javascript à jour dans le dossier integration/javascript selon les besoins.

    • Remplacez le texte __widgetName__ par le nom du widget réel.
    • Etendez le widget à partir d’une classe de widgets prêts à l’emploi convenable. Dans la plupart des cas, il s’agit de la classe de widget correspondant au widget existant à remplacer. Le nom de la classe parente est utilisé à plusieurs endroits, il est donc recommandé de rechercher toutes les instances de la chaîne xfaWidget.textField dans le fichier, et de les remplacer par la classe parente réelle utilisée.
    • Etendez la méthode render pour fournir une autre interface utilisateur. Il s’agit de l’emplacement d’où le module externe jQuery sera appelé pour mettre à jour l’interface utilisateur ou le comportement de l’interaction. La méthode render doit retourner un élément de contrôle de l’utilisateur.
    • Etendez la méthode getOptionsMap pour remplacer le paramètre d’option concerné suite à une modification du widget. La fonction renvoie un mappage qui fournit des détails sur l’action à exécuter lors de la modification d’une option. Les touches sont les options fournies au widget et les valeurs sont les fonctions appelées à chaque fois qu’un changement de l’option est détecté.
    • La méthode getEventMap mappe les événements déclenchés par le widget avec les événements requis par le modèle de formulaire adaptatif. La valeur par défaut mappe les événements HTML standard du widget par défaut et doit être mise à jour si un événement alternatif est déclenché.
    • La showDisplayValue et la showValue appliquent la clause d’affichage et de modification de l’image et peuvent être remplacées pour obtenir un autre comportement.
    • La méthode getCommitValue est appelée par le cadre des formulaires adaptatifs lorsque l’événement commit se produit. En règle générale, il s’agit de l’événement de sortie, à l’exception des éléments de liste déroulante, de bouton-radio et de case à cocher où il s’affiche en cas de modification. Pour en savoir plus, voir Expressions des formulaires adaptatifs.
    • Le fichier de modèle fournit des exemples d’implémentation pour différentes méthodes. Supprimez les méthodes qui ne doivent pas être étendues.

Créer une bibliothèque cliente

L’exemple de projet généré par l’archétype d’expert crée automatiquement les bibliothèques clientes requises et les inclut dans une bibliothèque cliente avec une catégorie af.customwidgets. Les fichiers Javascript et CSS disponibles dans af.customwidgets sont automatiquement inclus au moment de l’exécution.

Création et installation

Pour créer le projet, exécutez la commande suivante sur le shell pour générer un package CRX qui doit être installé sur le serveur AEM.

mvn clean install

Remarque :

Le projet d’expert fait référence à un référentiel distant à l’intérieur du fichier POM. Il est indiqué uniquement à titre de référence et conformément aux normes d’expert, les informations du référentiel sont capturées dans le fichier settings.xml.

Mettre à jour le formulaire adaptatif

Pour appliquer l’apparence personnalisée à un champ de formulaire adaptatif :

  1. Ouvrez le formulaire adaptatif en mode d’édition.
  2. Ouvrez la boîte de dialogue Propriétés pour trouver le champ auquel vous voulez appliquer l’apparence personnalisée.
  3. Dans l’onglet Style, mettez à jour la propriété CSS class pour ajouter le nom de l’apparence au format widget_<widgetName>. Par exemple : widget_numericstepper

Exemple : Créer une apparence personnalisée  

Examinons à présent un exemple de création d’une apparence personnalisée pour qu’un champ numérique s’affiche sous forme d’exécution numérique pas à pas ou de curseur. Exécutez les étapes suivantes :

  1. Exécutez la commande suivante pour créer un projet local en fonction de l’archétype expert :

    mvn archetype:generate -DarchetypeRepository=http://repo.adobe.com/nexus/content/groups/public/ -DarchetypeGroupId=com.adobe.aemforms -DarchetypeArtifactId=custom-appearance-archetype -DarchetypeVersion=1.0.4

    Il vous invite à spécifier des valeurs pour les paramètres suivants.
    Les valeurs utilisées dans cet exemple sont mises en surbrillance en gras.

    Définissez la valeur de la propriété « groupId » : com.adobe.afwidgets

    Définissez la valeur de la propriété « artifactId » : customWidgets

    Définissez la valeur de la propriété « version » : 1.0.1-SNAPSHOT

    Définissez la valeur de la propriété « package » : com.adobe.afwidgets

    Définissez la valeur de la propriété « artifactName » : customWidgets

    Définissez la valeur de la propriété « packageGroup » : adobe/customWidgets

    Définissez la valeur de la propriété « widgetName » : numericStepper

  2. Accédez au répertoire customWidgets (valeur spécifiée pour la propriété artifactID) et exécutez la commande suivante afin de générer un projet Eclipse :

    mvn eclipse:eclipse

  3. Ouvrez l’outil Eclipse et procédez comme suit pour importer le projet Eclipse :

    1. Sélectionnez Fichier > Importer > Projets existants dans l’espace de travail.

    2. Recherchez et sélectionnez le dossier dans lequel vous avez exécuté la commande archetype:generate.

    3. Cliquez sur Terminer.

      eclipse-screenshot
  4. Sélectionnez le widget à utiliser pour l’apparence personnalisée. Cet exemple utilise le widget d’exécution numérique pas à pas suivant :

    http://www.jqueryscript.net/form/User-Friendly-Number-Input-Spinner-with-jQuery-Bootstrap.html

    Dans le projet Eclipse, passez en revue le code du module externe dans le fichier plugin.js pour vous assurer qu’il correspond à la configuration requise pour l’apparence. Dans cet exemple, l’apparence satisfait aux exigences suivantes :

    • L’exécution numérique pas à pas doit s’étendre à partir de - $.xfaWidget.numericInput.
    • La méthode set value du widget définit la valeur une fois que le focus est sur le champ. Il s’agit d’un élément obligatoire pour un widget de formulaire adaptatif.
    • La méthode render doit être remplacée pour appeler la méthode bootstrapNumber.
    • Il n’y a aucune dépendance pour le module externe autre que le code source principal du module externe.
    • L’exemple n’effectue aucune mise en forme sur l’exécution automatique pas à pas ; aucun CSS supplémentaire n’est donc requis.
    • L’objet $userControl doit être à disposition de la méthode render. Il s’agit d’un champ de type texte qui est copié avec le code du module externe.
    • Les boutons + et - doivent être désactivés lorsque le champ est désactivé.
  5. Remplacez le contenu de bootstrap-number-input.js(module externe jQuery) par le contenu du fichier numericStepper-plugin.js.

  6. Dans le fichier numericStepper-widget.js, ajoutez le code suivant pour remplacer la méthode de rendu afin d’appeler le module externe et renvoyer l’objet $userControl :

    render : function() {
         var control = $.xfaWidget.numericInput.prototype.render.apply(this, arguments);
         var $control = $(control);
         var controlObject;
         try{
             if($control){
             $control.bootstrapNumber();
             var id = $control.attr("id");
             controlObject = $("#"+id);
             }
         }catch (exc){
              console.log(exc);
         }
         return controlObject;
    }
  7. Dans le fichier numericStepper-widget.js, remplacez la propriété getOptionsMap pour ignorer l’option d’accès et masquer les boutons + et- en mode désactivé.

    getOptionsMap: function(){
        var parentOptionsMap = $.xfaWidget.numericInput.prototype.getOptionsMap.apply(this,arguments),
    
        newMap = $.extend({},parentOptionsMap,
    
         {
    
               "access": function(val) {
               switch(val) {
                  case "open" :
                    this.$userControl.removeAttr("readOnly");
                    this.$userControl.removeAttr("aria-readonly");
                    this.$userControl.removeAttr("disabled");
                    this.$userControl.removeAttr("aria-disabled");
                    this.$userControl.parent().find(".input-group-btn button").prop('disabled',false);
                    break;
                  case "nonInteractive" :
                  case "protected" :
                    this.$userControl.attr("disabled", "disabled");
                    this.$userControl.attr("aria-disabled", "true");
                    this.$userControl.parent().find(".input-group-btn button").prop('disabled',true);
                    break;
                 case "readOnly" :
                    this.$userControl.attr("readOnly", "readOnly");
                    this.$userControl.attr("aria-readonly", "true");
                    this.$userControl.parent().find(".input-group-btn button").prop('disabled',true);
                    break;
                default :
                    this.$userControl.removeAttr("disabled");
                    this.$userControl.removeAttr("aria-disabled");
                    this.$userControl.parent().find(".input-group-btn button").prop('disabled',false);
                    break;
              }
           },
       });
       return newMap;
     }
  8. Enregistrez les modifications, accédez au dossier contenant le fichier pom.xml et exécutez la commande d’expert suivante pour générer le projet :

    mvn clean install

  9. Installez le package à l’aide d’AEM Package Manager.

  10. Ouvrez le formulaire adaptatif en mode d’édition auquel vous souhaitez appliquer l’apparence personnalisée et procédez comme suit :

    1. Cliquez avec le bouton droit de la souris sur le champ sur lequel vous souhaitez appliquer l’apparence et cliquez sur Modifier pour ouvrir la boîte de dialogue Modifier le composant.

    2. Dans l’onglet Style, mettez à jour la propriété classe CSS pour ajouter widget_numericStepper.

La nouvelle apparence que vous venez de créer est désormais disponible.

Ce produit est distribué sous licence Creative Commons Attribution - Pas d’utilisation commerciale - Partage à l’identique 3.0 non transposé  Les publications Twitter™ et Facebook ne sont pas couvertes par les dispositions Creative Commons.

Mentions légales   |   Politique de confidentialité en ligne