Anpassade funktioner i Adaptive Forms (Core Components)

Introduktion

AEM Forms har stöd för anpassade funktioner, vilket gör att man kan definiera JavaScript-funktioner för att implementera komplexa affärsregler. Dessa anpassade funktioner gör att man kan förbättra blanketternas funktioner genom att underlätta hantering och bearbetning av inmatade data för att uppfylla specifika krav. De möjliggör också dynamisk ändring av formulärbeteende baserat på fördefinierade kriterier.

Användning av anpassade funktioner uses-of-custom-function

Fördelarna med att använda anpassade funktioner i Adaptive Forms är:

Anpassade funktioner är i huvudsak klientbibliotek som läggs till i JavaScript-filen. När du har skapat en anpassad funktion blir den tillgänglig i regelredigeraren så att användaren kan välja den i ett adaptivt formulär. De anpassade funktionerna identifieras av JavaScript kommentarer i regelredigeraren.

JavaScript-anteckningar som stöds för anpassade funktioner js-annotations

JavaScript-anteckningar används för att tillhandahålla metadata för JavaScript-kod. Det innehåller kommentarer som börjar med specifika symboler, till exempel /** och @. Anteckningarna innehåller viktig information om funktioner, variabler och andra element i koden. Adaptiv form stöder följande JavaScript-anteckningar för anpassade funktioner:

Namn

Namnet används för att identifiera den anpassade funktionen i regelredigeraren för ett adaptivt formulär. Följande syntaxer används för att namnge en anpassad funktion:

Parameter

Parametern är en lista med argument som används av anpassade funktioner. En funktion kan ha stöd för flera parametrar. Följande syntaxer används för att definiera en parameter i en anpassad funktion:

Parametertypen är inte skiftlägeskänslig och blanksteg tillåts inte i parameternamnet.

<Parameter Description> innehåller information om parameterns syfte. Det kan innehålla flera ord.

Valfria parametrar
Som standard är alla parametrar obligatoriska. Du kan definiera en parameter som valfri genom att antingen lägga till = efter parametertypen eller genom att omsluta parameternamnet i []. Parametrar som definieras som valfria i JavaScript-anteckningar visas som valfria i regelredigeraren.
Om du vill definiera en variabel som en valfri parameter kan du använda någon av följande syntaxer:

I ovanstående kodrad är Input1 en valfri parameter utan något standardvärde. Så här deklarerar du valfri parameter med standardvärdet:
@param {string=<value>} input1

input1 som en valfri parameter med standardvärdet value.

I ovanstående kodrad är Input1 en valfri parameter utan något standardvärde. Så här deklarerar du valfri parameter med standardvärdet:
@param {array} [input1=<value>]
input1 är en valfri parameter av arraytyp med standardvärdet value .
Kontrollera att parametertypen omsluts av klammerparenteser {} och att parameternamnet omges av hakparenteser.

Titta på följande kodfragment, där input2 definieras som en valfri parameter:

        /**
         * optional parameter function
         * @name OptionalParameterFunction
         * @param {string} input1
         * @param {string=} input2
         * @return {string}
        */
        function OptionalParameterFunction(input1, input2) {
        let result = "Result: ";
        result += input1;
        if (input2 !== null) {
            result += " " + input2;
        }
        return result;
        }

Följande bild visas med den anpassade funktionen OptionalParameterFunction i regelredigeraren:

Du kan spara regeln utan att ange ett värde för de obligatoriska parametrarna, men regeln körs inte och ett varningsmeddelande visas som:

När användaren lämnar den valfria parametern tom, skickas värdet "Odefinierad" till den anpassade funktionen för den valfria parametern.

Klicka här om du vill veta mer om hur du definierar valfria parametrar i JSDocs.

Returtyp

Returtypen anger vilken typ av värde som den anpassade funktionen returnerar efter körningen. Följande syntaxer används för att definiera en returtyp i en anpassad funktion:

Privat

