Custom functions in Adaptive Forms (Core Components)

Introduction

AEM Forms supports custom functions, allowing users to define JavaScript functions for implementing complex business rules. These custom functions extend the capabilities of forms by facilitating manipulation and processing of entered data to meet specified requirements. They also enable dynamic alteration of form behavior based on predefined criteria.

Uses of custom functions uses-of-custom-function

Advantages of using custom functions in Adaptive Forms are:

Custom functions are essentially client libraries that are added in the JavaScript file. Once you create a custom function, it becomes available in the rule editor for selection by the user in an Adaptive Form. The custom functions are identified by the JavaScript annotations in the rule editor.

Supported JavaScript annotations for custom function js-annotations

JavaScript annotations are used to provide metadata for JavaScript code. It includes comments that start with specific symbols, for example, /** and @. The annotations provide important information about functions, variables, and other elements in the code. Adaptive Form supports the following JavaScript annotations for custom functions:

Name

The name is used to identify the custom function in the rule editor of an Adaptive Form. The following syntaxes are used to name a custom function:

Parameter

The parameter is a list of arguments used by custom functions. A function can support multiple parameters. The following syntaxes are used to define a parameter in a custom function:

The parameter type is not case-sensitive and spaces are not allowed in the parameter name.

<Parameter Description> contains details about the purpose of the parameter. It can have multiple words.

Optional Parameters
By default, all parameters are mandatory. You can define a parameter as optional by either adding = after the parameter type or enclosing the parameter name in []. Parameters defined as optional in JavaScript annotations are displayed as optional in the rule editor.
To define a variable as an optional parameter, you can use any of the following syntaxes:

In the above line of code, Input1 is an optional parameter without any default value. To declare optional parameter with default value:
@param {string=<value>} input1

input1 as an optional parameter with the default value set to value.

In the above line of code, Input1 is an optional parameter without any default value. To declare optional parameter with default value:
@param {array} [input1=<value>]
input1 is an optional parameter of array type with the default value set to value.
Ensure that the parameter type is enclosed in curly brackets {} and the parameter name is enclosed in square brackets.

Consider the following code snippet, where input2 is defined as an optional 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;
        }

The following illustration displays using the OptionalParameterFunction custom function in the rule editor:

You can save the rule without specifying a value for the required parameters, but the rule is not executed and displays a warning message as:

When the user leaves the optional parameter empty, then the “Undefined” value is passed to the custom function for the optional parameter.

To learn more about how to define optional parameters in JSDocs, click here.

Return Type

The return type specifies the type of value that the custom function returns after execution. The following syntaxes are used to define a return type in a custom function:

Private

The custom function declared as private, does not appear in the list of custom functions in the rule editor of an Adaptive form. By default, custom functions are public. The syntax to declare custom function as private is @private.

Guidelines while creating custom functions

To list the custom functions in the rule editor, you can use any one of the following formats:

Function statement with or without jsdoc comments

You can create a custom function with or without jsdoc comments.

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

If the user does not add any JavaScript annotations to the custom function, it is listed in the rule editor by its function name. However, it is recommended to include JavaScript annotations for improved readability of the custom functions.

Arrow function with mandatory JavaScript annotations or comment

You can create a custom function with an arrow function syntax:

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

If the user does not add any JavaScript annotations to the custom function, the custom function is not listed in the rule editor of an Adaptive Form.

Function expression with mandatory JavaScript annotations or comment

To list custom functions in the rule editor of an Adaptive Form, create custom functions in the following 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
        }

If the user does not add any JavaScript annotations to the custom function, the custom function is not listed in the rule editor of an Adaptive Form.

Create a custom function create-custom-function

Create a client library to call custom functions in the rule editor. For more information, see Using Client-Side Libraries.

Steps to create custom functions are:

Prerequisites to create a custom function

Before you begin adding a custom function to your Adaptive Forms, ensure you have the following:

Software:

Create a client library create-client-library

You can add custom functions by adding a client library. To create a client library, perform the following steps:

Clone the Repository

Clone your AEM Forms as a Cloud Service Repository:

This command downloads the repository and creates a local folder of the cloned repository on your machine. Throughout this guide, we refer to this folder as the [AEMaaCS project directory].

Add a Client Library Folder

To add new client library folder to the [AEMaaCS project directory], follow these steps:

Add files and folders to the Client Library folder

Add the following to the added client library folder:

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

Include the new folder in filter.xml:

Deploy the newly created Client library folder to your AEM environment

Deploy the AEM as a Cloud Service, [AEMaaCS project directory], to your Cloud Service environment. To deploy to your Cloud Service environment:

If you haven’t already set up a pipeline, refer to the guide on how to set up a pipeline for AEM Forms as a Cloud Service.

Once the pipeline is executed successfully, the custom function added in the client library becomes available in your Adaptive Form rule editor.

Add client library to an Adaptive Form use-custom-function

Once you have deployed your client library to your Forms CS environment, use its capabilities in your Adaptive Form. To add the client library in your Adaptive Form

You can use the custom function in the rule editor of an Adaptive Form using the JavaScript annotations.

Using a custom function in an Adaptive Form

In an Adaptive Form, you can use custom functions within the rule editor. Let us add the following code to the JavaScript file (Function.js file) to calculate age based on the Date of Birth(YYYY-MM-DD). Create a custom function as calculateAge() which takes the date of birth as input and returns age:

    /**
        * 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 the above example, when the user enters the date of birth in the format (YYYY-MM-DD), the custom function calculateAge is invoked and returns the age.

Let’s preview the form to observe how the custom functions are implemented through the rule editor:

Set the dropdown list options using custom functions

Rule Editor in Core Components does not support the Set Options of property to set the dropdown list options at runtime. However, you can set the dropdown list options using custom functions.

Look at the code below to see how we can set the dropdown list options using custom functions:

    /**
    * @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 the above code, setEnums is used to set the enum property and setEnumNames is used to set the enumNames property of dropdown.

Let’s create a rule for the Next button, which sets the value of dropdown list option when the user clicks the Next button:

Refer to the illustration below to demonstrate where the options of the dropdown list are set upon clicking the Display button:

Support for asynchronous functions in custom functions support-of-async-functions

Asynchronous custom functions do not appear in the rule editor list. However, it is possible to invoke asynchronous functions within custom functions created using synchronous function expressions.

Look at the code below to see how we can invoke asynchronous functions using custom functions:

    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 the above example, the asyncFunction function is an asynchronous function. It performs an asynchronous operation by making a GET request to https://petstore.swagger.io/v2/store/inventory. It waits for the response using await, parses the response body as JSON using the response.json(), and then returns the data. The callAsyncFunction function is a synchronous custom function that invokes the asyncFunction function and displays the response data in the console. Although the callAsyncFunction function is synchronous, it calls the asynchronous asyncFunction function and handles its result with then and catch statements.

To see its working, let us add a button and create a rule for the button that invokes the asynchronous function upon a button click.

Refer to the illustration of the console window below to demonstrate that when the user clicks the Fetch button, the custom function callAsyncFunction is invoked, which in turn calls an asynchronous function asyncFunction. Inspect the console window to view the response to the button click:

Let’s dive into the features of custom functions.

Various features for Custom Functions

You can use custom functions to add personalized features to forms. These functions support various abilities such as working with specific fields, using global fields, or caching. This flexibility allows you to customize forms according to your organization’s requirements.

Field and Global scope objects in custom functions support-field-and-global-objects

Field objects refer to the individual components or elements within a form, such as text fields, checkboxes. The Globals object contains read-only variables such as form instance, target field instance and methods to do form modifications within custom functions.

Let’s learn how custom functions use field and global objects with the help of a Contact Us form using different use cases.

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

Caching support for custom function

Adaptive Forms implement caching for custom functions to enhance response time while retrieving the custom function list in the rule editor. A message as Fetched following custom functions list from cache appears in the error.log file.

In case the custom functions are modified, the caching becomes invalidated, and it is parsed.

Troubleshooting troubleshooting

Considerations

See Also see-also