Benutzerdefinierte Funktionen in Kernkomponenten für adaptive Formulare

In diesem Artikel wird das Erstellen benutzerdefinierter Funktionen mit der neuesten Kernkomponente für adaptive Formulare beschrieben, die die aktuellsten Funktionen aufweist, z. B.:

Stellen Sie sicher, dass die neueste Formularversion in Ihrer AEM Forms-Kernkomponentenumgebung festgelegt ist, damit Sie die neuesten Features in benutzerdefinierten Funktionen verwenden können.

Einführung

AEM Forms 6.5 umfasst JavaScript-Funktionen, mit denen Sie mithilfe des Regeleditors komplexe Geschäftsregeln definieren können. AEM Forms bietet verschiedene vordefinierte Funktionen, für die jedoch in vielen Fällen benutzerdefinierte Funktionen definiert werden müssen, damit sie in mehreren Formularen verwendet werden können. Diese benutzerdefinierten Funktionen erweitern die Möglichkeiten von Formularen, indem sie die Be- und Verarbeitung von eingegebenen Daten ermöglichen, wenn spezifische Anforderungen erfüllt werden sollen. Darüber hinaus ermöglichen sie dynamische Veränderungen des Formularverhaltens basierend auf den vordefinierten Kriterien.

Vorteile benutzerdefinierter Funktionen uses-of-custom-function

Vorteile der Verwendung benutzerdefinierter Funktionen in Kernkomponenten für adaptive Formulare sind:

Benutzerdefinierte Funktionen sind im Wesentlichen Client-Bibliotheken, die in der JavaScript-Datei hinzugefügt werden. Nachdem Sie eine benutzerdefinierte Funktion erstellt haben, steht sie im Regeleditor zur Auswahl durch Benutzende in einem adaptiven Formular zur Verfügung. Die benutzerdefinierten Funktionen sind im Regeleditor anhand der JavaScript-Anmerkungen zu erkennen.

Unterstützte JavaScript-Anmerkungen für benutzerdefinierte Funktionen js-annotations

JavaScript-Anmerkungen bieten Metadaten für JavaScript-Code. Dies schließt Kommentare ein, die mit bestimmten Symbolen beginnen, z. B. /** und @. Die Anmerkungen enthalten wichtige Informationen zu Funktionen, Variablen und anderen Elementen im Code. Adaptive Formulare unterstützen die folgenden JavaScript-Anmerkungen für benutzerdefinierte Funktionen:

Name

Der Name wird verwendet, um die benutzerdefinierte Funktion im Regeleditor eines adaptiven Formulars zu erkennen. Die folgenden Syntaxen werden verwendet, um eine benutzerdefinierte Funktion zu benennen:

Parameter

Der Parameter ist eine Liste von Argumenten, die von benutzerdefinierten Funktionen verwendet werden. Eine Funktion kann mehrere Parameter unterstützen. Die folgenden Syntaxen werden verwendet, um einen Parameter in einer benutzerdefinierten Funktion zu definieren:

Beim Parametertyp wird nicht zwischen Groß- und Kleinschreibung unterschieden und Leerzeichen sind im Parameternamen nicht zulässig.

<Parameter Description> enthält Details zum Zweck des Parameters. Dies kann aus mehreren Wörtern bestehen.

Rückgabetyp

Der Rückgabetyp gibt den Typ des Werts an, den die benutzerdefinierte Funktion nach der Ausführung zurückgibt. Die folgenden Syntaxen werden verwendet, um einen Rückgabetyp in einer benutzerdefinierten Funktion zu definieren:

Beim Rückgabetyp wird nicht zwischen Groß- und Kleinschreibung unterschieden.

Privat

Die als privat deklarierte benutzerdefinierte Funktion wird nicht in der Liste der benutzerdefinierten Funktionen im Regeleditor eines adaptiven Formulars angezeigt. Standardmäßig sind benutzerdefinierte Funktionen öffentlich. Die Syntax zum Deklarieren der benutzerdefinierten Funktion als privat lautet @private.

Richtlinien beim Erstellen benutzerdefinierter Funktionen considerations

Um die benutzerdefinierten Funktionen im Regeleditor aufzulisten, können Sie eines der folgenden Formate verwenden:

Funktionsanweisung mit oder ohne jsdoc-Kommentare

Sie können eine benutzerdefinierte Funktion mit oder ohne jsdoc-Kommentare erstellen.

    function functionName(parameters)
        {
            // code to be executed
        }

Wenn Benutzende zu einer benutzerdefinierten Funktion keine JavaScript-Anmerkungen hinzufügen, wird sie im Regeleditor anhand ihres Funktionsnamens aufgelistet. Es wird jedoch empfohlen, JavaScript-Anmerkungen einzubeziehen, um die Lesbarkeit der benutzerdefinierten Funktionen zu verbessern.

Pfeilfunktion mit obligatorischen JavaScript-Anmerkungen oder -Kommentaren

Sie können eine benutzerdefinierte Funktion mit einer Pfeilfunktionssyntax erstellen:

    /**
    * test function
    * @name testFunction
    * @param {string} a parameter description
    * @param {string=} b parameter description
    * @return {string}
    */
    testFunction = (a, b) => {
    return a + b;
    };
    /** */
    testFunction1=(a) => (return a)
    /** */
    testFunction2 = a => a + 100;