Den anpassade funktionen som deklarerats som private visas inte i listan över anpassade funktioner i regelredigeraren för ett adaptivt formulär. Som standard är anpassade funktioner public. Syntaxen för att deklarera den anpassade funktionen som privat är @private.

Riktlinjer när du skapar anpassade funktioner

Om du vill visa en lista över anpassade funktioner i regelredigeraren kan du använda något av följande format:

Funktionssats med eller utan jsdoc-kommentarer

Du kan skapa en anpassad funktion med eller utan jsdoc-kommentarer.

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

Om användaren inte lägger till några JavaScript-anteckningar i den anpassade funktionen visas den i regelredigeraren med sitt funktionsnamn. Vi rekommenderar dock att du tar med JavaScript-anteckningar för förbättrad läsbarhet av anpassade funktioner.

Pilfunktion med obligatoriska JavaScript-anteckningar eller kommentarer

Du kan skapa en anpassad funktion med en pilfunktionssyntax:

    /**
    * 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;

Om användaren inte lägger till några JavaScript-anteckningar i den anpassade funktionen visas inte den anpassade funktionen i regelredigeraren för ett anpassat formulär.

Funktionsuttryck med obligatoriska JavaScript-anteckningar eller kommentarer

Om du vill visa anpassade funktioner i regelredigeraren för ett adaptivt formulär skapar du anpassade funktioner i följande 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
        }

Om användaren inte lägger till några JavaScript-anteckningar i den anpassade funktionen visas inte den anpassade funktionen i regelredigeraren för ett anpassat formulär.

Skapa en anpassad funktion create-custom-function

Skapa ett klientbibliotek för att anropa anpassade funktioner i regelredigeraren. Mer information finns i Använda klientbibliotek.

Steg för att skapa anpassade funktioner är:

Krav för att skapa en anpassad funktion

Innan du börjar lägga till en anpassad funktion i din adaptiva Forms måste du se till att du har följande:

Programvara:

Skapa ett klientbibliotek create-client-library

Du kan lägga till anpassade funktioner genom att lägga till ett klientbibliotek. Så här skapar du ett klientbibliotek:

Klona databasen

Klona din AEM Forms as a Cloud Service-databas:

Det här kommandot hämtar databasen och skapar en lokal mapp för den klonade databasen på din dator. I hela den här handboken ser vi den här mappen som [AEMaaCS-projektkatalog].

Lägg till en klientbiblioteksmapp

Så här lägger du till en ny biblioteksmapp för klienten i [AEMaaCS-projektkatalogen]:

Lägg till filer och mappar i mappen Klientbibliotek

Lägg till följande i den tillagda klientbiblioteksmappen:

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

Inkludera den nya mappen i filter.xml:

Distribuera den nyligen skapade biblioteksmappen för klienter till AEM

Distribuera AEM as a Cloud Service, [AEMaaCS-projektkatalogen], till din Cloud Service. Så här distribuerar du till din Cloud Service:

Om du inte redan har konfigurerat en pipeline kan du läsa guiden Konfigurera en pipeline för AEM Forms as a Cloud Service.

När pipeline har körts blir den anpassade funktion som lagts till i klientbiblioteket tillgänglig i regelredigeraren Adaptiv form.

Lägga till klientbibliotek i ett adaptivt formulär use-custom-function

När du har distribuerat klientbiblioteket till Forms CS-miljön kan du använda funktionerna i ditt adaptiva formulär. Lägga till klientbiblioteket i ditt adaptiva formulär

Du kan använda den anpassade funktionen i regelredigeraren för ett adaptivt formulär med JavaScript-anteckningar.

Använda en anpassad funktion i ett adaptivt formulär

I ett anpassat formulär kan du använda anpassade funktioner i regelredigeraren. Låt oss lägga till följande kod i JavaScript-filen (Function.js) för att beräkna ålder baserat på födelsedatum (ÅÅÅÅ-MM-DD). Skapa en anpassad funktion som calculateAge() som tar födelsedatumet som indata och returnerar ålder:

    /**
        * 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;
    }

I ovanstående exempel anropas den anpassade funktionen calculateAge när användaren anger födelsedatumet i formatet (ÅÅÅÅ-MM-DD) och sedan returnerar ålder.

Låt oss förhandsgranska formuläret för att se hur de anpassade funktionerna implementeras via regelredigeraren:

Ange alternativ för listrutor med anpassade funktioner

Regelredigeraren i Core Components stöder inte egenskapen Set Options of för att ange alternativ för listrutelistan vid körning. Du kan dock ange alternativ för listrutor med anpassade funktioner.

Titta på koden nedan för att se hur vi kan ange alternativ för listrutor med anpassade funktioner:

    /**
    * @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"];
    }

I ovanstående kod används setEnums för att ange egenskapen enum och setEnumNames används för att ange egenskapen enumNames för listrutan.

Låt oss skapa en regel för knappen Next, som anger värdet för alternativet för nedrullningsbar lista när användaren klickar på knappen Next:

Se bilden nedan för att visa var alternativen i listrutan ställs in när du klickar på knappen Visa:

Stöd för asynkrona funktioner i anpassade funktioner support-of-async-functions

Asynkrona anpassade funktioner visas inte i regelredigeringslistan. Det går dock att anropa asynkrona funktioner i anpassade funktioner som skapats med synkrona funktionsuttryck.

Titta på koden nedan för att se hur vi kan anropa asynkrona funktioner med anpassade funktioner:

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

I ovanstående exempel är funktionen asyncFunction en asynchronous function. Den utför en asynkron åtgärd genom att göra en GET-begäran till https://petstore.swagger.io/v2/store/inventory. Det väntar på svar med await, tolkar svarstexten som JSON med response.json() och returnerar sedan data. Funktionen callAsyncFunction är en synkron anpassad funktion som anropar funktionen asyncFunction och visar svarsdata i konsolen. Även om funktionen callAsyncFunction är synkron anropar den asynkrona funktionen asyncFunction och hanterar resultatet med programsatserna then och catch.

För att se hur den fungerar kan vi lägga till en knapp och skapa en regel för knappen som anropar den asynkrona funktionen när en knapp klickas.

Titta på bilden för konsolfönstret nedan för att visa att när användaren klickar på knappen Fetch anropas den anpassade funktionen callAsyncFunction som i sin tur anropar en asynkron funktion asyncFunction. Inspect i konsolfönstret för att visa svaret på knappen:

Låt oss dyka upp i funktionerna för anpassade funktioner.

Olika funktioner för anpassade funktioner

Du kan använda anpassade funktioner för att lägga till anpassade funktioner i formulär. Dessa funktioner har stöd för olika funktioner, som att arbeta med specifika fält, använda globala fält eller cachelagring. Tack vare denna flexibilitet kan ni anpassa formulären efter organisationens behov.

Fält- och globala omfångsobjekt i anpassade funktioner support-field-and-global-objects

Fältobjekt refererar till de enskilda komponenterna eller elementen i ett formulär, t.ex. textfält och kryssrutor. Globals-objektet innehåller skrivskyddade variabler som formulärinstans, målfältsinstans och metoder för att göra formulärändringar i anpassade funktioner.

Låt oss lära oss hur anpassade funktioner använder fält och globala objekt med hjälp av ett Contact Us-formulär med olika användningsfall.

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

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

        globals.functions.validate(field);

    }

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

        globals.functions.reset(field);

    }

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

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

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

/**
* @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});
}

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

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

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

/**

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

Cachelagringsstöd för anpassad funktion

Adaptiv Forms implementerar cachning för anpassade funktioner för att förbättra svarstiden samtidigt som den anpassade funktionslistan hämtas i regelredigeraren. Ett meddelande som Fetched following custom functions list from cache visas i filen error.log.

Om de anpassade funktionerna ändras blir cachningen ogiltig och den tolkas.

Felsökning troubleshooting

Överväganden

Se även see-also