Aangepaste weergaven maken voor adaptieve formuliervelden

Inleiding

Bij adaptieve formulieren wordt het weergaveframework gebruikt om u te helpen aangepaste weergaven te maken voor adaptieve formuliervelden en een andere gebruikerservaring te bieden. Vervang bijvoorbeeld keuzerondjes en selectievakjes door schakelknoppen of gebruik aangepaste jQuery-plug-ins om gebruikersinvoer in velden zoals telefoonnummers of e-mailadressen te beperken.

In dit document wordt uitgelegd hoe u met een jQuery-insteekmodule deze alternatieve ervaringen voor adaptieve formuliervelden kunt maken. Daarnaast wordt een voorbeeld weergegeven voor het maken van een aangepaste weergave voor numerieke veldcomponenten die worden weergegeven als een numerieke stapfunctie of schuifregelaar.

Laten we eerst kijken naar de belangrijkste termen en concepten die in dit artikel worden gebruikt.

​​VormgevingVerwijst naar de stijl, vormgeving en organisatie van verschillende elementen van een adaptief formulierveld. Het omvat gewoonlijk een etiket, een interactief gebied om input, een hulppictogram, en korte en lange beschrijvingen van het gebied te verstrekken. De aanpassing van de weergave die in dit artikel wordt besproken, is van toepassing op de weergave van het invoergebied van het veld.

jQuery- insteekmoduleBiedt een standaardmechanisme op basis van het jQuery-widgetframework voor het implementeren van een alternatieve weergave.

​​ClientLibA client-side bibliotheeksysteem in AEM client-side verwerking aangedreven door complexe JavaScript- en CSS-code. Zie Client-Side Libraries gebruiken voor meer informatie.

Toolkit ArchetypeA Maven project templating defined as an original pattern or model for Maven projects. Voor meer informatie, zie Inleiding aan Archetypes.

User ControlReference to the main element in a widget that contains the value of the field, and is used by the appearance framework for binding the custom widget UI with the adaptive form model.

Stappen om een aangepaste weergave te maken

Op hoog niveau zijn de volgende stappen nodig om een aangepaste weergave te maken:

1. Een project maken: Creeer een Geweven project dat een inhoudspakket om op AEM produceert op te stellen.

2. Een bestaande widgetklasse uitbreiden: Een bestaande widgetklasse uitbreiden en de vereiste klassen overschrijven.

3. Een clientbibliotheek maken: Maak een clientLib: af.customwidget bibliotheek en voeg de vereiste JavaScript- en CSS-bestanden toe.

4. Het project bouwen en installeren: Bouw het Maven project en installeer het geproduceerde inhoudspakket op AEM.

5. Het aangepaste formulier bijwerken: Pas de eigenschappen van formuliervelden aan om de aangepaste weergave te gebruiken.

Een project maken

Een bepaald archetype is een uitgangspunt voor het creëren van een douaneverschijning. De details van het te gebruiken archetype zijn als volgt:

• Bewaarplaats: https://repo.adobe.com/nexus/content/groups/public/
• Artefact-id: custom-appearance-archetype
• Groep-id: com.adobe.aemforms
• Versie: 1.0.4.

Voer het volgende bevel uit om een lokaal project tot stand te brengen dat op archetype wordt gebaseerd:

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

De opdracht downloadt de Maven-plug-ins en archetype-informatie van de opslagplaats en genereert een project op basis van de volgende informatie:

• groupId: Groep-id gebruikt door het gegenereerde Maven-project
• artefactId: Artefact-id die wordt gebruikt door het gegenereerde Maven-project.
• versie: Versie voor het gegenereerde Maven-project.
• pakket: Pakket gebruikt voor de bestandsstructuur.
• artifactName: Artefactnaam van het gegenereerde AEM.
• packageGroup: Pakketgroep van het gegenereerde AEM.
• widgetName: Weergavenaam die ter referentie wordt gebruikt.

Het gegenereerde project heeft de volgende structuur:

─<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

Een bestaande widgetklasse uitbreiden

Zodra het projectmalplaatje wordt gecreeerd, doe de volgende veranderingen, zoals vereist:

