Beispiele für die Entwicklung und Verwendung benutzerdefinierter Funktionen

Der Artikel enthält die detaillierten Beispiele für benutzerdefinierte Funktionen für ein adaptives Formular, das auf Kernkomponenten basiert, und bietet wertvolle Einblicke in ihre effektive Implementierung in verschiedenen Szenarien. Benutzerdefinierte Funktionen werden im Regeleditor einer AEM Forms verwendet und ermöglichen es Entwickelnden, die Logik zu definieren und zu steuern, die das Formularverhalten steuert.
In diesem Artikel werden verschiedene Implementierungen benutzerdefinierter Funktionen untersucht und gezeigt, wie sie verwendet werden können, um Formulare an spezifische Anforderungen anzupassen und die allgemeine Funktionalität zu verbessern.

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 jedoch Dropdown-Listenoptionen mit benutzerdefinierten Funktionen füllen, mit denen Sie Optionen basierend auf einer bestimmten Logik abrufen können. Benutzerdefinierte Funktionen bieten mehr Flexibilität und Kontrolle darüber, wie und wann die Dropdown-Optionen ausgefüllt werden, und verbessern das Benutzererlebnis.

Um die Dropdown-Listenoptionen mit einer benutzerdefinierten Funktion zu füllen, fügen Sie den folgenden Code hinzu, wie im Abschnitt create-custom-function beschrieben:

    /**
    * @name setEnums
    * @returns {string[]}
    **/
    function setEnums() {
    return ["0","1","2","3","4","5","6"];
    }

    /**
    * @name setEnumNames
    * @returns {string[]}
    **/
    function setEnumNames() {
    return ["Sunday","Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
    }

Im obigen Code wird setEnums verwendet, um die enum-Eigenschaft festzulegen, und setEnumNames wird verwendet, um die enumNames-Eigenschaft von Dropdown festzulegen.

Erstellen wir eine Regel für die Schaltfläche Next , die den Wert der Dropdown-Listenoption festlegt, wenn der Benutzer auf die Schaltfläche Next klickt:

Anhand der unten stehenden Abbildung können Sie sehen, wo die Optionen der Dropdown-Liste eingestellt sind, wenn Sie auf die Schaltfläche Anzeigen klicken:

Anzeigen eines Bereichs mithilfe der SetProperty

Im Folgenden erfahren Sie, wie benutzerdefinierte Funktionen mithilfe eines Contact Us Formulars Felder und globale Objekte verwenden.

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});
       }
    }

In diesem Beispiel wird das Bedienfeld personaldetails durch Klicken auf die Schaltfläche überprüft. Wenn im Bedienfeld keine Fehler erkannt werden, wird ein weiteres Bedienfeld, das Bedienfeld feedback, beim Klicken auf die Schaltfläche angezeigt.

Erstellen wir eine Regel für die Schaltfläche Next, die das Bedienfeld personaldetails validiert und das Bedienfeld feedback sichtbar macht, wenn Benutzende auf die Schaltfläche Next klicken.

In der folgenden Abbildung sehen Sie, wie das Bedienfeld personaldetails beim Klicken auf die Schaltfläche Next validiert wird. Falls alle Felder innerhalb der personaldetails validiert werden, wird das Bedienfeld feedback angezeigt.

Wenn Fehler in den Feldern des Bedienfelds personaldetails vorhanden sind, werden sie beim Klicken auf die Schaltfläche Next auf Feldebene angezeigt und das Bedienfeld feedback bleibt unsichtbar.

Überprüfen des Felds

Im Folgenden erfahren Sie, wie benutzerdefinierte Funktionen Felder und globale Objekte verwenden, um das Feld mithilfe eines Contact Us Formulars zu validieren.

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);

    }

In diesem Beispiel wird ein benutzerdefiniertes Überprüfungsmuster auf das Feld contact angewendet. Benutzende müssen eine Telefonnummer eingeben, die mit 10 gefolgt von 8 Ziffern beginnt. Wenn Benutzende eine Telefonnummer eingeben, die nicht mit 10 beginnt oder nicht genau 8 Ziffern enthält, wird beim Klicken auf die Schaltfläche eine Validierungsfehlermeldung angezeigt:

Der nächste Schritt besteht darin, eine Regel für die Schaltfläche Next zu erstellen, die das Feld contact beim Klicken auf die Schaltfläche validiert.

Beziehen Sie sich auf die folgende Abbildung, die zeigt, dass eine Fehlermeldung auf Feldebene angezeigt wird, wenn Benutzende eine Telefonnummer eingeben, die nicht mit 10 beginnt:

Wenn Benutzende eine gültige Telefonnummer eingeben und alle Felder im Bedienfeld personaldetails validiert worden sind, wird das Bedienfeld feedback auf dem Bildschirm angezeigt:

Zurücksetzen eines Bedienfelds

Im Folgenden erfahren Sie, wie benutzerdefinierte Funktionen Felder und globale Objekte verwenden, um das Feld mithilfe eines Contact Us Formulars zurückzusetzen.

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);

    }

In diesem Beispiel wird das Bedienfeld personaldetails beim Klicken auf die Schaltfläche Clear zurückgesetzt. Als Nächstes erstellen Sie eine Regel für die Schaltfläche Clear, die das Bedienfeld bei einem Klick auf die Schaltfläche zurücksetzt.

In der folgenden Abbildung sehen Sie, dass der Bereich personaldetails zurückgesetzt wird, wenn jemand auf die Schaltfläche clear klickt:

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

Im Folgenden erfahren Sie, wie benutzerdefinierte Funktionen Felder und globale Objekte verwenden, um eine benutzerdefinierte Nachricht auf Feldebene anzuzeigen und das Feld mithilfe eines Contact Us Formulars als ungültig zu markieren.

Mit der Funktion markFieldAsInvalid() können Sie ein Feld als ungültig definieren und eine benutzerdefinierte Fehlermeldung auf Feldebene festlegen. Der Wert fieldIdentifier kann fieldId, field qualifiedName oder field dataRef lauten. Der Wert des Objekts namens option kann {useId: true}, {useQualifiedName: true} oder {useDataRef: true} lauten.
Folgende Syntax wird verwendet, um ein Feld als ungültig zu markieren und eine benutzerdefinierte Nachricht festzulegen:

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 });
    }
}

In diesem Beispiel wird eine benutzerdefinierte Meldung auf Feldebene angezeigt, wenn Benutzende weniger als 15 Zeichen in das Textfeld „Kommentare“ eingeben.

Der nächste Schritt besteht darin, eine Regel für das Feld comments zu erstellen:

Sehen Sie sich das Beispiel unten an, in dem dargestellt wird, wie die Eingabe von negativem Feedback in das Feld comments die Anzeige einer benutzerdefinierten Nachricht auf Feldebene auslöst:

Wenn der/die Benutzende mehr als 15 Zeichen in das Textfeld „Kommentare“ eingibt, wird das Feld validiert und das Formular übermittelt:

Senden geänderter Daten an den Server

Im Folgenden erfahren Sie, wie benutzerdefinierte Funktionen mithilfe eines Contact Us Formulars Felder und globale Objekte verwenden, um bearbeitete Daten auf dem Server zu übermitteln.

Diese Codezeile
globals.functions.submitForm(globals.functions.exportData(), false); wird verwendet, um die Formulardaten nach der Bearbeitung zu senden.

Fügen Sie den folgenden Code in der benutzerdefinierten Funktion 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 jemand in diesem Beispiel das Textfeld comments leer lässt, wird beim Senden des Formulars an den Server NA gesendet.

Erstellen Sie jetzt eine Regel für die Submit-Schaltfläche, die Daten sendet:

In der Abbildung unten finden Sie das console window, das zeigt, dass der Wert als NA an den Server gesendet wird, wenn jemand das Textfeld comments leer lässt:

Sie können auch das Konsolenfenster überprüfen, um die an den Server gesendeten Daten anzuzeigen:

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

Im Folgenden erfahren Sie, wie benutzerdefinierte Funktionen mithilfe eines Contact Us Formulars Feld- und globale Objekte verwenden, um Übermittlungs-Handler zu überschreiben.

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 Formularübermittlungsmeldungen in einem modalen Feld 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);
}

Wenn in diesem Beispiel der Benutzer die customSubmitSuccessHandler und customSubmitErrorHandler benutzerdefinierten Funktionen verwendet, werden die Erfolgs- und Fehlermeldungen in einem modalen Fenster angezeigt. Die JavaScript-showModal(type, message) wird verwendet, um ein modales Dialogfeld dynamisch zu erstellen und auf einem Bildschirm anzuzeigen.

Erstellen Sie jetzt eine Regel für die erfolgreiche Formularübermittlung:

Anhand der folgenden Abbildung können Sie zeigen, dass bei erfolgreicher Übermittlung des Formulars die Erfolgsmeldung in einem modalen Fenster angezeigt wird:

Erstellen wir analog dazu eine Regel für fehlgeschlagene Formularübermittlungen:

Anhand der folgenden Abbildung können Sie zeigen, dass bei fehlgeschlagener Formularübermittlung die Fehlermeldung in einem modalen Fenster angezeigt wird:

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.

Falls der benutzerdefinierte Übermittlungs-Handler in bestehenden 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 für die letzte Instanz des wiederholbaren Bereichs. Zum Schreiben einer Regel für eine bestimmte Instanz des wiederholbaren Bereichs können wir eine benutzerdefinierte Funktion verwenden.

Erstellen wir ein anderes Formular, Booking Form Informationen über Reisende zu sammeln, die zu einem Ziel unterwegs sind. Ein Reisenden-Bedienfeld wird als wiederholbares Bedienfeld hinzugefügt, in dem der Benutzer mithilfe der Schaltfläche Add Traveler Details für 5 Reisende hinzufügen kann.

Fügen Sie die folgende Codezeile hinzu, wie im Abschnitt create-custom-function erläutert, um Aktionen in einer bestimmten Instanz des wiederholbaren Bereichs durchzuführen, die nicht der letzten 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});
}

In diesem Beispiel führt die benutzerdefinierte Funktion hidePanelInRepeatablePanel eine Aktion in einer bestimmten Instanz des wiederholbaren Bereichs durch. Im obigen Code stellt travelerinfo den wiederholbaren Bereich dar. Der repeatablePanel[1].traveler, {visible: false}-Code blendet den Bereich in der zweiten Instanz des wiederholbaren Bereichs aus.

Fügen wir eine Schaltfläche mit der Bezeichnung Hide hinzu und fügen wir eine Regel hinzu, um die zweite Instanz eines wiederholbaren Bereichs auszublenden.

Anhand des folgenden Videos wird gezeigt, dass beim Klicken auf die Hide der Bereich in der zweiten wiederholbaren Instanz ausgeblendet wird:

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

Im Folgenden erfahren Sie, wie benutzerdefinierte Funktionen Felder und globale Objekte verwenden, um Felder mithilfe eines Booking Form vorzubefüllen.

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']]));
}

Im oben genannten Code füllt die Funktion testImportData das Textfeld Booking Amount vorab aus, wenn das Formular geladen wird. Nehmen wir einmal an, dass das Buchungsformular die 10,000 des Mindestbuchungsbetrags erfordert.

Erstellen wir bei der Initialisierung des Formulars eine Regel, bei der der Wert im Booking Amount Textfeld beim Laden des Formulars mit einem angegebenen Wert vorausgefüllt wird:

Der folgende Screenshot zeigt, dass beim Laden des Formulars der Wert im Booking Amount Textfeld mit einem angegebenen Wert vorausgefüllt ist:

Fokus auf das spezifische Feld legen

Im Folgenden erfahren Sie, wie benutzerdefinierte Funktionen Felder und globale Objekte verwenden, um mithilfe eines Booking Form den Fokus auf ein bestimmtes Feld zu legen.

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);
    }

Fügen wir der Schaltfläche Submit eine Regel hinzu, um den Fokus auf das Textfeld Email ID zu legen, wenn darauf geklickt wird:

Der folgende Screenshot zeigt, dass beim Klicken auf die Schaltfläche Submit der Fokus auf das Feld Email ID gelegt wird:

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

Im Folgenden erfahren Sie, wie benutzerdefinierte Funktionen mithilfe von Feld- und globalen Objekten wiederholbare Bereiche mithilfe der dispatchEvent-Eigenschaft mithilfe eines Booking Form hinzufügen oder löschen.

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:

/**
 * 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 wir der Schaltfläche Add Traveler eine Regel hinzu, um den wiederholbaren Bereich hinzuzufügen, wenn auf ihn geklickt wird:

Die folgende GIF-Datei veranschaulicht, dass beim Klicken auf die Schaltfläche Add Traveler der Bereich mithilfe der dispatchEvent hinzugefügt wird:

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:

/**

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

Fügen wir der Schaltfläche Delete Traveler eine Regel hinzu, um den wiederholbaren Bereich beim Klicken zu löschen:

Die nachstehende GIF-Datei zeigt, dass beim Klicken auf die Schaltfläche Delete Traveler das Reisenden-Bedienfeld mithilfe der Eigenschaft dispatchEvent gelöscht wird:

Fehlerbehebung

Siehe auch