Aangepaste functies in Adaptive Forms (Core Components)

Inleiding

AEM Forms ondersteunt aangepaste functies, zodat gebruikers JavaScript-functies kunnen definiëren voor het implementeren van complexe bedrijfsregels. Deze aangepaste functies vergroten de mogelijkheden van formulieren door het bewerken en verwerken van ingevoerde gegevens te vergemakkelijken, zodat aan bepaalde vereisten wordt voldaan. Ze maken het ook mogelijk het formuliergedrag dynamisch te wijzigen op basis van vooraf gedefinieerde criteria.

Gebruik van aangepaste functies uses-of-custom-function

De voordelen van het gebruik van aangepaste functies in Adaptive Forms zijn:

Aangepaste functies zijn in wezen clientbibliotheken die in het JavaScript-bestand worden toegevoegd. Zodra u een douanefunctie creeert, wordt het beschikbaar in de regelredacteur voor selectie door de gebruiker in een Aangepast Vorm. De douanefuncties worden geïdentificeerd door de aantekeningen van JavaScript in de regelredacteur.

Ondersteunde JavaScript-annotaties voor aangepaste functies js-annotations

JavaScript-annotaties worden gebruikt om metagegevens voor JavaScript-code te verschaffen. Het bevat opmerkingen die beginnen met specifieke symbolen, bijvoorbeeld /** en @. De annotaties bevatten belangrijke informatie over functies, variabelen en andere elementen in de code. Het adaptieve formulier ondersteunt de volgende JavaScript-annotaties voor aangepaste functies:

Naam

De naam wordt gebruikt om de douanefunctie in de regelredacteur van een Aangepast Vorm te identificeren. De volgende syntaxis wordt gebruikt om een douanefunctie te noemen:

Parameter

De parameter is een lijst met argumenten die door aangepaste functies worden gebruikt. Een functie kan meerdere parameters ondersteunen. De volgende syntaxis wordt gebruikt om een parameter in een douanefunctie te bepalen:

Het parametertype is niet hoofdlettergevoelig en spaties zijn niet toegestaan in de parameternaam.

<Parameter Description> bevat details over het doel van de parameter. Het kan meerdere woorden hebben.

Facultatieve Parameters
Standaard zijn alle parameters verplicht. U kunt een parameter als optioneel definiëren door = toe te voegen achter het parametertype of door de parameternaam in [] te plaatsen. Parameters die in JavaScript-annotaties als optioneel worden gedefinieerd, worden in de regeleditor als optioneel weergegeven.
Als u een variabele wilt definiëren als een optionele parameter, kunt u een van de volgende syntaxis gebruiken:

In de bovenstaande coderegel is Input1 een optionele parameter zonder standaardwaarde. Optionele parameter met standaardwaarde declareren:
@param {string=<value>} input1

input1 als een optionele parameter met de standaardwaarde ingesteld op value .

In de bovenstaande coderegel is Input1 een optionele parameter zonder standaardwaarde. Optionele parameter met standaardwaarde declareren:
@param {array} [input1=<value>]
input1 is een optionele parameter van het type array met de standaardwaarde value .
Zorg ervoor dat het parametertype wordt ingesloten door accolades {} en dat de parameternaam wordt ingesloten door vierkante haakjes.

Overweeg het volgende codefragment, waar input2 als facultatieve parameter wordt bepaald:

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

De volgende illustratie wordt weergegeven met behulp van de aangepaste functie OptionalParameterFunction in de regeleditor:

U kunt de regel opslaan zonder een waarde voor de vereiste parameters op te geven, maar de regel wordt niet uitgevoerd en er wordt een waarschuwingsbericht weergegeven als:

Wanneer de gebruiker de optionele parameter leeg laat, wordt de 'Undefined'-waarde doorgegeven aan de aangepaste functie voor de optionele parameter.

Meer over leren hoe te om facultatieve parameters in JSDocs te bepalen, klik hier.

Retourtype

Het retourneringstype geeft het type waarde op dat de aangepaste functie na de uitvoering retourneert. De volgende syntaxis wordt gebruikt om een terugkeertype in een douanefunctie te bepalen:

Persoonlijk

De aangepaste functie die als private is gedeclareerd, komt niet voor in de lijst met aangepaste functies in de regeleditor van een adaptief formulier. Aangepaste functies zijn standaard openbaar. De syntaxis voor het declareren van een aangepaste functie als private is @private .

Richtlijnen tijdens het maken van aangepaste functies

Om van de douanefuncties in de regelredacteur een lijst te maken, kunt u om het even welke volgende formaten gebruiken:

Functie-instructie met of zonder jsdoc-opmerkingen

U kunt een aangepaste functie maken met of zonder jsdoc-opmerkingen.

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

Als de gebruiker geen JavaScript-annotaties toevoegt aan de aangepaste functie, wordt deze door de functienaam in de regeleditor weergegeven. Het wordt echter aanbevolen JavaScript-annotaties op te nemen om de leesbaarheid van de aangepaste functies te verbeteren.

Pijlfunctie met verplichte JavaScript-annotaties of -opmerkingen

U kunt een aangepaste functie maken met een syntaxis voor een pijlfunctie:

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

Als de gebruiker geen JavaScript-annotaties toevoegt aan de aangepaste functie, wordt de aangepaste functie niet vermeld in de regeleditor van een adaptief formulier.

Functie-expressie met verplichte JavaScript-annotaties of -commentaar

Als u aangepaste functies wilt weergeven in de regeleditor van een adaptief formulier, maakt u aangepaste functies in de volgende indeling:

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

Als de gebruiker geen JavaScript-annotaties toevoegt aan de aangepaste functie, wordt de aangepaste functie niet vermeld in de regeleditor van een adaptief formulier.

Een aangepaste functie maken create-custom-function

Creeer een cliëntbibliotheek om douanefuncties in de regelredacteur te roepen. Voor meer informatie, zie Gebruikend cliënt-Kant Bibliotheken.

Stappen voor het maken van aangepaste functies zijn:

Vereisten om een aangepaste functie te maken

Voordat u een aangepaste functie toevoegt aan de Adaptive Forms, moet u het volgende doen:

Software:

Een clientbibliotheek maken create-client-library

U kunt aangepaste functies toevoegen door een clientbibliotheek toe te voegen. Voer de volgende stappen uit om een clientbibliotheek te maken:

Kloon de Bewaarplaats

Kloon uw as a Cloud Service Bewaarplaats van AEM Forms:

Met deze opdracht downloadt u de opslagplaats en maakt u een lokale map van de gekloonde opslagplaats op uw computer. Door deze gids, verwijzen wij naar deze omslag als [ AEMaaCS projectfolder ].

voeg een Omslag van de Bibliotheek van de Cliënt toe

Om nieuwe omslag van de cliëntbibliotheek aan de [ AEMaaCS projectfolder ] toe te voegen, volg deze stappen:

voegt dossiers en omslagen aan de omslag van de Bibliotheek van de Cliënt toe

Voeg het volgende toe aan de toegevoegde omslag van de cliëntbibliotheek:

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

omvat de nieuwe omslag in filter.xml:

stel de pas gecreëerde de bibliotheekomslag van de Cliënt aan uw AEM milieu op

Stel AEM as a Cloud Service, [ AEMaaCS projectfolder ], aan uw milieu van de Cloud Service op. Implementeren in uw Cloud Service-omgeving:

Als u niet reeds opstelling een pijpleiding hebt, verwijs naar de gids op hoe te opstelling een pijpleiding voor AEM Forms as a Cloud Service.

Zodra de pijpleiding met succes wordt uitgevoerd, wordt de douanefunctie die in de cliëntbibliotheek wordt toegevoegd beschikbaar in uw Aangepaste redacteur van de Regel van de Vorm.

Clientbibliotheek toevoegen aan een adaptief formulier use-custom-function

Zodra u de clientbibliotheek hebt geïmplementeerd in uw Forms CS-omgeving, gebruikt u de mogelijkheden van de clientbibliotheek in uw adaptieve formulier. De clientbibliotheek toevoegen aan uw adaptieve formulier

U kunt de douanefunctie in de regelredacteur van een Aangepaste Vormgebruiken gebruikend de annotaties van JavaScript.

Een aangepaste functie gebruiken in een adaptief formulier

In een AanpassingsVorm, kunt u douanefuncties binnen de regelredacteurgebruiken. Voeg de volgende code toe aan het JavaScript-bestand (Function.js ) om de leeftijd te berekenen op basis van de geboortedatum (JJJJ-MM-DD). Maak een aangepaste functie als calculateAge() die de geboortedatum als invoer neemt en de leeftijd retourneert:

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

In het bovenstaande voorbeeld wordt de aangepaste functie calculateAge aangeroepen en wordt de leeftijd geretourneerd wanneer de gebruiker de geboortedatum in de notatie invoert (JJJJ-MM-DD).

Bekijk een voorbeeld van het formulier om te zien hoe de aangepaste functies worden geïmplementeerd via de regeleditor:

Opties voor vervolgkeuzelijsten instellen met behulp van aangepaste functies

De Redacteur van de regel in de Componenten van de Kern steunt niet de Vastgestelde Opties van bezit om de opties van de dropdown lijst bij runtime te plaatsen. U kunt de opties voor de vervolgkeuzelijst echter instellen met behulp van aangepaste functies.

Bekijk de onderstaande code om te zien hoe u de opties voor de vervolgkeuzelijst kunt instellen met behulp van aangepaste functies:

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

In de bovenstaande code wordt setEnums gebruikt om de eigenschap enum in te stellen en wordt setEnumNames gebruikt om de eigenschap enumNames van het vervolgkeuzemenu in te stellen.

Maak een regel voor de knop Next , die de waarde van de keuzelijst instelt wanneer de gebruiker op de knop Next klikt:

Raadpleeg de onderstaande afbeelding om aan te tonen waar de opties van de vervolgkeuzelijst zijn ingesteld wanneer u op de knop Weergeven klikt:

Ondersteuning voor asynchrone functies in aangepaste functies support-of-async-functions

De asynchrone douanefuncties verschijnen niet in de lijst van de regelredacteur. Het is echter mogelijk om asynchrone functies aan te roepen binnen aangepaste functies die zijn gemaakt met synchrone functie-expressies.

Bekijk de code hieronder om te zien hoe we asynchrone functies kunnen aanroepen met behulp van aangepaste functies:

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

In het bovenstaande voorbeeld is de functie asyncFunction een asynchronous function . De toepassing voert een asynchrone bewerking uit door een GET -aanvraag in te dienen bij https://petstore.swagger.io/v2/store/inventory . Het wacht op de reactie met await, parseert de hoofdtekst van de reactie met JSON met de response.json() en retourneert de gegevens. De functie callAsyncFunction is een synchrone aangepaste functie die de functie asyncFunction aanroept en de reactiegegevens in de console weergeeft. Hoewel de functie callAsyncFunction synchroon is, roept deze de asynchrone functie asynchrone functie asyncFunction aan en verwerkt deze het resultaat met then - en catch -instructies.

Om zijn het werken te zien, laten wij een knoop toevoegen en een regel voor de knoop creëren die de asynchrone functie na een knoop klikt.

Raadpleeg de illustratie van het onderstaande consolevenster om aan te tonen dat wanneer de gebruiker op de knop Fetch klikt, de aangepaste functie callAsyncFunction wordt aangeroepen, die op zijn beurt een asynchrone functie asyncFunction aanroept. Inspect het consolevenster om de reactie op de knoop te bekijken klik:

Laten we eens kijken naar de functies van aangepaste functies.

Verschillende functies voor Aangepaste functies

U kunt aangepaste functies gebruiken om aangepaste functies toe te voegen aan formulieren. Deze functies ondersteunen diverse mogelijkheden, zoals het werken met specifieke velden, het gebruik van globale velden of caching. Dankzij deze flexibiliteit kunt u formulieren aanpassen aan de vereisten van uw organisatie.

Veld- en globale bereikobjecten in aangepaste functies support-field-and-global-objects

Veldobjecten verwijzen naar de afzonderlijke componenten of elementen in een formulier, zoals tekstvelden, selectievakjes. Het object Globals bevat alleen-lezen variabelen, zoals formulierinstantie, doelveldinstantie en methoden voor het uitvoeren van formulierwijzigingen binnen aangepaste functies.

Laten we leren hoe aangepaste functies veld- en globale objecten gebruiken met behulp van een Contact Us -formulier. Hierbij wordt gebruikgemaakt van verschillende gebruiksgevallen.

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

Ondersteuning voor caching van aangepaste functies

De adaptieve Forms voert caching voor douanefuncties uit om reactietijd te verbeteren terwijl het terugwinnen van de lijst van de douanefunctie in de regelredacteur. Er verschijnt een bericht als Fetched following custom functions list from cache in het error.log -bestand.

Als de aangepaste functies worden gewijzigd, wordt het in cache plaatsen ongeldig en wordt het geparseerd.

Problemen oplossen troubleshooting

Overwegingen

Zie ook see-also