Wenn Benutzende der benutzerdefinierten Funktion keine JavaScript-Anmerkungen hinzufügen, wird die benutzerdefinierte Funktion nicht im Regeleditor eines adaptiven Formulars aufgeführt.

Funktionsausdruck mit obligatorischen JavaScript-Anmerkungen oder -Kommentaren

Um benutzerdefinierte Funktionen im Regeleditor eines adaptiven Formulars aufzulisten, erstellen Sie benutzerdefinierte Funktionen im folgenden Format:

    /**
    * test function
    * @name testFunction
    * @param {string} input1 parameter description
    * @param {string=} input2 parameter description
    * @return {string}
    */
    testFunction = function(input1,input2)
        {
            // code to be executed
        }

Wenn Benutzende der benutzerdefinierten Funktion keine JavaScript-Anmerkungen hinzufügen, wird die benutzerdefinierte Funktion nicht im Regeleditor eines adaptiven Formulars aufgeführt.

Voraussetzungen zum Erstellen einer benutzerdefinierten Funktion.

Bevor Sie mit dem Hinzufügen einer benutzerdefinierten Funktion zu Ihrem adaptiven Formular beginnen, stellen Sie sicher, dass Sie die folgende Software auf Ihrem Computer installiert haben:

Erstellen einer benutzerdefinierten Funktion create-custom-function

Die Schritte zum Erstellen benutzerdefinierter Funktionen sind die Folgenden:

Erstellen einer Client-Bibliothek mit dem AEM-Projektarchetyp create-client-library-archetype

Sie können benutzerdefinierte Funktionen hinzufügen, indem Sie unter Verwendung des AEM-Projektarchetyps eine Client-Bibliothek zu dem erstellten Projekt hinzufügen.
Wenn Sie über ein vorhandenes Projekt verfügen , können Sie Ihrem lokalen Projekt direkt benutzerdefinierte Funktionen hinzufügen.

Nachdem Sie ein Archetypprojekt erstellt oder ein vorhandenes Projekt verwendet haben, erstellen Sie eine Client-Bibliothek. Um eine Client-Bibliothek zu erstellen, führen Sie die folgenden Schritte aus:

Hinzufügen eines Client-Bibliotheksordners

Gehen Sie wie folgt vor, um einen neuen Client-Bibliotheksordner zu Ihrem [AEM-Projektverzeichnis] hinzuzufügen:

Hinzufügen von Dateien und Ordnern zum Client-Bibliotheksordner

Fügen Sie dem hinzugefügten Client-Bibliotheksordner Folgendes hinzu:

Location is: [AEMaaCS project directory]/ui.apps/src/main/content/jcr_root/apps/experience-league/customclientlibs/

Schließen Sie den neuen Ordner in filter.xml ein:

Erstellen und Bereitstellen benutzerdefinierter Funktionen über CRXDE create-add-custom-function

