Custom functions in Adaptive Forms Core Components

This article describes creating Custom Functions with the latest Adaptive Form Core Component, which have the latest features such as:

Ensure to set the latest form version on your AEM Forms Core Component environment to use the latest features in Custom Functions.

Introduction

AEM Forms 6.5 includes JavaScript functions that allow you to define complex business rules by using the rule editor. While AEM Forms offers a variety of out-of-the-box custom functions, many use cases require defining your own custom functions to use across multiple forms. These custom functions enhance the capabilities of forms by enabling the manipulation and processing of entered data to meet specific requirements. Additionally, they allow for dynamic alteration of form behavior based on the predefined criteria.

Uses of custom functions uses-of-custom-function

Advantages of using Custom Functions in Adaptive Forms Core Components 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 provides 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. 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.

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:

The return type is not case-sensitive.

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 considerations

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.

Prerequisites to create a custom function

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

Create a custom function create-custom-function

Steps to create custom functions are:

Create a client library using the AEM Project Archetype create-client-library-archetype

You can add custom functions by adding a client library to the project created using the AEM Project Archetype.
If you have an existing project you can directly add custom functions to your local project.

After you create an Archetype Project or use an existing project, create a client library. To create a client library perform the following steps:

Add a Client Library Folder

To add new client library folder to your [AEM project directory], follow the 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:

Create and deploy custom functions through CRXDE create-add-custom-function

If you are using the latest AEM Forms and Forms add-on, you can create a custom function through CRXDE to use the latest updates of custom functions. To do so, perform the following steps:

You can refer to the following custom function folder. Download and install this folder on your AEM instance.

Now, you can use the custom function in your Adaptive Form by adding the client library.

Add client library in an Adaptive Form add-client-library

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

Now, you can create a rule to use custom functions in the rule editor:

Now, let’s understand how to configure and use a custom function using the Rule Editor’s Invoke service in AEM Forms 6.5

Using Custom Function in an Adaptive Form use-custom-functions

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:

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 upon 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 refers 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 usecases.

Use Case: Show a panel using the SetProperty rule

Add the following code in the custom function as explained in the create-custom-functionsection, to set the form field as 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});
       }
    }

In this example, validation of the personaldetails panel occurs upon clicking the button. If no errors are detected in the panel, another panel, the feedback panel, becomes visible upon button click.

Let’s create a rule for the Next button, which validates the personaldetails panel and makes the feedback panel visible when the user clicks the Next button.

Refer to the illustration below to demonstrate where the personaldetails panel is validated upon clicking the Next button. In case all the fields within the personaldetails are validated, the feedback panel becomes visible.

If errors are present in the fields of the personaldetails panel, they are displayed at the field level upon clicking the Next button, and the feedback panel remains invisible.

Use Case: Validate the field.

Add the following code in the custom function as explained in the create-custom-functionsection, to validate the field.

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

        globals.functions.validate(field);

    }

In this example, a custom validation pattern is applied to the contact field. Users are required to input a phone number starting with 10 followed by 8 digits. If the user enters a phone number that does not start with 10 or contains more or less than 8 digits, a validation error message appears upon the button click:

Now, next step is to create a rule for the Next button that validates the contact field on the button click.

Refer to the illustration below to demonstrate that if the user enters a phone number that does not start with 10, an error message appears at the field level:

If the user enters a valid phone number and all fields in the personaldetails panel are validated, the feedback panel appears on the screen:

Use Case: Reset a panel

Add the following code in the custom function as explained in the create-custom-functionsection, to reset the panel.

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

        globals.functions.reset(field);

    }

In this example, the personaldetails panel resets upon clicking the Clear button. Next step is to create a rule for the Clear button that resets the panel on the button click.

See the illustration below to display that if the user clicks the clear button, the personaldetails panel resets:

Use Case: To display custom message at the field level and marking the field as invalid

You can use the markFieldAsInvalid() function to define a field as invalid and set custom error message at a field level. The fieldIdentifier value can be fieldId, or field qualifiedName, or field dataRef. The value of the object named option can be {useId: true}, {useQualifiedName: true}, or {useDataRef: true}.
The syntaxes used to mark field as invalid and set custom message are:

Add the following code in the custom function as explained in the create-custom-functionsection, to enable custom message at the field level.

    /**
    * 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 this example, if the user enters less than 15 characters in the comments textbox, a custom message appears at the field level.

Next step is to create a rule for the comments field:

See the demonstration below to display that entering negative feedback in the comments field triggers the display of a custom message at the field level:

If the user enters more than 15 characters in commments textbox, the field gets validated and form is submitted:

Use Case: Submit altered data to the server

The following line of code:
globals.functions.submitForm(globals.functions.exportData(), false); is used to submit the form data after manipulation.

Add the following code in the custom function as explained in the create-custom-functionsection, to submit the manipulated data at the server:

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

In this example, if the user leaves the comments textbox empty, the NA is submitted to the server at form submission.

Now create a rule for the Submit button which submits data:

Refer to the illustration of the console window below to demonstrate that if the user leaves the comments textbox empty, then the value as NA is submitted at the server:

You can also inspect the console window to view the data submitted to the server:

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