Anpassade funktioner i adaptiva Forms Core-komponenter

I den här artikeln beskrivs hur du skapar anpassade funktioner med den senaste adaptiva Form Core-komponenten som har de senaste funktionerna, som:

Se till att du ställer in den senaste formulärversionen i AEM Forms Core Component-miljön så att den använder de senaste funktionerna i Anpassade funktioner.

Introduktion

AEM Forms 6.5 innehåller JavaScript-funktioner som gör att du kan definiera komplexa affärsregler med regelredigeraren. AEM Forms har en mängd färdiga anpassade funktioner, men många användningsområden kräver att man definierar egna funktioner för flera formulär. Dessa anpassade funktioner förbättrar formulärens funktioner genom att möjliggöra hantering och bearbetning av inmatade data för att uppfylla specifika krav. Dessutom kan de dynamiskt ändra formulärbeteende baserat på de fördefinierade villkoren.

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

Fördelarna med att använda anpassade funktioner i adaptiva Forms Core-komponenter ä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 anpassat formulär. De anpassade funktionerna identifieras av JavaScript kommentarer i regelredigeraren.

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

JavaScript-anteckningar innehåller 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

Namn 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.

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:

Returtypen är inte skiftlägeskänslig.

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 considerations

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.

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 följande programvara är installerad på datorn:

Skapa en anpassad funktion create-custom-function

Steg för att skapa anpassade funktioner är:

Skapa ett klientbibliotek med hjälp av AEM Project Archetype create-client-library-archetype

Du kan lägga till anpassade funktioner genom att lägga till ett klientbibliotek i projektet som skapats med AEM Project Archetype.
Om du har ett befintligt projekt kan du lägga till anpassade funktioner direkt i ditt lokala projekt.

Skapa ett klientbibliotek när du har skapat ett Arketype-projekt eller använt ett befintligt projekt. Så här skapar du ett klientbibliotek:

Lägg till en klientbiblioteksmapp

Följ stegen nedan om du vill lägga till en ny biblioteksmapp för klienten i [AEM projektkatalog]:

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:

Skapa och driftsätt anpassade funktioner via CRXDE create-add-custom-function

Om du använder det senaste AEM Forms- och Forms-tillägget kan du skapa en anpassad funktion via CRXDE för att använda de senaste uppdateringarna av anpassade funktioner. Gör så här:

Du kan referera till följande anpassade funktionsmapp. Hämta och installera den här mappen på din AEM.

Nu kan du använda den anpassade funktionen i ditt adaptiva formulär genom att lägga till klientbiblioteket.

Lägga till klientbibliotek i ett adaptivt formulär add-client-library

När du har distribuerat klientbiblioteket till din AEM Forms-miljö kan du använda dess funktioner i ditt adaptiva formulär. Lägga till klientbiblioteket i ditt adaptiva formulär

Nu kan du skapa en regel som använder anpassade funktioner i regelredigeraren:

Nu ska vi förstå hur du konfigurerar och använder en anpassad funktion med tjänsten Invoke i regelredigeraren i AEM Forms 6.5

Använda anpassad funktion i ett anpassat formulär use-custom-functions

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:

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 när knappen klickar:

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 enskilda komponenter eller element 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ändningar.

Använd skiftläge: Visa en panel med regeln SetProperty

Lägg till följande kod i den anpassade funktionen enligt beskrivningen i avsnittet create-custom-function för att ange formulärfältet som Required.

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

I det här exemplet valideras panelen personaldetails när du klickar på knappen. Om inga fel upptäcks på panelen visas en annan panel, feedback-panelen, när du klickar på knappen.

Låt oss skapa en regel för knappen Next som validerar panelen personaldetails och gör panelen feedback synlig när användaren klickar på knappen Next.

Se bilden nedan för att visa var panelen personaldetails valideras när du klickar på knappen Next. Om alla fält i personaldetails valideras blir panelen feedback synlig.

Om det finns fel i fälten på panelen personaldetails visas de på fältnivå när du klickar på knappen Next och panelen feedback visas inte.

Använd skiftläge: Verifiera fältet.

Lägg till följande kod i den anpassade funktionen enligt anvisningarna i avsnittet create-custom-function för att validera fältet.

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

        globals.functions.validate(field);

    }

I det här exemplet används ett anpassat valideringsmönster för fältet contact. Användare måste ange ett telefonnummer som börjar med 10 följt av 8 siffror. Om användaren anger ett telefonnummer som inte börjar med 10 eller innehåller fler eller färre än 8 siffror visas ett valideringsfelmeddelande när knappen klickar:

Nästa steg är nu att skapa en regel för knappen Next som validerar fältet contact vid knappklicket.

Se bilden nedan för att visa att om användaren anger ett telefonnummer som inte börjar med 10 visas ett felmeddelande på fältnivå:

Om användaren anger ett giltigt telefonnummer och alla fält på panelen personaldetails valideras visas panelen feedback på skärmen:

Använd skiftläge: Återställ en panel

Lägg till följande kod i den anpassade funktionen enligt anvisningarna i avsnittet create-custom-function för att återställa panelen.

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

        globals.functions.reset(field);

    }

I det här exemplet återställs panelen personaldetails när du klickar på knappen Clear. Nästa steg är att skapa en regel för knappen Clear som återställer panelen när du klickar på knappen.

Se bilden nedan för att visa att panelen personaldetails återställs om användaren klickar på knappen clear:

Använd skiftläge: Om du vill visa anpassat meddelande på fältnivå och markera fältet som ogiltigt

Du kan använda funktionen markFieldAsInvalid() för att definiera ett fält som ogiltigt och ange ett anpassat felmeddelande på fältnivå. Värdet fieldIdentifier kan vara fieldId, field qualifiedName eller field dataRef. Värdet för objektet option kan vara {useId: true}, {useQualifiedName: true} eller {useDataRef: true}.
Syntaxerna som används för att markera fält som ogiltiga och ange anpassade meddelanden är:

Lägg till följande kod i den anpassade funktionen enligt beskrivningen i avsnittet create-custom-function för att aktivera anpassade meddelanden på fältnivå.

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

I det här exemplet visas ett anpassat meddelande på fältnivå om användaren skriver färre än 15 tecken i textrutan för kommentarer.

Nästa steg är att skapa en regel för fältet comments:

Se demonstrationen nedan för att visa att om du anger negativ feedback i fältet comments utlöses visningen av ett anpassat meddelande på fältnivå:

Om användaren skriver in mer än 15 tecken i textrutan för kommentarer valideras fältet och formuläret skickas:

Använd skiftläge: Skicka ändrade data till servern

Följande kodrad:
globals.functions.submitForm(globals.functions.exportData(), false); används för att skicka formulärdata efter manipulering.

Lägg till följande kod i den anpassade funktionen enligt beskrivningen i avsnittet create-custom-function för att skicka manipulerade data till servern:

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

I det här exemplet skickas NA till servern när formuläret skickas om användaren lämnar textrutan comments tom.

Skapa nu en regel för knappen Submit som skickar data:

Titta på bilden för console window nedan för att visa att om användaren lämnar textrutan comments tom så skickas värdet som NA på servern:

Du kan även kontrollera konsolfönstret för att visa data som skickats till servern:

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