Wenn Sie die aktuellsten Versionen von AEM Forms- und des Forms-Add-ons verwenden, können Sie über CRXDE eine benutzerdefinierte Funktion erstellen, um die neuesten Aktualisierungen von benutzerdefinierten Funktionen zu verwenden. Führen Sie dazu die folgenden Schritte aus:

Sie können auf den folgenden Ordner Benutzerdefinierte Funktion verweisen. Laden Sie diesen Ordner herunter und installieren Sie ihn in Ihrer AEM-Instanz.

Jetzt können Sie die benutzerdefinierte Funktion in Ihrem adaptiven Formular verwenden, indem Sie die Client-Bibliothek hinzufügen.

Hinzufügen einer Client-Bibliothek in einem adaptiven Formular add-client-library

Nachdem Sie Ihre Client-Bibliothek in Ihrer AEM Forms-Umgebung bereitgestellt haben, verwenden Sie die zugehörigen Funktionen in Ihrem adaptiven Formular. Hinzufügen der Client-Bibliothek zu einem adaptiven Formular

Jetzt können Sie eine Regel erstellen, um benutzerdefinierte Funktionen im Regeleditor zu verwenden:

Im Folgenden erfahren Sie, wie Sie einen benutzerdefinierten Fehler-Handler mit dem Aufrufdienst des Regeleditors in AEM Forms 6.5 konfigurieren und verwenden.

Verwenden von benutzerdefinierten Funktionen in einem adaptiven Formular. use-custom-functions

In einem adaptiven Formular können Sie benutzerdefinierte Funktionen im Regeleditor verwenden.
Fügen Sie der JavaScript-Datei (Function.js) den folgenden Code hinzu, um das Alter basierend auf dem Geburtsdatum (JJJJ-MM-TT) zu berechnen. Erstellen Sie eine benutzerdefinierte Funktion als calculateAge(), die das Geburtsdatum als Eingabe annimmt und das Alter zurückgibt:

    /**
        * Calculates Age
        * @name calculateAge
        * @param {object} field
        * @return {string}
    */

    function calculateAge(field) {
    var dob = new Date(field);
    var now = new Date();

    var age = now.getFullYear() - dob.getFullYear();
    var monthDiff = now.getMonth() - dob.getMonth();

    if (monthDiff < 0 || (monthDiff === 0 && now.getDate() < dob.getDate())) {
    age--;
    }

    return age;
    }

Wenn Benutzende im obigen Beispiel das Geburtsdatum im Format JJJJ-MM-TT eingeben, wird die benutzerdefinierte Funktion calculateAge aufgerufen und das Alter zurückgegeben.

Sehen wir uns das Formular in der Vorschau an, um zu sehen, wie die benutzerdefinierten Funktionen über den Regeleditor implementiert werden:

Unterstützung für asynchrone Funktionen in benutzerdefinierten Funktionen support-of-async-functions

Asynchrone benutzerdefinierte Funktionen werden nicht in der Liste des Regeleditors angezeigt. Es ist jedoch möglich, asynchrone Funktionen innerhalb benutzerdefinierter Funktionen aufzurufen, die mit synchronen Funktionsausdrücken erstellt wurden.

Sehen Sie sich den folgenden Code an, um zu erfahren, wie Sie asynchrone Funktionen mit benutzerdefinierten Funktionen aufrufen können:

    async function asyncFunction() {
    const response = await fetch('https://petstore.swagger.io/v2/store/inventory');
    const data = await response.json();
    return data;
    }

    /**
    * callAsyncFunction
    * @name callAsyncFunction callAsyncFunction
    */
    function callAsyncFunction() {
    asyncFunction()
        .then(responseData => {
        console.log('Response data:', responseData);
        })
        .catch(error => {
         console.error('Error:', error);
    });
}

