[AEM Forms]{class="badge positive" title="Gilt für AEM Forms)."}

Beispiele für die Entwicklung und Verwendung benutzerdefinierter Funktionen

Dieser Artikel enthält ausführliche Beispiele für benutzerdefinierte Funktionen für ein adaptives Formular, das auf Kernkomponenten basiert, und bietet praktische Einblicke in ihre effektive Implementierung in gängigen Formularerstellungsszenarien wie Validierung, Berechnung und dynamisches Feldverhalten. Benutzerdefinierte Funktionen werden im Regeleditor) Adobe Experience Manager (AEM) Forms-Umgebung verwendet, sodass Entwicklerinnen und Entwickler die Logik definieren und steuern können, die das Formularverhalten steuert.

Was benutzerdefinierte Funktionen tun

Benutzerdefinierte Funktionen erweitern die Funktionen des AEM Forms Regeleditors indem sie es Entwickelnden ermöglichen, wiederverwendbare Geschäftslogik einzukapseln, die andernfalls nur schwer durch vordefinierte Regeln allein zum Ausdruck gebracht werden könnte. Da der Regeleditor diese Funktionen direkt für Formularautoren bereitstellt, können Teams komplexe Logik einmal standardisieren und sie konsistent auf mehrere Formulare anwenden. Dies reduziert Duplikate, verbessert die Wartbarkeit und stellt sicher, dass spezialisiertes Verhalten - wie benutzerdefinierte Validierung oder Datenumwandlung - zentralisiert bleibt und einfach aktualisiert werden kann.

In diesem Artikel werden verschiedene Implementierungen von benutzerdefinierten Funktionen untersucht, wobei gezeigt wird, wie sie verwendet werden können, um adaptive Forms an spezifische Geschäftsanforderungen anzupassen und die allgemeine Formularfunktionalität zu verbessern.

Häufige Anwendungsfälle für benutzerdefinierte Funktionen

Benutzerdefinierte Funktionen werden in der Regel angewendet, um zielgerichtete Herausforderungen mit der Formularlogik zu lösen. Zu den wichtigsten Anwendungsfällen gehören:

Durch die Zentralisierung dieser Logik in benutzerdefinierten Funktionen erstellen Entwickler adaptive Forms, die anpassbarer, einfacher zu verwalten und besser an spezifische Organisationsanforderungen angepasst sind.

Füllen der Dropdown-Listenoptionen mit benutzerdefinierten Funktionen

Der Regeleditor in den Kernkomponenten unterstützt die Eigenschaft Optionen festlegen nicht, um Dropdown-Listenoptionen zur Laufzeit dynamisch zu füllen. Sie können Dropdown-Listenoptionen jedoch mithilfe von benutzerdefinierten Funktionen auffüllen, die Optionen basierend auf einer bestimmten Geschäftslogik zur Laufzeit abrufen. Benutzerdefinierte Funktionen bieten mehr Flexibilität und Kontrolle darüber, wie und wann die Dropdown-Optionen ausgefüllt werden, und verbessern das Benutzererlebnis.

Hinzufügen des benutzerdefinierten Funktions-Codes

Um die Optionen der Dropdown-Liste mit einer benutzerdefinierten Funktion zu füllen, führen Sie die folgenden Schritte aus:

Erstellen Sie eine Regel, um die benutzerdefinierte Funktion aufzurufen

Die folgende Abbildung zeigt, wo die Optionen der Dropdown-Liste beim Klicken auf die Schaltfläche festgelegt werden. Sobald die Regel angewendet wird, wird die Dropdown-Liste zur Laufzeit mit den sieben Wochentagsoptionen gefüllt, wodurch bestätigt wird, dass die benutzerdefinierte Funktion sowohl die gespeicherten Werte als auch ihre Anzeigebeschriftungen erfolgreich bereitgestellt hat.

Anzeigen eines Bereichs mithilfe der SetProperty

Benutzerdefinierte Funktionen verwenden Feld- und globale Objekte zur Steuerung des Formularverhaltens, wie unten mit einem Contact Us Formular gezeigt.

Fügen Sie den folgenden Code in der benutzerdefinierten Funktion hinzu, wie im Abschnitt create-custom-function beschrieben, um das Formularfeld auf Required festzulegen.

    /**
    * enablePanel
    * @name enablePanel
    * @param {object} field1
    * @param {object} field2
    * @param {scope} globals
    */

    function enablePanel(field1,field2, globals)
    {
       if(globals.functions.validate(field1).length === 0)
       {
       globals.functions.setProperty(field2, {visible: true});
       }
    }

Funktionsweise der Sichtbarkeitslogik des Bedienfelds

