Show Menu
THEMEN×

Erstellen von benutzerdefinierten Erscheinungsbildern für adaptive Formularfelder

Einführung

Adaptive Formulare nutzen das Framework für Erscheinungsbild , um Ihnen beim Erstellen von benutzerdefinierten Erscheinungsbildern für adaptive Formularfelder zu helfen und eine neuartige Benutzerfreundlichkeit zu bieten. Ersetzen Sie zum Beispiel Optionsfelder und aktivieren Sie Felder mit Schaltflächen oder verwenden Sie benutzerdefinierte jQuery-Plugins, um Benutzereingaben in Feldern wie Telefonnummern oder E-Mail-ID einzuschränken.
In diesem Dokument wird erläutert, wie ein jQuery-Plugin verwendet wird, um diese alternativen Erfahrungen für adaptive Formularfelder zu erstellen. Darüber hinaus demonstriert es ein Beispiel dafür, wie ein benutzerdefiniertes Erscheinungsbild für numerische Feldkomponente erstellt wird, damit es als numerischer Schritt oder Schieberegler dargestellt wird.
Werfen wir einen Blick auf die in diesem Artikel verwendeten Schlüsselbegriffe und Konzepte.
Erscheinungsbild bezieht sich auf den Stil, das Erscheinungsbild und die Organisation verschiedener Elemente eines adaptiven Formularfelds. Es umfasst in der Regel eine Beschriftung, einen interaktiven Bereich für Eingaben, ein Hilfesymbol und kurze und lange Beschreibungen des Feldes. Die in diesem Artikel besprochene Anpassung des Erscheinungsbilds gilt für das Erscheinungsbild des Feld-Eingabebereichs.
jQuery-Plugin Stellt einen Standardmechanismus bereit, der auf dem jQuery-Widget-Framework basiert, um ein alternatives Erscheinungsbild zu implementieren.
ClientLib Ein clientseitiges Bibliothekssystem in der clientseitigen AEM-Verarbeitung, das durch komplexen JavaScript- und CSS-Code gesteuert wird. Weitere Informationen finden Sie unter Verwenden clientseitiger Bibliotheken.
Archetype A Maven Project Templating Toolkit definiert als ein Originalmuster oder -modell für Maven Projekte. Weitere Informationen finden Sie unter Einführung in Archetypen.
Benutzersteuerelement bezieht sich auf das Hauptelement in einem Widget, das den Wert des Felds enthält, und wird vom Erscheinungsbild-Framework zum Binden der benutzerdefinierten Widget-Benutzeroberfläche an das adaptive Formularmodell verwendet.

Schritte zum Erstellen eines benutzerdefinierten Erscheinungsbilds

Die Schritte zum Erstellen eines benutzerdefinierten Erscheinungsbilds auf höherer Ebene sind wie folgt:
  1. Projekt erstellen: Erstellen Sie ein Maven-Projekt, das ein Inhaltspaket generiert, das auf AEM bereitgestellt werden soll.
  2. Vorhandene Widget-Klasse erweitern: Erweitern Sie eine vorhandene Widget-Klasse und überschreiben Sie die erforderlichen Klassen.
  3. Client-Bibliothek erstellen : Erstellen Sie eine clientLib: af.customwidget -Bibliothek und fügen Sie die erforderlichen JavaScript- und CSS-Dateien hinzu.
  4. Erstellen und installieren Sie das Projekt : Erstellen Sie das Maven-Projekt und installieren Sie das generierte Inhaltspaket auf AEM.
  5. Adaptives Formular aktualisieren: Aktualisieren Sie die Feldeigenschaften für adaptive Formulare, um das benutzerdefinierte Erscheinungsbild zu verwenden.

Projekt erstellen

Ein Maven-Archetyp bildet den Ausgangspunkt zum Erstellen eines benutzerdefinierten Erscheinungsbilds. Die Details des zu verwendenden Archetyps lauten folgendermaßen:
  • Repository : https://repo.adobe.com/nexus/content/groups/public/
  • Artefakt-ID : custom-appearance-archetype
  • Gruppen-ID : com.adobe.aemforms
  • Version : 1.0.4
