Introduction to Custom Functions for Adaptive Forms based on Core Components

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 enable dynamic alteration of form behavior based on predefined criteria. Custom functions also enable developers to enforce complex validation logic, perform dynamic calculations, and control the display or behavior of form elements based on user interactions or 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.

Next Step

To create and use a custom function in your Adaptive Form, refer to the Create a Custom Function for an Adaptive Form Based on Core Components article.

See Also