In diesem Beispiel wird durch Klicken auf die Schaltfläche die Validierung des personaldetails Bedienfelds Trigger. Wenn das Bedienfeld keine Fehler enthält, wird das feedback Bedienfeld angezeigt. Dadurch wird sichergestellt, dass das feedback nur angezeigt wird, wenn das personaldetails fehlerfrei ist.

Erstellen einer Regel für die Next

Erstellen Sie eine Regel für die Schaltfläche Next , die das personaldetails überprüft und das feedback einblendet. Die Regel führt die folgenden Aktionen aus, wenn der Benutzer auf die Schaltfläche Next klickt:

Erwartetes Verhalten

Siehe die unten stehende Abbildung. Sie zeigt, wo das personaldetails nach dem Klicken auf die Schaltfläche Next validiert wird. Wenn alle Felder im personaldetails Bedienfeld erfolgreich validiert wurden, wird das feedback Bedienfeld angezeigt.

Wenn Fehler in den Feldern des personaldetails Bedienfelds vorhanden sind, werden diese Fehler beim Klicken auf die Schaltfläche Next auf Feldebene angezeigt. Daher bleibt das feedback Bedienfeld unsichtbar, bis der/die Benutzende die Fehler korrigiert und das Bedienfeld ohne Probleme validiert.

Überprüfen des Felds

Benutzerdefinierte Funktionen validieren ein Feld, indem sie mit zwei Laufzeitobjekten arbeiten: dem field-Objekt, das das spezifische Formularfeld darstellt, das überprüft wird, und dem globals-Objekt, das integrierte Formularfunktionen wie validate() verfügbar macht. In diesem Abschnitt wird anhand eines Contact Us Formulars als Beispiel gezeigt, wie diese Objekte bei der Validierung eines Felds zusammenarbeiten.

Fügen Sie den folgenden Code in der benutzerdefinierten Funktion hinzu, wie im Abschnitt create-custom-function beschrieben, um das Feld zu validieren.

    /**
    * validateField
    * @name validateField
    * @param {object} field
    * @param {scope} globals
    */
    function validateField(field,globals)
    {

        globals.functions.validate(field);

    }

Der globals.functions.validate(field) Aufruf ruft die integrierte Validierung der Plattform für das übergebene field auf. Dadurch wird das Feld anhand der konfigurierten Einschränkungen ausgewertet. Wenn die Eingabe diese Einschränkungen nicht erfüllt, wird die zugehörige Fehlermeldung auf Feldebene als Trigger angezeigt.

In diesem Beispiel wird ein benutzerdefiniertes Überprüfungsmuster auf das Feld contact angewendet. Das Feld erzwingt ein striktes Telefonnummernformat:

Da diese Regeln zusammen durchgesetzt werden, schlägt die Validierung aller Eingaben, die eine der Bedingungen verletzen, fehl. Wenn Benutzende eine Telefonnummer eingeben, die nicht mit 10 beginnt oder mehr oder weniger als 8 Ziffern enthält, schlägt die Überprüfung im Feld fehl und zeigt eine Validierungsfehlermeldung an, sobald auf die Schaltfläche geklickt wird.

Der nächste Schritt besteht darin, eine Regel für die Schaltfläche “Next” zu erstellen, die das contact beim Klicken auf die Schaltfläche validiert. Diese Regel verknüpft die Validierungslogik mit der Benutzeraktion und stellt sicher, dass das Feld überprüft wird, bevor das Formular weitergeleitet wird.

Die folgende Abbildung zeigt das Verhalten auf Feldebene: Wenn Benutzende eine Telefonnummer eingeben, die nicht mit 10 beginnt, schlägt die Validierung fehl und direkt auf Feldebene wird eine Fehlermeldung angezeigt.

Wenn der Benutzer eine gültige Telefonnummer eingibt und alle Felder im personaldetails-Bereich die Validierung bestehen, wird das feedback-Bedienfeld auf dem Bildschirm angezeigt. Dadurch wird bestätigt, dass die erfolgreiche Validierung aller erforderlichen Felder im Bereich die Bedingung ist, durch die die nächste Phase des Formulars entsperrt wird.

Zurücksetzen eines Bedienfelds

Benutzerdefinierte Funktionen setzen ein Bedienfeld zurück, indem sie die Objekte field und global verwenden, wie hier mit einem Contact Us Formular gezeigt. Das field-Objekt stellt die spezifische Formularkomponente dar, für die eine Aktion durchgeführt wird, während das global-Objekt (globals) Zugriff auf die integrierten Funktionen des Formulars bietet, einschließlich des Zurücksetzungsvorgangs.