1. Neem de afhankelijkheid van de externe plug-in van het project op.

   1. Plaats de externe of aangepaste jQuery-plug-ins in de map jqueryplugin/javascript en de bijbehorende CSS-bestanden in de map jqueryplugin/css. Zie de JS- en CSS-bestanden in de map jqueryplugin/javascript and jqueryplugin/css voor meer informatie.
   2. Wijzig de js.txt- en css.txt-bestanden om extra JavaScript- en CSS-bestanden van de jQuery-insteekmodule op te nemen.

2. Integreer de externe insteekmodule met het framework om interactie mogelijk te maken tussen het aangepaste weergaveframework en de jQuery-insteekmodule. De nieuwe widget werkt alleen nadat u de volgende functies hebt uitgebreid of genegeerd.

1. Werk het JavaScript-bestand naar wens bij in de map integration/javascript.

   • Vervang de tekst __widgetName__ door de daadwerkelijke widgetnaam.
   • Breid de widget uit van een geschikte buitenste widgetklasse. In de meeste gevallen is dit de klasse widget die overeenkomt met de bestaande widget die wordt vervangen. De naam van de bovenliggende klasse wordt op meerdere locaties gebruikt. Het wordt daarom aanbevolen te zoeken naar alle instanties van de tekenreeks xfaWidget.textField in het bestand en deze te vervangen door de werkelijk gebruikte bovenliggende klasse.
   • Breid render methode uit om een afwisselende UI te verstrekken. Dit is de locatie vanwaar de jQuery-insteekmodule wordt aangeroepen om de gebruikersinterface of het interactiegedrag bij te werken. De render methode zou een user-control element moeten terugkeren.
   • Breid de getOptionsMap methode uit om het even welke optie met voeten te treden die als toe te schrijven aan een verandering in widget wordt beïnvloed. De functie retourneert een toewijzing die details bevat voor de actie die moet worden uitgevoerd bij wijziging van een optie. De sleutels zijn de opties die aan widget worden verstrekt en de waarden zijn de functies die worden geroepen wanneer een verandering in de optie wordt ontdekt.
   • De methode getEventMap wijst gebeurtenissen toe die door de widget worden geactiveerd, met de gebeurtenissen die door het adaptieve formuliermodel worden vereist. De standaardwaarde wijst standaard HTML-gebeurtenissen toe voor de standaardwidget en moet worden bijgewerkt als een alternatieve gebeurtenis wordt geactiveerd.
   • De showDisplayValue en showValue passen de weergave- en bewerkingsafbeeldingsvoorwaarde toe en kunnen worden overschreven voor een ander gedrag.
   • De methode getCommitValue wordt aangeroepen door het adaptieve formulierframework wanneer de gebeurtenis commitplaatsvindt. Over het algemeen is dit de afsluitgebeurtenis, behalve voor de vervolgkeuzelijst, het keuzerondje en de selectievakjes (waar deze voorkomt bij wijziging). Zie Aangepaste Forms-expressies voor meer informatie.
   • Het sjabloonbestand biedt voorbeeldimplementatie voor verschillende methoden. Verwijder methoden die niet moeten worden uitgebreid.

Een clientbibliotheek maken

Het voorbeeldproject dat door het Maven archetype wordt geproduceerd leidt automatisch tot vereiste cliëntbibliotheken, en verpakt hen in een cliëntbibliotheek met een categorie af.customwidgets. De JavaScript- en CSS-bestanden die beschikbaar zijn in af.customwidgets worden automatisch opgenomen bij uitvoering.

bouwen en installeren

Om het project te bouwen, voer het volgende bevel op shell uit om een pakket te produceren CRX dat op de AEM server moet worden geïnstalleerd.

mvn clean install

Het aangepaste formulier bijwerken

De aangepaste weergave toepassen op een adaptief formulierveld:

1. Open het adaptieve formulier in de bewerkingsmodus.
2. Open het dialoogvenster Eigenschap voor het veld waarop u de aangepaste weergave wilt toepassen.
3. Werk op het tabblad Stileren de eigenschap CSS class bij om de weergavenaam toe te voegen in de indeling widget_<widgetName>. Bijvoorbeeld: widget_numericstepper