Im obigen Beispiel ist die Funktion „asyncFunction“ eine asynchronous function. Sie führt einen asynchronen Vorgang durch, indem eine GET-Anfrage an https://petstore.swagger.io/v2/store/inventory gesendet wird. Sie wartet mit await auf die Antwort, analysiert den Antworttext mithilfe der response.json() als JSON und gibt dann die Daten zurück. Die Funktion callAsyncFunction ist eine synchrone benutzerdefinierte Funktion, die die Funktion asyncFunction aufruft und die Antwortdaten in der Konsole anzeigt. Obwohl die Funktion callAsyncFunction synchron ist, ruft sie die asynchrone Funktion „asyncFunction“ auf und verarbeitet ihr Ergebnis mit den Anweisungen then und catch.

Um ihre Funktionsweise zu sehen, fügen wir eine Schaltfläche hinzu und erstellen eine Regel für die Schaltfläche, die die asynchrone Funktion bei einem Klick auf eine Schaltfläche aufruft.

In der Abbildung unten finden Sie das Konsolenfenster, um zu zeigen, dass beim Klicken auf die Schaltfläche Fetch die benutzerdefinierte Funktion callAsyncFunction aufgerufen wird, die wiederum die asynchrone Funktion asyncFunction aufruft. Inspizieren Sie das Konsolenfenster, um die Antwort anzusehen, wenn Sie auf die Schaltfläche klicken:

Im Folgenden werden die Merkmale von benutzerdefinierten Funktionen vorgestellt.

Verschiedene Merkmale von benutzerdefinierten Funktionen

Sie können benutzerdefinierte Funktionen verwenden, um personalisierte Merkmale zu Funktionen hinzuzufügen. Diese Funktionen unterstützen verschiedene Fähigkeiten, wie z. B. das Arbeiten mit bestimmten Feldern, das Verwenden globaler Felder oder das Zwischenspeichern. Diese Flexibilität ermöglicht es Ihnen, Formulare entsprechend den Anforderungen Ihres Unternehmens anzupassen.

Objekte mit dem Gültigkeitsbereich „Feld“ und „Global“ in benutzerdefinierten Funktionen support-field-and-global-objects

Feldobjekte beziehen sich auf die einzelnen Komponenten oder Elemente in einem Formular, z. B. Textfelder und Kontrollkästchen. Das Globals-Objekt enthält schreibgeschützte Variablen wie Formularinstanz, Zielfeldinstanz und Methoden zum Durchführen von Formularänderungen in benutzerdefinierten Funktionen.

Im Folgenden erfahren wir, wie benutzerdefinierte Funktionen für verschiedene Anwendungsfälle Feld- und global-Objekte mithilfe eines Contact Us-Formulars verwenden.

Anwendungsfall: Anzeigen eines Bedienfelds mithilfe der SetProperty-Regel

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.

Anwendungsfall: Das Feld 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:

Anwendungsfall: Zurücksetzen eines Bedienfelds

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:

Anwendungsfall: Eine benutzerdefinierte Nachricht auf Feldebene anzeigen und das Feld als ungültig 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.
Die Syntaxen, die zum Markieren des Felds als ungültig und zum Festlegen der benutzerdefinierten Nachricht verwendet werden, sind:

Um eine benutzerdefinierte Nachricht auf Feldebene zu aktivieren, fügen Sie den folgenden Code in der benutzerdefinierten Funktion hinzu, wie im Abschnitt create-custom-function beschrieben.

    /**
    * 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 jemand mehr als 15 Zeichen in das Textfeld „Kommentare“ eingibt, wird das Feld validiert und das Formular wird gesendet:

Anwendungsfall: Übermittlung geänderter Daten an den Server

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 nun eine Regel für die Schaltfläche Submit, mit der Daten gesendet werden:

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:

Caching-Unterstützung für benutzerdefinierte Funktionen

Adaptive Formulare nutzen Caching für benutzerdefinierte Funktionen, um die Antwortzeit beim Abrufen der Liste der benutzerdefinierten Funktionen im Regeleditor zu verbessern. In der Datei error.log wird eine Meldung Fetched following custom functions list from cache angezeigt.

Wenn die benutzerdefinierten Funktionen geändert werden, wird das Caching invalidiert, und es wird analysiert.

Fehlerbehebung troubleshooting

Überlegungen