Fügen Sie den folgenden Code in der benutzerdefinierten Funktion hinzu, wie im Abschnitt create-custom-function beschrieben, um das Bedienfeld zurückzusetzen.

    /**
    * resetField
    * @name  resetField
    * @param {string} input1
    * @param {object} field
    * @param {scope} globals
    */
    function  resetField(field,globals)
    {

        globals.functions.reset(field);

    }

Der globals.functions.reset(field)-Aufruf löscht die Werte der angegebenen field und stellt den anvisierten Bereich wieder in den leeren Anfangszustand zurück. Die Übergabe des field-Arguments teilt der Rücksetzungsfunktion genau mit, welche Komponente gelöscht werden soll. Aus diesem Grund wird das Bedienfeld - und nicht das gesamte Formular - zurückgesetzt.

In diesem Beispiel wird das personaldetailsPanel Klicken auf die Schaltfläche Clearzurückgesetzt. Dies tritt auf, weil die Funktion resetField das personaldetails Panel als field Argument erhält und an globals.functions.reset() übergibt.

Erstellen einer Regel für die Schaltfläche „Löschen“

Der nächste Schritt besteht darin, eine Regel für die Schaltfläche Clear zu erstellen, die den Bereich beim Klicken auf die Schaltfläche zurücksetzt. Diese Regel bindet das Schaltflächen-Klickereignis an die benutzerdefinierte Funktion resetField und stellt sicher, dass die Aktion zum Zurücksetzen jedes Mal ausgeführt wird, wenn der Benutzer auf die Schaltfläche “Clear” klickt.

Die folgende Abbildung zeigt, dass das personaldetails zurückgesetzt wird, wenn der Benutzer auf die Schaltfläche Clear klickt:

So zeigen Sie eine benutzerdefinierte Meldung auf Feldebene an und markieren das Feld als ungültig

Benutzerdefinierte Funktionen verwenden das Feld und globale Objekte, um eine benutzerdefinierte Meldung auf Feldebene anzuzeigen und das Feld als ungültig zu markieren, wie hier mit einem Contact Us Formular gezeigt. Das Feldobjekt stellt das einzelne Formularfeld dar, das validiert wird, während globales Objekt (globals) integrierte Hilfsfunktionen wie Validierungs-Dienstprogramme verfügbar macht.

Die Funktion markFieldAsInvalid() definiert ein Feld als ungültig und legt eine benutzerdefinierte Fehlermeldung auf Feldebene fest. Sie akzeptiert eine Feldkennung, eine benutzerdefinierte Nachricht und ein Optionsobjekt, das angibt, wie das Feld identifiziert wird.

Feldkennung (fieldIdentifier) — Übergeben Sie einen der folgenden Werte:

Optionsobjekt (option) - Übergeben Sie die entsprechende Option, die der ausgewählten Kennung entspricht:

Syntax zum Kennzeichnen eines Felds als ungültig

Verwenden Sie eine der folgenden Syntaxen, um ein Feld als ungültig zu markieren und eine benutzerdefinierte Nachricht festzulegen:

Benutzerdefinierter Funktions-Code

Fügen Sie den folgenden Code in der benutzerdefinierten Funktion hinzu, wie im Abschnitt create-custom-function erläutert, um eine benutzerdefinierte Nachricht auf Feldebene zu aktivieren:

    /**
    * customMessage
    * @name customMessage
    * @param {object} field
    * @param {scope} globals
    */
    function customMessage(field, globals) {
    const minLength = 15;
    const comments = field.$value.trim();
    if (comments.length < minLength) {
        globals.functions.markFieldAsInvalid(field.$id, "Comments must be at least 15 characters long.", { useId: true });
    }
}

Wenn in diesem Beispiel Benutzende weniger als 15 Zeichen in Textfeld Kommentare eingeben, wird eine benutzerdefinierte Meldung auf Feldebene angezeigt. Dies erzwingt eine minimale Eingabelänge, da die Funktion den eingegebenen Wert trimmt und seine Länge mit dem minLength Schwellenwert von 15 vergleicht, wodurch das Feld ungültig wird, wenn die Anforderung nicht erfüllt ist.

Feldvalidierungsverhalten

Der nächste Schritt besteht darin, eine Regel für das comments Feld zu erstellen, die die benutzerdefinierte Funktion customMessage aufruft, sie an das Feld zu binden, sodass die Validierung ausgeführt wird, wenn der Benutzer Eingaben bereitstellt.

Wie gezeigt, wird durch die Eingabe von Kurz- oder Negativfeedback von weniger als 15 Zeichen in das comments Feld die Anzeige der benutzerdefinierten Nachricht auf Feldebene Trigger, wodurch der Eintrag als ungültig markiert wird.

