Entwickeln von Formularen (klassische Benutzeroberfläche) :headding-anchor:developing-forms-classic-ui
Die grundlegende Struktur eines Formulars sieht wie folgt aus:
- Beginn des Formulars
- Elemente des Formulars
- Ende des Formulars
All diese Teile werden mit einer Reihe standardmäßiger Formularkomponenten realisiert, die in einer Standard-AEM-Installation verfügbar sind.
Neben der Entwicklung neuer Komponenten für Ihre Formulare ist auch Folgendes möglich:
Skripte verwenden, um die Funktionalität bei Bedarf zu erweitern.
Vorabladen von Formularwerten :headding-anchor:preloading-form-values
Die Formular-Start-Komponente stellt ein Feld für den Ladepfad bereit. Dies ist ein optionaler Pfad, der auf einen Knoten im Repository verweist.
Der Ladepfad ist der Pfad zu den Knoteneigenschaften, mit dem vordefinierte Werte in mehrere Felder im Formular geladen werden.
Dies ist ein optionales Feld, das den Pfad zu einem Knoten im Repository angibt. Wenn dieser Knoten Eigenschaften hat, die den Feldnamen entsprechen, werden die jeweiligen Felder im Formular vorab mit den Werten dieser Eigenschaften ausgefüllt. Wenn keine Übereinstimmung besteht, steht im Feld der Standardwert.
FormsHelper#setFormLoadResource
in init.jsp
.Vorabladen von Formularfeldern mit mehreren Werten :headding-anchor:preloading-form-fields-with-multiple-values
Einige Formularfelder verfügen auch über einen Element-Ladepfad. Dies ist ein weiterer optionaler Pfad, der auf einen Knoten im Repository verweist.
Der Element-Ladepfad ist der Pfad zu Knoteneigenschaften, mit dem vordefinierte Werte in dieses Formularfeld geladen werden – z. B. eine Dropdown-Liste, eine Gruppe von Kontrollkästchen oder eine Gruppe von Optionsfeldern.
Beispiel: Vorabladen einer Dropdown-Liste mit mehreren Werten :headding-anchor:example-preloading-a-dropdown-list-with-multiple-values
Eine Dropdown-Liste kann mit Ihren zur Auswahl stehenden Werten konfiguriert werden.
Mit dem Element-Ladepfad kann auf eine Liste aus einem Ordner im Repository zugegriffen werden, die in das Feld geladen wird:
-
Erstellen Sie einen Sling-Ordner (
sling:Folder
),
z. B./etc/designs/<myDesign>/formlistvalues
. -
Fügen Sie eine neue Eigenschaft (z. B.
myList
) des Typs mehrwertige Zeichenfolge (String[]
) hinzu, die eine Liste der Dropdown-Elemente enthält. Sie können auch mithilfe eines Skripts Inhalte importieren, z. B. mit einem JSP-Skript oder cURL in einem Shell-Skript. -
Verwenden Sie den vollständigen Pfad im Feld Element-Ladepfad.
Zum Beispiel/etc/designs/geometrixx/formlistvalues/myList
Hinweis: Wenn die Werte im String[]
wie folgt formatiert sind:
AL=Alabama
AK=Alaska
generiert AEM die Liste wie folgt:
<option value="AL">Alabama</option>
<option value="AK">Alaska</option>
Diese Funktion kann beispielsweise in einer mehrsprachigen Umgebung nützlich sein.
Entwickeln eigener Formularaktionen :headding-anchor:developing-your-own-form-actions
Für ein Formular ist eine Aktion erforderlich. Die Aktion bestimmt den Vorgang, der ausgeführt wird, wenn das Formular mit Benutzerdaten übermittelt wird.
Mit einer AEM-Standardinstallation stehen verschiedene Aktionen zur Verfügung. Sie finden diese unter:
/libs/foundation/components/form/actions
und in der Action Type-Liste der Formular-Komponente:
Dieser Abschnitt erläutert, wie Sie Ihre eigene Formularaktion entwickeln und zu dieser Liste hinzufügen können.
Sie können Ihre eigene Aktion wie folgt unter /apps
hinzufügen:
-
Erstellen Sie einen Knoten des Typs
sling:Folder
. Geben Sie einen Namen an, der der zu implementierenden Aktion entspricht.Beispiel:
/apps/myProject/components/customFormAction
-
Definieren Sie in diesem Knoten die folgenden Eigenschaften und klicken Sie anschließend auf Alle speichern, um Ihre Änderungen zu speichern:
-
sling:resourceType
: alsfoundation/components/form/action
festlegen -
componentGroup
: als.hidden
definieren -
Optional:
-
jcr:title
: Geben Sie einen Titel Ihrer Wahl an, der in der Dropdown-Auswahlliste angezeigt wird. Wenn Sie dies nicht festlegen, wird der Name des Knotens angezeigt -
jcr:description
: Geben Sie eine Beschreibung Ihrer Wahl ein
-
-
-
Erstellen Sie im Ordner einen Dialogfeldknoten:
- Fügen Sie Felder hinzu, damit der Autor bzw. die Autorin das Formular-Dialogfeld bearbeiten kann, nachdem die Aktion ausgewählt wurde.
-
Im Ordner erstellen Sie entweder:
-
Ein Postskript.
Der Name des Skripts lautetpost.POST.<extension>
, z. B.post.POST.jsp
Das Postskript wird aufgerufen, wenn ein Formular eingereicht wird, und verarbeitet es. Es enthält den Code, der die Daten aus dem FormularPOST
verarbeitet. -
Fügen Sie ein Weiterleitungsskript hinzu, das aufgerufen wird, wenn das Formular eingereicht wird.
Der Name des Skripts lautetforward.<extension
>, z. B.forward.jsp
Dieses Skript kann einen Pfad definieren. Die aktuelle Anfrage wird dann an den angegebenen Pfad weitergeleitet.
Der erforderliche Aufruf ist
FormsHelper#setForwardPath
(2 Varianten). Ein typischer Anwendungsfall besteht darin, eine Validierung oder Logik auszuführen, um den Zielpfad zu finden, und anschließend zu diesem Pfad weiterzuleiten. Dabei wird die Speicherung in JCR dem standardmäßigen Sling-POST-Servlet überlassen.Es kann auch ein weiteres Servlet verwendet werden, das die eigentliche Verarbeitung übernimmt. In diesem Fall stellen die Formularaktion und
forward.jsp
nur die Verbindung dar. Ein Beispiel dafür ist die E-Mail-Aktion unter/libs/foundation/components/form/actions/mail
, die Details an<currentpath>.mail.html
weiterleitet, wo sich ein E-Mail-Servlet befindet.Das bedeutet:
- Ein
post.POST.jsp
eignet sich für kleine Vorgänge, die vollständig von der Aktion selbst ausgeführt werden. forward.jsp
ist hingegen hilfreich, wenn nur Delegation erforderlich ist.
Die Skripte werden in folgender Reihenfolge ausgeführt:
-
Nach dem Rendering des Formulars (
GET
):init.jsp
- Für alle Feldeinschränkungen:
clientvalidation.jsp
- validationRT des Formulars:
clientvalidation.jsp
- Das Formular wird über eine Laderessource geladen, wenn dies festgelegt ist
addfields.jsp
während des Renderings von<form></form>
-
Nach der Verarbeitung eines Formular-
POST
:-
init.jsp
-
Für alle Feldeinschränkungen:
servervalidation.jsp
-
validationRT des Formulars:
servervalidation.jsp
-
forward.jsp
-
Wenn ein Weiterleitungspfad festgelegt wurde (
FormsHelper.setForwardPath
), leiten Sie die Anfrage weiter und rufen Sie anschließendcleanup.jsp
auf -
Wenn kein Weiterleitungspfad festgelegt wurde, rufen Sie
post.POST.jsp
auf (der Vorgang ist hier beendet,cleanup.jsp
wird nicht aufgerufen)
-
-
-
Auch hier können Sie optional Folgendes zum Ordner hinzufügen:
-
Ein Skript für das Hinzufügen von Feldern.
Der Name des Skripts lautetaddfields.<extension>
, z. B.addfields.jsp
Einaddfields
-Skript wird unmittelbar nach dem Schreiben der HTML für den Formularstart aufgerufen. Dadurch kann die Aktion benutzerdefinierte Eingabefelder oder sonstigen HTML-Code in das Formular einfügen. -
Ein Initialisierungsskript.
Der Name des Skripts lautetinit.<extension>
, z. B.init.jsp
Dieses Skript wird aufgerufen, wenn das Formular gerendert wird. Es kann zur Initialisierung von handlungsspezifischen Elementen verwendet werden. -
Ein Bereinigungsskript.
Der Name des Skripts lautetcleanup.<extension>
, z. B.cleanup.jsp
Dieses Skript kann für die Bereinigung verwendet werden.
-
-
Verwenden Sie die Formularkomponente in einem Absatzsystem. Das Dropdown-Menü Aktionstyp enthält nun Ihre neue Aktion.
note note NOTE So zeigen Sie weitere Standardaktionen an, die im Produkt inbegriffen sind: /libs/foundation/components/form/actions
Entwicklung Ihrer eigenen Formulareinschränkungen :headding-anchor:developing-your-own-form-constraints
Einschränkungen können auf zwei Ebenen angewendet werden:
Einschränkungen für einzelne Felder :headding-anchor:constraints-for-individual-fields
Sie können wie folgt Ihre eigenen Einschränkungen für ein einzelnes Feld hinzufügen (unter /apps
):
-
Erstellen Sie einen Knoten des Typs
sling:Folder
. Geben Sie einen Namen an, der der zu implementierenden Einschränkung entspricht.Beispiel:
/apps/myProject/components/customFormConstraint
-
Definieren Sie in diesem Knoten die folgenden Eigenschaften und klicken Sie anschließend auf Alle speichern, um Ihre Änderungen zu speichern:
-
sling:resourceType
: auffoundation/components/form/constraint
festlegen -
constraintMessage
: Eine individuelle Nachricht, die beim Übermitteln des Formulars angezeigt wird, wenn das Feld gemäß der Einschränkung nicht gültig ist. -
Optional:
jcr:title
: Geben Sie einen Titel Ihrer Wahl an, der in der Auswahlliste angezeigt wird. Wenn Sie dies nicht festlegen, wird der Name des Knotens angezeigthint
: zusätzliche Informationen für den Benutzer zur Verwendung dieses Felds
-
-
In diesem Ordner benötigen Sie möglicherweise auch die folgenden Skripte:
-
Ein Client-Validierungsskript:
Der Name des Skripts lautetclientvalidation.<extension>
, z. B.clientvalidation.jsp
.
Dieses Skript wird aufgerufen, wenn das Formularfeld gerendert wird. Es kann verwendet werden, um Client-JavaScript zur Validierung des Felds im Client zu erstellen. -
Ein Server-Validierungsskript:
Der Name des Skripts lautetservervalidation.<extension>
, z. B.servervalidation.jsp
.
Dieses Skript wird beim Übermitteln des Formulars aufgerufen. Es kann verwendet werden, um das Feld auf dem Server zu validieren, nachdem das Formular übermittelt wurde.
-
/libs/foundation/components/form/constraints
Globale Formulareinschränkungen :headding-anchor:form-global-constraints
Legen Sie die globale Validierung eines Formulars fest, indem Sie einen Ressourcentyp in der Start-Formularkomponente angeben ( validationRT
). Beispiel:
apps/myProject/components/form/validation
Anschließend können Sie Folgendes definieren:
- ein
clientvalidation.jsp
, das nach den Client-Validierungsskripten des Felds eingefügt wird - und ein
servervalidation.jsp
, das auch nach den einzelnen Feld-Servervalidierungen bei einemPOST
aufgerufen wird.
Ein- und Ausblenden von Formularkomponenten :headding-anchor:showing-and-hiding-form-components
Sie können das Formular so konfigurieren, dass Formularkomponenten abhängig vom Wert anderer Formularfelder ein- oder ausgeblendet werden.
Das Ändern der Sichtbarkeit eines Formularfelds ist nützlich, wenn das Feld nur unter besonderen Bedingungen erforderlich ist. Auf einem Feedback-Formular werden Kunden beispielsweise gefragt, ob ihnen Produktinformationen per E-Mail zugesendet werden sollen. Nach der Auswahl von „Ja“ wird ein Textfeld eingeblendet, damit die Person die eigene E-Mail-Adresse eingeben kann.
Legen Sie mit dem Dialogfeld Einblenden-/Ausblenden-Regeln bearbeiten die Bedingungen fest, unter denen eine Formularkomponente ein- oder ausgeblendet wird.
Legen Sie mit den Feldern, die im Dialogfeld oben sind, die folgenden Informationen fest:
- ob Sie Bedingungen zum Aus- oder Einblenden der Komponente festlegen
- ob eine oder alle Bedingungen erfüllt sein müssen, um die Komponente ein- oder auszublenden
Eine oder mehrere Bedingungen werden unter diesen Feldern eingeblendet. Eine Bedingung vergleicht den Wert einer anderen Formularkomponente (auf dem gleichen Formular) mit einem Wert. Wenn der tatsächliche Wert im Feld die Bedingung erfüllt, wird die Bedingung als wahr ausgewertet. Bedingungen enthalten die folgenden Informationen:
- den Titel des Formularfeldes, das geprüft wird
- einen Operator
- einen Wert, mit dem der Feldwert verglichen wird
Beispiel: eine Optionsfeldgruppen-Komponente mit dem Titel Receive email notifications?
* * enthält die Optionsfelder Yes
und No
. Eine Textfeld-Komponente mit dem Titel Email Address
verwendet die folgende Bedingung, damit sie sichtbar wird, wenn Yes
ausgewählt wird:
In JavaScript verweisen Bedingungen mit dem Wert der Eigenschaft „Elementname“ auf Felder. Im vorigen Beispiel ist contact
der Wert der Eigenschaft „Elementname“ der Optionsfeldgruppen-Komponente. Der folgende Code entspricht dem JavaScript-Code für dieses Beispiel:
((contact == "Yes"))
Ein- oder Ausblenden einer Formular-Komponente:
-
Bearbeiten Sie die entsprechende Formular-Komponente.
-
Wählen Sie Einblenden/Ausblenden aus, um das Dialogfeld „Regeln einblenden/ausblenden“ bearbeiten zu öffnen:
-
Wählen Sie in der ersten Dropdown-Liste entweder Einblenden oder Ausblenden aus, um anzugeben, ob die Bedingungen das Einblenden oder das Ausblenden der Komponente bestimmen.
-
Wählen Sie in der Dropdown-Liste am Ende der obersten Zeile Folgendes aus:
- Alle: Wenn alle Bedingungen wahr sein müssen, um die Komponente ein- oder auszublenden.
- Beliebig: Wenn nur eine oder mehrere Bedingungen wahr sein müssen, um die Komponente ein- oder auszublenden.
-
Wählen Sie in der Bedingungszeile (als Standard wird nur eine gezeigt) eine Komponente und einen Operator aus und geben Sie einen Wert an.
-
Klicken Sie bei Bedarf auf Bedingung hinzufügen, um weitere Bedingungen hinzuzufügen.
Beispiel:
-
-
Klicken Sie auf OK, um die Definition zu speichern.
-
Nachdem Sie Ihre Definition gespeichert haben, wird in den Eigenschaften der Formularkomponente der Link Regeln bearbeiten neben der Option Einblenden/Ausblenden angezeigt. Klicken Sie auf diesen Link, um das Dialogfeld Einblenden-/Ausblenden-Regeln bearbeiten zu öffnen, damit Sie Änderungen vornehmen können.
Klicken Sie auf OK, um alle Änderungen zu speichern.
note caution CAUTION Sie können die Auswirkungen von Ein-/Ausblendedefinitionen überprüfen und testen: -
im Vorschaumodus in der Autorenumgebung (Sie müssen die Seite neu laden, wenn Sie zum ersten Mal zur Vorschau wechseln)
-
in der Veröffentlichungsumgebung
-
Behandlung von nicht mehr gültigen Komponentenverweisen :headding-anchor:handling-broken-component-references
Einblenden/Ausblenden-Bedingungen verweisen mit dem Wert der Eigenschaft „Elementname“ auf andere auf dem Formular befindliche Komponenten. Die Einblenden/Ausblenden-Konfiguration ist ungültig, wenn eine der Bedingungen auf eine Komponente verweist, die gelöscht oder bei der die Eigenschaft „Elementname“ geändert wurde. In diesen Fällen müssen Sie die Bedingungen manuell aktualisieren. Anderenfalls tritt beim Laden des Formulars ein Fehler auf.
Wenn die Einblenden/Ausblenden-Konfiguration ungültig ist, wird die Konfiguration nur als JavaScript-Code bereitgestellt. Bearbeiten Sie den Code, um die Probleme zu beheben. Der Code verwendet die Eigenschaft „Elementname“, mit der ursprünglich auf die Komponenten verwiesen wurde.
Entwicklung von Skripten zur Verwendung mit Formularen :headding-anchor:developing-scripts-for-use-with-forms
Weitere Informationen über die API-Elemente, die Sie zur Erstellung von Skripten verwenden können, finden Sie in den javadocs zu Formularen.
Sie können dies z. B. verwenden, um einen Dienst aufzurufen, bevor das Formular übermittelt wird, und den Dienst abbrechen, wenn es fehlschlägt:
-
Validierungs-Ressourcentyp definieren
-
Aufnehmen eines Skripts zur Überprüfung:
- Rufen Sie in der JSP den Webdienst auf und erstellen Sie ein Objekt
com.day.cq.wcm.foundation.forms.ValidationInfo
mit den Fehlermeldungen. Wenn Fehler auftreten, werden die Formulardaten nicht ausgegeben.
- Rufen Sie in der JSP den Webdienst auf und erstellen Sie ein Objekt