Führen Sie den folgenden Befehl aus, um ein lokales Projekt basierend auf dem Archetyp zu erstellen:
mvn archetype:generate -DarchetypeRepository=https://repo.adobe.com/nexus/content/groups/public/ -DarchetypeGroupId=com.adobe.aemforms -DarchetypeArtifactId=custom-appearance-archetype -DarchetypeVersion=1.0.4
Mit dem Befehl werden die Maven-Plugins und Archetypinformationen aus dem Repository heruntergeladen und ein Projekt basierend auf den folgenden Informationen generiert:
  • groupId : vom generierten Maven-Projekt verwendete Gruppen-ID
  • artifactId : vom generierten Maven-Projekt verwendete Artefakt-ID.
  • version : Version für das generierte Maven-Projekt.
  • package : für die Dateistruktur verwendetes Paket.
  • artifactName : Artefaktname des generierten AEM-Pakets.
  • packageGroup : Paketgruppe des generierten AEM-Pakets.
  • widgetName : zu Referenzzwecken verwendeter Name des Erscheinungsbilds.
Das generierte Projekt hat die folgende Struktur:
─<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

Vorhandene Widget-Klasse erweitern

Nehmen Sie nach Erstellen der Projektvorlage bei Bedarf die folgenden Änderungen vor:
  1. Schließen Sie die Plugin-Abhängigkeit des Fremdanbieters in das Projekt ein.
    1. Place the third-party or custom jQuery plugins in the jqueryplugin/javascript folder and related CSS files in the jqueryplugin/css folder. For more details, see the JS and CSS files under the jqueryplugin/javascript and jqueryplugin/css folder.
    2. Ändern Sie die Dateien js.txt und css.txt , um jede zusätzliche JavaScript- und CSS-Datei des jQuery-Plugins einzuschließen.
  2. Integrieren Sie das Drittanbieter-Plug-In mit dem Framework, um die Interaktion zwischen dem benutzerdefinierten Framework des Erscheinungsbilds und dem jQuery-Plugin zu aktivieren. Das neue Widget funktioniert erst, wenn Sie die folgenden Funktionen erweitern oder überschreiben.