Wenn der/die Benutzende 15 oder mehr Zeichen in das Textfeld „Kommentare“ eingibt, wird die Überprüfung des Felds erfolgreich durchgeführt und das Formular übermittelt.

Senden geänderter Daten an den Server

Benutzerdefinierte Funktionen senden bearbeitete Formulardaten an den Server, indem sie Feld- und globale Objekte kombinieren, wie hier mit einem Contact Us Formular gezeigt. Die Kernmethode ist globals.functions.submitForm(), die Formulardaten übermittelt, nachdem eine Manipulation angewendet wurde.

Die folgende Codezeile übermittelt die Formulardaten nach der Bearbeitung:

globals.functions.submitForm(globals.functions.exportData(), false);

Grundlagen zu den Argumenten von submitForm

Die submitForm-Methode akzeptiert drei Argumente, die steuern, was wie übermittelt wird:

Beispiel: Übermitteln eines Standardwerts für leere Felder

Fügen Sie in der benutzerdefinierten Funktion den folgenden Code hinzu, wie im Abschnitt create-custom-function beschrieben, um die bearbeiteten Daten an den Server zu senden:

    /**
    * submitData
    * @name submitData
    * @param {object} field
    * @param {scope} globals
    */
    function submitData(globals)
    {

    var data = globals.functions.exportData();
    if(!data.comments) {
    data.comments = 'NA';
    }
    console.log('After update:{}',data);
    globals.functions.submitForm(data, false);
    }

Wenn der Benutzer in diesem Beispiel das comments Textfeld leer lässt, wird der NA bei der Formularübermittlung an den Server gesendet. Diese Ersetzung stellt sicher, dass der Server immer einen definierten Wert für das comments erhält, wodurch die Datenintegrität erhalten bleibt und leere oder undefinierte Einträge in der gesendeten Payload verhindert werden.

Binden der Funktion an die Senden-Schaltfläche

Erstellen Sie anschließend eine Regel für die Schaltfläche Submit , die die benutzerdefinierte Funktion submitData aufruft. Diese Regel verbindet die Sende-Aktion der Schaltfläche mit der -Funktion, sodass, wenn Benutzende Submit auswählen, die bearbeiteten Daten - einschließlich des NA für leere Kommentare - an den Server gesendet werden.

Informationen zum Bestätigen des Verhaltens finden Sie in der Abbildung der console window. Wenn der/die Benutzende das comments Textfeld leer lässt, wird in der Konsolenausgabe das aktualisierte Datenobjekt vor der Übermittlung mit dem Wert angezeigt, der durch das comments Feld ersetzt NA, was zeigt, dass der Standardwert auf dem Server angewendet wird.

Sie können auch das Konsolenfenster überprüfen, um die genauen Daten anzuzeigen, die an den Server gesendet wurden. Die protokollierte Ausgabe, die durch die console.log('After update:{}', data)-Anweisung erzeugt wird, spiegelt das endgültige Datenobjekt nach der Bearbeitung wider, sodass Sie überprüfen können, ob die erwarteten Werte - einschließlich Standardersetzungen - vorhanden sind, bevor die Daten den Server erreichen.

Überschreiben der erfolgreichen Formularübermittlung und der Fehler-Handler

Benutzerdefinierte Funktionen verwenden Feld- und globale Objekte, um die standardmäßigen Übermittlungs-Handler in Adobe Experience Manager (AEM) Forms zu überschreiben. In diesem Beispiel wird ein Contact Us Formular verwendet, um zu veranschaulichen, wie die Erfolgsmeldung und die Fehlermeldung angepasst werden und wie diese Formularübermittlungsmeldungen in einem modalen Dialogfeld“ angezeigt.

Fügen Sie die folgende Codezeile hinzu, wie im Abschnitt create-custom-features erläutert, um die Übermittlungs- oder Fehlermeldung für Formularübermittlungen anzupassen und die Meldungen zur Formularübermittlung in einem modalen Dialogfeld anzuzeigen:

/**
 * Handles the success response after a form submission.
 *
 * @param {scope} globals - This object contains a read-only form instance, target field instance, triggered event, and methods for performing form modifications within custom functions.
 * @returns {void}
 */
function customSubmitSuccessHandler(globals) {
    var event = globals.event;
    var submitSuccessResponse = event.payload.body;
    var form = globals.form;

    if (submitSuccessResponse) {
        if (submitSuccessResponse.redirectUrl) {
            window.location.href = encodeURI(submitSuccessResponse.redirectUrl);
        } else if (submitSuccessResponse.thankYouMessage) {
            showModal("success", submitSuccessResponse.thankYouMessage);
        }
    }
}