Voorbeeld: Een aangepaste weergave maken  

Bekijk nu een voorbeeld om een douaneverschijning voor een numeriek gebied tot stand te brengen om als numerieke stapper of schuif te verschijnen. Voer de volgende stappen uit:

1. Voer het volgende bevel uit om een lokaal project tot stand te brengen dat op Maven archetype wordt gebaseerd:

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

   U wordt gevraagd waarden op te geven voor de volgende parameters.

   De in dit voorbeeld gebruikte waarden worden vet gemarkeerd.

   Define value for property 'groupId': com.adobe.afwidgets

   Define value for property 'artifactId': customWidgets

   Define value for property 'version': 1.0.1-SNAPSHOT

   Define value for property 'package': com.adobe.afwidgets

   Define value for property 'artifactName': customWidgets

   Define value for property 'packageGroup': adobe/customWidgets

   Define value for property 'widgetName': numericStepper

2. Navigeer naar de map customWidgets (opgegeven waarde voor de eigenschap artifactID) en voer de volgende opdracht uit om een Eclipse-project te genereren:

   mvn eclipse:eclipse

3. Open het gereedschap Eclipse en voer de volgende handelingen uit om het Eclipse-project te importeren:

   1. Selecteer File > Import > Existing Projects into Workspace.

   2. Blader en selecteer de map waarin u de opdracht archetype:generate hebt uitgevoerd.

   3. Klik op Finish.

      

4. Selecteer de widget die voor de aangepaste weergave moet worden gebruikt. In dit voorbeeld wordt de volgende numerieke stepper-widget gebruikt:

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

   Controleer in het Eclipse-project de insteekcode in het plugin.js-bestand om te controleren of deze voldoet aan de vereisten voor de weergave. In dit voorbeeld voldoet de weergave aan de volgende vereisten:

   • De numerieke stapfunctie moet worden uitgebreid van - $.xfaWidget.numericInput.
   • De methode set value van de widget stelt de waarde in nadat de focus op het veld is geplaatst. Dit is een verplichte vereiste voor een adaptieve formulierwidget.
   • De render methode moet worden met voeten getreden om de bootstrapNumber methode aan te halen.
   • Er is geen andere afhankelijkheid van de plug-in dan de hoofdbroncode van de plug-in.
   • In het voorbeeld wordt geen stijl toegepast op de stapfunctie. Er is dus geen extra CSS vereist.
   • Het object $userControl moet beschikbaar zijn voor de methode render. Dit is een veld van het type text dat met de insteekcode is gekloond.
   • De + en - knopen zouden moeten worden onbruikbaar gemaakt wanneer het gebied wordt onbruikbaar gemaakt.

5. Vervang de inhoud van de bootstrap-number-input.js (jQuery-insteekmodule) door de inhoud van het numericStepper-plugin.js-bestand.

6. Voeg in het numericStepper-widget.js-bestand de volgende code toe om de rendermethode te overschrijven om de insteekmodule aan te roepen en het $userControl-object te retourneren:

   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. Overschrijf in het bestand numericStepper-widget.js de eigenschap getOptionsMap om de toegangsoptie te overschrijven en verberg de knoppen + en - in de uitgeschakelde modus.

   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. Sla de wijzigingen op, navigeer naar de map die het pom.xml-bestand bevat en voer de volgende Maven-opdracht uit om het project te maken:

   mvn clean install

9. Installeer het pakket met AEM Package Manager.

10. Open het adaptieve formulier in de bewerkingsmodus waarop u de aangepaste weergave wilt toepassen en voer de volgende handelingen uit:

    1. Klik met de rechtermuisknop op het veld waarop u de weergave wilt toepassen en klik op Edit om het dialoogvenster Component bewerken te openen.

    2. Werk op het tabblad Stijl de eigenschap CSS class bij om widget_numericStepper toe te voegen.

De nieuwe weergave die u zojuist hebt gemaakt, is nu beschikbaar voor gebruik.