Funktion Beschreibung
render Die Renderfunktion gibt das jQuery-Objekt für das standardmäßige HTML-Element des Widgets zurück. Das standardmäßige HTML-Element sollte fokussierbar sein. Zum Beispiel <a> , <input> und <li> . The returned element is used as $userControl . If the $userControl specifies the above constraint, the functions of the AbstractWidget class work as expected, else some of the common APIs (focus, click) require changes.
getEventMap Gibt eine Zuordnung zur Konvertierung von HTML-Elementen zu XFA-Ereignissen zurück. { blur: XFA_EXIT_EVENT, } Dieses Beispiel zeigt, dass es sich blur um ein HTML-Ereignis handelt und dass es sich um das entsprechende XFA-Ereignis XFA_EXIT_EVENT handelt.
getOptionsMap Gibt eine Zuordnung mit detaillierten Informationen zurück, wie eine Option geändert werden kann. Die Schlüssel sind die Optionen, die dem Widget zur Verfügung gestellt werden, und die Werte sind Funktionen, die aufgerufen werden, wenn eine Änderung der Option erkannt wird. Das Widget verfügt über Handler für alle allgemeinen Optionen (außer value und displayValue ).
getCommitValue Das jQuery-Widget-Framework lädt Funktionen, sobald der Wert des jQuery-Widgets im XFA-Modell gespeichert wird (beispielsweise bei einem exit-Ereignis eines Textfelds). Die Implementierung sollte den Wert zurückgeben, der im Widget gespeichert wird. Der Handler erhält den neuen Wert für die Option.
showValue Standardmäßig wird in XFA beim Ereignis „enter“ der rawValue des Felds angezeigt. This function is called to show the rawValue to the user.
showDisplayValue Standardmäßig wird in XFA beim Ereignis „exit“ der formattedValue des Felds angezeigt. This function is called to show the formattedValue to the user.
  1. Aktualisieren Sie bei Bedarf die JavaScript-Datei im Ordner integration/javascript .
    • Replace the text __widgetName__ with the actual widget name.
    • Erweitern Sie das Widget aus einer geeigneten, sofort einsetzbaren Widget-Klasse. In den meisten Fällen handelt es sich dabei um die Widget-Klasse, die mit dem vorhandenen Widget übereinstimmt, das ersetzt wird. Der Name der übergeordneten Klasse wird an mehreren Standorten verwendet, daher wird empfohlen, nach allen Instanzen der Zeichenfolge xfaWidget.textField in der Datei zu suchen und sie durch die eigentliche übergeordnete Klasse zu ersetzen, die verwendet wird.
    • Erweitern Sie die Methode render , um eine alternative UI bereitzustellen. Das ist der Standort, von dem aus das jQuery-Plugin aufgerufen wird, um die UI oder das Interaktionsverhalten zu aktualisieren. Die Methode render sollte ein Benutzersteuerelement zurückgeben.
    • Erweitern Sie die Methode getOptionsMap , um alle Optionseinstellungen zu überschreiben, die durch Änderungen am Widget beeinflusst wurden. Die Funktion gibt eine Zuordnung zurück, die Details für die Aktion enthält, die bei Änderung einer Option ausgeführt werden soll. Die Schlüssel sind die Optionen für das Widget und die Werte sind die Funktionen, die aufgerufen werden, wenn eine Änderung in der Option erkannt wird.
    • Die Methode getEventMap ordnet durch das Widget ausgelöste Ereignisse den Ereignissen zu, die durch das adaptive Formularmodell benötigt werden. Der Standardwert ordnet Standard-HTML-Ereignisse für das Standard-Widget zu. Es muss aktualisiert werden, falls ein alternatives Widget ausgelöst wird.
    • showDisplayValue und showValue wenden die Display- und Edit-Picture-Klausel an und können überschrieben werden, um ein alternatives Verhalten zu erzielen.
    • Die Methode getCommitValue wird durch das Framework für adaptive Formulare aufgerufen, wenn das Ereignis commit auftritt. Im Allgemeinen handelt es sich um das exit-Ereignis, mit Ausnahme von Dropdown-Liste, Optionsfeld und Elementen des Kontrollkästchens, wenn es bei einer Änderung auftritt. Weitere Informationen finden Sie unter Adaptive Formularausdrücke .
    • Die Vorlagendatei bietet Beispielimplementierung für verschiedene Methoden. Entfernen Sie Methoden, die nicht erweitert werden sollen.

Client-Bibliothek erstellen

Das durch den Maven-Archetyp generierte Beispielprojekt erstellt automatisch erforderliche Client-Bibliotheken und legt sie in eine Client-Bibliothek mit der Kategorie af.customwidgets ab. Die in af.customwidgets verfügbaren JavaScript- und CSS-Dateien werden zur Laufzeit automatisch eingefügt.

Erstellen und Installieren

Führen Sie zum Erstellen des Projekts den folgenden Befehl im Shell aus, um ein CRX-Paket zu generieren, das auf einem AEM-Server installiert werden muss.
mvn clean install
Das Maven-Projekt bezieht sich auf ein Remote-Repository in der POM-Datei. Dies dient nur zu Referenzzwecken und die Repository-Informationen werden gemäß Maven-Standards in der Datei settings.xml erfasst.

Adaptives Formular aktualisieren

So wenden Sie das benutzerdefinierte Erscheinungsbild auf ein adaptives Formularfeld an:
  1. Öffnen Sie Ihr adaptives Formular im Bearbeitungsmodus.
  2. Öffnen Sie das Dialogfeld Eigenschaft für das Feld, auf das Sie das benutzerdefinierte Erscheinungsbild anwenden möchten.
  3. In the Styling tab, update the CSS class property to add the appearance name in the widget_<widgetName> format. Beispiel: widget_numericstepper

Beispiel: Benutzerspezifische Berichte erstellen  