/**
 * Handles the error response after a form submission.
 *
 * @param {string} customSubmitErrorMessage - The custom error message.
 * @param {scope} globals - This object contains a read-only form instance, target field instance, triggered event, and methods for performing form modifications within custom functions.
 * @returns {void}
 */
function customSubmitErrorHandler(customSubmitErrorMessage, globals) {
    showModal("error", customSubmitErrorMessage);
}
function showModal(type, message) {
    // Remove any existing modals
    var existingModal = document.getElementById("modal");
    if (existingModal) {
        existingModal.remove();
    }

    // Create the modal dialog
    var modal = document.createElement("div");
    modal.setAttribute("id", "modal");
    modal.setAttribute("class", "modal");

    // Create the modal content
    var modalContent = document.createElement("div");
    modalContent.setAttribute("class", "modal-content");

    // Create the modal header
    var modalHeader = document.createElement("div");
    modalHeader.setAttribute("class", "modal-header");
    modalHeader.innerHTML = "<h2>" + (type === "success" ? "Thank You" : "Error") + "</h2>";

    // Create the modal body
    var modalBody = document.createElement("div");
    modalBody.setAttribute("class", "modal-body");
    modalBody.innerHTML = "<p class='" + type + "-message'>" + message + "</p>";

    // Create the modal footer
    var modalFooter = document.createElement("div");
    modalFooter.setAttribute("class", "modal-footer");

    // Create the close button
    var closeButton = document.createElement("button");
    closeButton.setAttribute("class", "close-button");
    closeButton.innerHTML = "Close";
    closeButton.onclick = function() {
        modal.remove();
    };

    // Append the elements to the modal content
    modalFooter.appendChild(closeButton);
    modalContent.appendChild(modalHeader);
    modalContent.appendChild(modalBody);
    modalContent.appendChild(modalFooter);

    // Append the modal content to the modal
    modal.appendChild(modalContent);

    // Append the modal to the document body
    document.body.appendChild(modal);
}

Funktionsweise der benutzerdefinierten Handler

In diesem Beispiel zeigen die benutzerdefinierten Funktionen customSubmitSuccessHandler und customSubmitErrorHandler die Erfolgs- und Fehlermeldungen in einem modalen Dialogfeld an. Der customSubmitSuccessHandler liest die Übermittlungsantwort aus globals.event.payload.body und leitet den Benutzer entweder zu einer redirectUrl weiter oder zeigt eine thankYouMessage in einem modalen Fenster an. Der customSubmitErrorHandler erhält die benutzerdefinierte Fehlermeldung und übergibt sie direkt an das Modal .

Die JavaScript-Funktion erstellt showModal(type, message) dynamisch und zeigt auf dem Bildschirm ein modales Dialogfeld an. Zunächst werden alle vorhandenen Modale entfernt, um Duplikate zu vermeiden. Anschließend werden die modale Kopfzeile, der Hauptteil, die Fußzeile und eine Schaltfläche Schließen erstellt, bevor das fertige Dialogfeld an den Dokumenthauptteil angehängt wird. Dadurch wird sichergestellt, dass jeweils nur ein Modal angezeigt wird und dass sowohl Erfolgs- als auch Fehlerantworten dieselbe Rendering-Logik wiederverwenden.

Erstellen von Übermittlungsregeln

Erstellen Sie nach dem Hinzufügen der benutzerdefinierten Funktionen Regeln, die sie an den entsprechenden Stellen im Ablauf der Formularübermittlung aufrufen:

Standard-Übermittlungs-Handler

Um die erfolgreiche und fehlgeschlagene Übermittlung eines Formulars standardmäßig anzuzeigen, sind die Funktionen Default submit Form Success Handler und Default submit Form Error Handler standardmäßig verfügbar. Diese integrierten Handler bieten Standardverhalten, ohne dass benutzerdefinierter Code erforderlich ist. Daher benötigen Sie nur die oben genannten benutzerdefinierten Handler, wenn Sie ein maßgeschneidertes Messaging oder ein modales Erlebnis wünschen.

Wenn der benutzerdefinierte Übermittlungs-Handler in bestehenden Adobe Experience Manager (AEM)-Projekten oder -Formularen nicht wie erwartet funktioniert, lesen Sie den Abschnitt Fehlerbehebung.

Ausführen von Aktionen in einer bestimmten Instanz des wiederholbaren Bereichs

Regeln, die mit dem visuellen Regeleditor in einem wiederholbaren Bereich erstellt wurden, gelten nur für die letzte Instanz des wiederholbaren Bereichs. Da der visuelle Regeleditor nur für die letzte Instanz vorgesehen ist, ist eine benutzerdefinierte Funktion erforderlich, um Aktionen für jede andere spezifische Instanz eines wiederholbaren Bereichs durchzuführen.

