Erstellen von benutzerdefinierten Erscheinungsbildern für adaptive Formularfelder create-custom-appearances-for-adaptive-form-fields
Einführung introduction
Adaptive Formulare verwenden die Erscheinungsbild-Framework um Ihnen zu helfen, benutzerdefinierte Erscheinungsbilder für adaptive Formularfelder zu erstellen und ein anderes Benutzererlebnis 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 Sie mit einem jQuery-Plug-in diese alternativen Erlebnisse für adaptive Formularfelder erstellen können. Darüber hinaus wird ein Beispiel zum Erstellen eines benutzerdefinierten Erscheinungsbilds für numerische Feldkomponenten gezeigt, das als numerischer Schritt oder Schieberegler angezeigt wird.
Sehen wir uns zunächst die Schlüsselbegriffe und Konzepte an, die in diesem Artikel verwendet werden.
Erscheinungsbild Bezieht sich auf den Stil, das Aussehen und die Anordnung verschiedener Elemente eines adaptiven Formularfelds. Normalerweise enthält es eine Beschriftung, einen interaktiven Bereich zur Eingabe, ein Hilfesymbol sowie kurze und lange Beschreibungen des Felds. Die in diesem Artikel beschriebene Anpassung des Erscheinungsbilds gilt für das Erscheinungsbild des Eingabebereichs des Felds.
jQuery-Plug-in Stellt einen Standardmechanismus basierend auf dem jQuery-Widget-Framework bereit, um ein alternatives Erscheinungsbild zu implementieren.
ClientLib Ein Client-seitiges Bibliothekensystem in Client-seitiger AEM-Verarbeitung, das von komplexem JavaScript- und CSS-Code gesteuert wird. Weitere Informationen finden Sie unter Verwenden Client-seitiger Bibliotheken.
Archetyp Das Vorlagenerstellungs-Toolkit eines Maven-Projekts, das als Originalmuster oder -modell für Maven-Projekte festgelegt wird. Weitere Informationen finden Sie unter Einführung in Archetypen.
Benutzerkontrolle Bezieht sich auf das Hauptelement in einem Widget, das den Wert des Felds enthält; es wird vom Framework für das Erscheinungsbild verwendet, um die benutzerdefinierte Widget-Benutzeroberfläche mit dem adaptiven Formularmodell zu verbinden.
Schritte zum Erstellen eines benutzerdefinierten Erscheinungsbilds steps-to-create-a-custom-appearance
Die Schritte zum Erstellen eines benutzerdefinierten Erscheinungsbilds auf hoher Ebene lauten wie folgt:
-
Projekt erstellen: Erstellen Sie ein Maven-Projekt, das ein Inhaltspaket generiert, das in AEM bereitgestellt wird.
-
Vorhandene Widget-Klasse erweitern: Erweitern Sie eine vorhandene Widget-Klasse und überschreiben Sie die erforderlichen Klassen.
-
Client-Bibliothek erstellen: Erstellen Sie eine
clientLib: af.customwidget
-Bibliothek und fügen Sie die erforderlichen JavaScript- und CSS-Dateien hinzu. -
Projekt erstellen und installieren: Erstellen Sie das Maven-Projekt und installieren Sie den generierten Inhalt in AEM.
-
Adaptives Formular aktualisieren: Aktualisieren Sie die Eigenschaften adaptiver Formularfelder zur Nutzung des benutzerdefinierten Erscheinungsbilds.
Projekt erstellen create-a-project
Ein Maven-Archetyp ist ein Ausgangspunkt für die Erstellung eines benutzerdefinierten Erscheinungsbilds. Die Details des zu verwendenden Archetyps lauten wie folgt:
- Repository: https://repo1.maven.org/maven2/com/adobe/
- 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://repo1.maven.org/maven2/com/adobe/ -DarchetypeGroupId=com.adobe.aemforms -DarchetypeArtifactId=custom-appearance-archetype -DarchetypeVersion=1.0.4
Der Befehl lädt die Maven-Plug-ins und Archetypinformationen aus dem Repository herunter und generiert ein Projekt, das auf den folgenden Informationen basiert:
- 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: Name des Erscheinungsbilds, der als Referenz verwendet wird.
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 extend-an-existing-widget-class
Nachdem die Projektvorlage erstellt wurde, nehmen Sie die folgenden Änderungen nach Bedarf vor:
-
Schließen Sie die Drittanbieter-Plug-in-Abhängigkeit zum Projekt ein.
-
Platzieren Sie die Fremdanbieter- oder benutzerdefinierten jQuery-Plug-ins im Ordner
jqueryplugin/javascript
und zugehörige CSS-Dateien im Ordnerjqueryplugin/css
. Weitere Informationen finden Sie in den JS- und CSS-Dateien im Ordnerjqueryplugin/javascript and jqueryplugin/css
. -
Ändern Sie die Dateien
js.txt
undcss.txt
, um jede zusätzliche JavaScript- und CSS-Datei des jQuery-Plugins einzuschließen.
-
-
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.
-
Aktualisieren Sie bei Bedarf die JavaScript-Datei im Ordner
integration/javascript
.-
Ersetzen Sie den Text
__widgetName__
durch den tatsächlichen Widget-Namen. -
Erweitern Sie das Widget von einer geeigneten vordefinierten Widget-Klasse. In den meisten Fällen handelt es sich um die Widget-Klasse, die dem vorhandenen Widget entspricht, 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 Methoderender
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 Informationen bereitstellt, damit die Aktion nach Änderung einer Option durchgeführt werden kann. Die Schlüssel sind die Optionen des Widgets und die Werte sind die Funktionen, die aufgerufen werden, sobald eine Änderung in dieser 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
undshowValue
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 Ereigniscommit
auftritt. Im Allgemeinen handelt es sich um das exit -Ereignis, mit Ausnahme der Dropdown-, Optionsfeld- und Kontrollkästchen-Elemente, in denen es bei einer Änderung auftritt. Weitere Informationen finden Sie unter Adaptive Forms-Ausdrücke. -
Die Vorlagendatei bietet eine Beispielimplementierung für verschiedene Methoden. Entfernen Sie Methoden, die nicht erweitert werden sollen.
-
Erstellen einer Client-Bibliothek create-a-client-library
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 inaf.customwidgets
verfügbaren JavaScript- und CSS-Dateien werden zur Laufzeit automatisch eingefügt.
Erstellen und Installieren build-and-install
Führen Sie zum Erstellen des Projekts den folgenden Befehl auf der Shell aus, um ein CRX-Paket zu generieren, das auf dem AEM-Server installiert werden muss.
mvn clean install
settings.xml
erfasst.Adaptives Formular aktualisieren update-the-adaptive-form
So wenden Sie das benutzerdefinierte Erscheinungsbild auf ein adaptives Formularfeld an:
- Öffnen Sie Ihr adaptives Formular im Bearbeitungsmodus.
- Öffnen Sie die Eigenschaft Dialogfeld für das Feld, auf das Sie das benutzerdefinierte Erscheinungsbild anwenden möchten.
- Aktualisieren Sie auf der Registerkarte Stile die Eigenschaft
CSS class
, um den Namen des Erscheinungsbilds zum Formatwidget_<widgetName>
hinzufügen. Beispiel: widget_numericstepper
Beispiel: Erstellen eines benutzerdefinierten Erscheinungsbilds sample-create-a-custom-appearance-nbsp
Sehen wir uns nun ein Beispiel an, um ein benutzerdefiniertes Erscheinungsbild für ein numerisches Feld zu erstellen, das als numerischer Schritt oder Schieberegler angezeigt wird. Führen Sie die folgenden Schritte durch:
-
Führen Sie den folgenden Befehl aus, um ein lokales Projekt basierend auf dem Maven-Archetyp zu erstellen:
mvn archetype:generate -DarchetypeRepository=https://repo1.maven.org/maven2/com/adobe/ -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
-
Navigieren Sie zum Verzeichnis
customWidgets
(angegebener Wert für die EigenschaftartifactID
) und führen Sie den folgenden Befehl durch, um ein Eclipse-Projekt zu generieren:mvn eclipse:eclipse
-
Öffnen Sie das Eclipse-Tool und führen Sie zum Importieren des Eclipse-Projekts die folgenden Schritte durch:
-
Wählen Sie Datei > Importieren > Vorhandene Projekte in den Arbeitsbereich.
-
Suchen Sie den Ordner aus, in dem Sie den Befehl
archetype:generate
durchgeführt haben. -
Klicken Sie auf Beenden.
-
-
Wählen Sie das Widget für das benutzerdefinierte Erscheinungsbild aus. In diesem Beispiel wird das folgende Widget für numerische Schritte verwendet:
https://www.jqueryscript.net/form/User-Friendly-Number-Input-Spinner-with-jQuery-Bootstrap.html
Ü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:-
Die numerischen Schritte sollten über
- $.xfaWidget.numericInput
erweitert werden. -
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 MethodebootstrapNumber
aufzurufen. -
Es gibt keine zusätzliche Abhängigkeit für das Plug-in außer dem Hauptquellcode des Plug-ins.
-
Das Beispiel führt keine Formatierung für den Schritt durch, sodass kein zusätzliches CSS erforderlich ist.
-
Das
$userControl
-Objekt sollte in derrender
-Methode verfügbar sein. Es ist ein Feld vom Typtext
, das mit dem Plugin-Typ geklont wird. -
Die Schaltflächen + und - sollten deaktiviert werden, wenn das Feld deaktiviert wird.
-
-
Ersetzen Sie den Inhalt des
bootstrap-number-input.js
(jQuery-Plugin) mit dem Inhalt dernumericStepper-plugin.js
-Datei. -
Fügen Sie in der Datei
numericStepper-widget.js
den folgenden Code hinzu, um die Render-Methode zum Aufrufen des Plug-ins und Zurückgeben des$userControl
-Objekts zu überschreiben:code language-javascript 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; }
-
Überschreiben Sie in der Datei
numericStepper-widget.js
die EigenschaftgetOptionsMap
, um die Zugriffsoption zu überschreiben, und blenden Sie die Schaltflächen „+“ und „-“ im deaktivierten Modus aus.code language-javascript 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; }
-
Speichern Sie die Änderungen, navigieren Sie zum Ordner mit der Datei
pom.xml
und führen Sie folgenden Maven-Befehl aus, um das Projekt zu erstellen:mvn clean install
-
Installieren Sie das Paket mit dem AEM Package Manager.
-
Öffnen Sie das adaptive Formular im Bearbeitungsmodus, auf das Sie das benutzerdefinierte Erscheinungsbild anwenden möchten, und führen Sie die folgenden Schritte durch:
-
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.
-
Aktualisieren Sie in der Registerkarte „Stile“ die Eigenschaft CSS-Klasse, um
widget_numericStepper
hinzuzufügen.
-
Das von Ihnen erstellte neue Erscheinungsbild kann jetzt verwendet werden.