Werfen wir nun einen Blick auf ein Beispiel, um ein benutzerdefiniertes Erscheinungsbild für ein numerisches Feld zu erstellen, damit es als numerischer Schritt oder Schieberegler dargestellt wird. Führen Sie die folgenden Schritte durch:
  1. Führen Sie den folgenden Befehl aus, um ein lokales Projekt basierend auf dem Maven-Archetyp zu erstellen:
    mvn archetype:generate -DarchetypeRepository=https://repo.adobe.com/nexus/content/groups/public/ -DarchetypeGroupId=com.adobe.aemforms -DarchetypeArtifactId=custom-appearance-archetype -DarchetypeVersion=1.0.4
    Es fordert Sie auf, Werte für die folgenden Parameter anzugeben.
    Die in diesem Beispiel verwendeten Werte werden fett markiert .
    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. Navigieren Sie zum Verzeichnis customWidgets (angegebener Wert für die Eigenschaft artifactID ) und führen Sie den folgenden Befehl durch, um ein Eclipse-Projekt zu generieren:
    mvn eclipse:eclipse
  3. Öffnen Sie das Eclipse-Tool und führen Sie zum Importieren des Eclipse-Projekts die folgenden Schritte durch:
    1. Wählen Sie Datei > Importieren > Vorhandene Projekte in den Arbeitsbereich .
    2. Suchen Sie den Ordner aus, in dem Sie den Befehl archetype:generate durchgeführt haben.
    3. Klicken Sie auf Finish .
  4. Wählen Sie das Widget aus, das für das benutzerdefinierte Erscheinungsbild verwendet werden soll. In diesem Beispiel wird das Widget für numerische Schritte verwendet:
    Überprüfen Sie im Eclipse-Projekt die Datei plugin.js , um sicherzustellen, dass sie mit den Anforderungen für das Erscheinungsbild übereinstimmt. In diesem Beispiel erfüllt das Erscheinungsbild die folgenden Anforderungen:
    • The numeric stepper should extend from - $.xfaWidget.numericInput .
    • Die Methode set value des Widgets legt den Wert fest, nachdem der Fokus auf das Feld festgelegt wurde. Es ist eine obligatorische Anforderung für das Widget eines adaptiven Formulars.
    • Die Methode render muss überschrieben werden, um die Methode bootstrapNumber aufzurufen.
    • Mit Ausnahme des Haupt-Quellcodes gibt es für das Plugin keine zusätzliche Abhängigkeit.
    • In dem Beispiel werden keine Stile auf die Schritte angewendet und daher ist kein zusätzliches CSS erforderlich.
    • The $userControl object should be available to the render method. Es ist ein Feld vom Typ text , das mit dem Plugin-Typ geklont wird.
    • Die Schaltflächen + und - sollten deaktiviert werden, wenn das Feld deaktiviert wird.
  5. Ersetzen Sie den Inhalt des bootstrap-number-input.js (jQuery-Plugin) mit dem Inhalt der numericStepper-plugin.js -Datei.
  6. In the numericStepper-widget.js file, add the following code to override the render method to invoke the plugin and return the $userControl object:
    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. In the numericStepper-widget.js file, override the getOptionsMap property to override the access option, and hide the + and - buttons in disabled mode.
    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. Save the changes, navigate to the folder containing the pom.xml file, and execute the following Maven command to build the project:
    mvn clean install
  9. Installieren Sie das Paket mit dem AEM Package Manager.
  10. Öffnen Sie das adaptive Formular im Bearbeitungsmodus, auf das Sie das benutzerdefinierte Erscheinungsbild anwenden möchten, und führen Sie die folgenden Schritte durch:
    1. Klicken Sie mit der rechten Maustaste auf das Feld, auf das Sie das Erscheinungsbild anwenden möchten, und klicken Sie auf Bearbeiten , um das Dialogfeld „Komponente bearbeiten“ zu öffnen.
    2. Aktualisieren Sie in der Registerkarte „Stile“ die Eigenschaft CSS-Klasse , um widget_numericStepper hinzuzufügen.
Das gerade erstellte, neue Erscheinungsbild ist jetzt verfügbar.