Stellen Sie sich einen Booking Form vor, der erstellt wurde, um Informationen über Reisende zu sammeln, die zu einem Ziel unterwegs sind. Ein Reisenden-Panel wird als wiederholbares Panel hinzugefügt, sodass Benutzende mithilfe der Schaltfläche Add Traveler Details für bis zu 5 Reisende können.

Hinzufügen der benutzerdefinierten Funktion

Fügen Sie den folgenden Code hinzu, wie im Abschnitt create-custom-function erläutert, um Aktionen in einer bestimmten Instanz des wiederholbaren Bereichs durchzuführen, die nicht der letzte ist:

/**
* @name hidePanelInRepeatablePanel
* @param {scope} globals
*/
function hidePanelInRepeatablePanel(globals)
{
    var repeatablePanel = globals.form.travelerinfo;
    // hides a panel inside second instance of repeatable panel
    globals.functions.setProperty(repeatablePanel[1].traveler, {visible : false});
}

Funktionsweise der benutzerdefinierten Funktion

Die benutzerdefinierte Funktion hidePanelInRepeatablePanel führt eine Aktion in einer bestimmten Instanz des wiederholbaren Bereichs aus. Der Code funktioniert wie folgt:

Trigger der Regel mit einer Schaltfläche

Fügen Sie eine Schaltfläche mit der Bezeichnung Hide hinzu und fügen Sie eine Regel an, die die benutzerdefinierte Funktion aufruft, um die zweite Instanz des wiederholbaren Bereichs auszublenden.

Sehen Sie sich das folgende Video an, das zeigt, dass beim Klicken auf die Schaltfläche Hide der Bereich in der zweiten wiederholbaren Instanz ausgeblendet wird:

Füllen Sie das Feld beim Laden des Formulars mit einem Wert vorab aus

Benutzerdefinierte Funktionen verwenden Feld- und globale Objekte zum Vorausfüllen eines Felds, wie hier mit einem Buchungsformular gezeigt. Wenn das Buchungsformular geladen wird, wird das Textfeld Buchungsbetrag automatisch mit einem angegebenen Wert ausgefüllt. In diesem Beispiel erfordert das Formular einen Mindestbuchungsbetrag von 10.000, sodass das Feld bei der Initialisierung mit 10,000 vorausgefüllt wird.

Vorausfüllen des Felds durch die benutzerdefinierte Funktion

Fügen Sie die folgende Codezeile hinzu, wie im Abschnitt create-custom-function erläutert, um den vorausgefüllten Wert in ein Feld zu laden, wenn das Formular initialisiert wird:

/**
 * Tests import data
 * @name testImportData
 * @param {scope} globals
 */
function testImportData(globals)
{
    globals.functions.importData(Object.fromEntries([['amount','10000']]));
}

In diesem Code füllt die Funktion testImportData das Textfeld Buchungsbetrag vorab, wenn das Formular geladen wird. Die Funktion erreicht dies durch die globals.functions.importData()-Methode:

Da die Funktion bei der Initialisierung des Formulars ausgeführt wird, ist der Wert vorhanden, sobald das Formular gerendert wird, sodass die Mindestbuchungsbetrag-Anforderung standardmäßig erfüllt ist.

Erstellen einer Regel bei Formularinitialisierung

Das Buchungsformular erfordert einen Mindestbuchungsbetrag von .000. Erstellen Sie eine Regel bei der Initialisierung des Formulars, damit der Wert im Textfeld Buchungsbetrag beim Laden des Formulars mit dem angegebenen Wert vorausgefüllt wird. Durch das Binden der benutzerdefinierten testImportData an das Initialisierungsereignis des Formulars wird das Vorbefüllen automatisch Trigger, ohne dass der Benutzer den Wert manuell eingeben muss.

Der folgende Screenshot zeigt, dass beim Laden des Formulars der Wert im Textfeld Buchungsbetrag mit dem angegebenen Wert von 10.000“ ist. Dadurch wird bestätigt, dass die benutzerdefinierte Funktion bei der Initialisierung erfolgreich ausgeführt wurde und dass das Feld den vorgesehenen Standardbuchungsbetrag widerspiegelt, sobald das Formular angezeigt wird.

Fokus auf das spezifische Feld legen

Benutzerdefinierte Funktionen verwenden die Objekte field und global, um den Fokus auf ein bestimmtes Feld zu legen. Das folgende Beispiel zeigt dieses Verhalten mithilfe eines Buchungsformulars.

Die setFocus-Funktion verschiebt den Eingabe-Cursor programmgesteuert in ein bestimmtes Formularfeld, lenkt die Aufmerksamkeit der Benutzenden auf dieses Feld und optimiert die Dateneingabe. Dies ist besonders nützlich, um Benutzende durch erforderliche Felder zu führen oder das nächste Feld hervorzuheben, das sie ausfüllen müssen.

Schritt 1: Benutzerdefinierte Funktion definieren

Fügen Sie die folgende Codezeile hinzu, wie im Abschnitt create-custom-function erläutert, um den Fokus auf das angegebene Feld zu legen, wenn auf die Submit-Schaltfläche geklickt wird:

/**
 * @name testSetFocus
 * @param {object} emailField
 * @param {scope} globals
 */
    function testSetFocus(field, globals)
    {
        globals.functions.setFocus(field);
    }

In dieser Funktion ruft globals.functions.setFocus(field) die integrierte Fokusmethode auf und übergibt das Ziel-field-Objekt, sodass sich der Cursor zur Laufzeit zu diesem Feld bewegt. Das globals-Objekt bietet Zugriff auf die Funktionen auf Formularebene, während der field-Parameter angibt, welches Feld den Fokus erhält.

Schritt 2: Regel an die Schaltfläche „Senden“ anhängen

Fügen Sie eine Regel zur Schaltfläche Submit hinzu, sodass der Fokus beim Klicken auf die Schaltfläche auf das Textfeld Email ID gelegt wird. Gehen Sie hierfür wie folgt vor:

Schritt 3: Überprüfen des Fokusverhaltens

Der folgende Screenshot zeigt das Ergebnis: Wenn Sie auf die Schaltfläche “Submit” klicken, wechselt der Fokus direkt zum Feld “Email ID”, wo Sie den Cursor platzieren und ihn für die Eingabe vorbereiten können.

Hinzufügen oder Löschen eines wiederholbaren Bereichs mithilfe der dispatchEvent

Mit der dispatchEvent-Eigenschaft können benutzerdefinierte Funktionen einen (Bereich) hinzufügen oder löschen indem sie die addInstance- und removeInstance-Ereignisse für ein Bereichsobjekt auslösen. Erfahren Sie, wie benutzerdefinierte Funktionen Feld- und globale Objekte verwenden, um wiederholbare Bereiche über die dispatchEvent-Eigenschaft zu steuern, demonstriert mit einem Booking Form.

Ein wiederholbarer Bereich ist ein Formularabschnitt, der zur Laufzeit dupliziert werden kann, sodass ein einzelnes Layout - z. B. die Details eines Reisenden - so oft wie nötig wiederholt werden kann. Die dispatchEvent-Funktion erstellt programmgesteuert Trigger auf Bereichsebene, sodass durch den Aufruf mit addInstance eine neue Kopie des Bereichs erstellt wird und durch den Aufruf mit removeInstance eine Kopie entfernt wird.

Hinzufügen eines wiederholbaren Bereichs mit addInstance

Fügen Sie die folgende Codezeile hinzu, wie im Abschnitt create-custom-function beschrieben, um einen Bereich hinzuzufügen, wenn mithilfe der dispatchEvent-Eigenschaft auf die Schaltfläche Add Traveler geklickt wird. Das addInstance-Ereignis weist das Formular an, den traveler Bereich zu wiederholen, wodurch jedes Mal, wenn es gesendet wird, eine neue Instanz erzeugt wird:

/**
 * Tests add instance with dispatchEvent
 * @name testAddInstance
 * @param {scope} globals
 */
function testAddInstance(globals)
{
    var repeatablePanel = globals.form.traveler;
    globals.functions.dispatchEvent(repeatablePanel,'addInstance');
}

Fügen Sie der Schaltfläche Add Traveler eine Regel hinzu, um den wiederholbaren Bereich hinzuzufügen, wenn Sie auf die Schaltfläche klicken.

Siehe die unten stehende GIF. Da die Regel dispatchEvent mit addInstance aufruft, wird durch Klicken auf die Schaltfläche Add Traveler dem Formular ein neues Bedienfeld für Reisende hinzugefügt:

Löschen eines wiederholbaren Bereichs mit removeInstance

Fügen Sie auf ähnliche Weise die folgende Codezeile hinzu, wie im Abschnitt create-custom-function erläutert, um einen Bereich zu löschen, wenn mithilfe der dispatchEvent-Eigenschaft auf die Schaltfläche Delete Traveler geklickt wird. Das removeInstance-Ereignis weist das Formular an, eine Instanz des Bedienfelds „Wiederholte traveler" zu entfernen:

/**

 * @name testRemoveInstance
 * @param {scope} globals
 */
function testRemoveInstance(globals)
{
    var repeatablePanel = globals.form.traveler;
    globals.functions.dispatchEvent(repeatablePanel, 'removeInstance');
}

Fügen Sie der Schaltfläche Delete Traveler eine Regel hinzu, um den wiederholbaren Bereich beim Klicken auf die Schaltfläche zu löschen.

Siehe die unten stehende GIF. Da die Regel dispatchEvent mit removeInstance aufruft, wird beim Klicken auf die Schaltfläche Delete Traveler das Reisenden-Bedienfeld aus dem Formular gelöscht:

Bekanntes Problem

Benutzerdefinierte Funktionen unterstützen keine Literale für reguläre Ausdrücke in JavaScript. Reguläre Ausdrücke, die mit literaler Syntax) geschrieben (durch Schrägstriche wie /^abc$/ getrennt) werden, werden in benutzerdefinierten Funktionen nicht unterstützt. Daher führt die Verwendung eines Regex-Literals in einer benutzerdefinierten Funktion direkt zu Fehlern während der Ausführung. Um reguläre Ausdrücke zuverlässig zu erstellen, verwenden Sie stattdessen den RegExp Konstruktor.

Betroffenes Code-Muster

Die folgende Literalsyntax wird nicht unterstützt und verursacht einen Ausführungsfehler als Trigger:

const pattern = /^abc$/;

Da benutzerdefinierte Funktionen keine Literale regulärer Ausdrücke erkennen, schlägt diese Zeile zur Laufzeit fehl, anstatt erfolgreich kompiliert und ausgeführt zu werden.

Empfohlene Problemumgehung

Um die Kompatibilität zu gewährleisten, ersetzen Sie jedes Literal regulärer Ausdrücke durch einen entsprechenden Ausdruck, der durch den RegExp-Konstruktor) erstellt. Der RegExp-Konstruktor akzeptiert das Muster als Zeichenfolgenargument und erzeugt dasselbe Objekt für reguläre Ausdrücke, das andernfalls vom Literal erstellt würde.

Warum das wichtig ist

Das Umgestalten regulärer Ausdrücke für die Verwendung des RegExp-Konstruktors gewährleistet eine konsistente und zuverlässige Ausführung innerhalb benutzerdefinierter Funktionen. In JavaScript sind die literale Syntax und der RegExp-Konstruktor zwei äquivalente Möglichkeiten, dasselbe Muster zu definieren. Hier wird jedoch nur die Konstruktorform unterstützt. Durch die Standardisierung des Konstruktorformulars werden die Laufzeitfehler verhindert, die durch nicht unterstützte Literalsyntax verursacht werden, und es wird ein vorhersehbares, portables Verhalten über benutzerdefinierte Funktionen hinweg erzeugt.

Fehlerbehebung

Wenn der benutzerdefinierte Übermittlungs-Handler in bestehenden Adobe Experience Manager (AEM)-Projekten oder -Formularen nicht wie erwartet funktioniert, beginnt die Auflösung mit einer Versionsaktualisierung, gefolgt von projekt- und formularspezifischen Korrekturschritten.

Aktualisieren Sie zunächst die AEM-Kernkomponenten auf Version 3.0.18 oder höher. Diese Versionsausrichtung ist erforderlich, da sich das Verhalten des benutzerdefinierten Übermittlungs-Handlers in den neueren Kernkomponenten geändert hat und vorhandene Projekte und Formulare, die mit früheren Versionen erstellt wurden, die veraltete submitForm('custom:submitSuccess', 'custom:submitError')-Signatur beibehalten, die nicht mehr korrekt aufgelöst wird. Die Aktualisierung der Kernkomponenten ist erforderlich, reicht aber nicht aus. Bestehende AEM-Projekte und -Formulare erfordern die folgenden zusätzlichen Schritte.

Lösung für AEM-Projekte

Für ein vorhandenes AEM-Projekt muss der Entwickler den veralteten Übermittlungsaufruf migrieren:

Auflösung für bestehende Forms

Bei vorhandenen Formularen, bei denen die benutzerdefinierten Übermittlungs-Handler nicht ordnungsgemäß funktionieren, wird die Änderung über den Regeleditor und nicht über Code angewendet:

Beim erneuten Speichern der Regel wird sie für die aktualisierten Kernkomponenten neu generiert, wodurch veraltete submitForm('custom:submitSuccess', 'custom:submitError')-Regel durchsubmitForm() im Formular ersetzt wird. Daher wird das Formular an das aktuelle Verhalten des Übermittlungs-Handlers angepasst, und die benutzerdefinierten Handler funktionieren wieder ordnungsgemäß. Dies funktioniert, weil der Regeleditor die Regeldefinition beim Speichern neu schreibt. Daher reicht es aus, das Formular einfach zu öffnen und zu speichern, ohne die zugrunde liegende Regel manuell zu bearbeiten.

Siehe auch