自适应核心组件中的自定义函数Forms

本文介绍了如何使用最新的自适应表单核心组件创建自定义函数，这些组件具有最新的功能，例如：

请确保在AEM Forms核心组件环境中设置最新表单版本以使用自定义函数中的最新功能。

简介

AEM Forms 6.5包括JavaScript函数，这些函数允许您使用规则编辑器定义复杂的业务规则。 虽然AEM Forms提供了多种现成的自定义函数，但许多用例需要定义您自己的自定义函数才能在多个表单中使用。 这些自定义函数允许根据特定要求处理输入的数据，从而增强表单的功能。 此外，它们允许根据预定义标准动态更改表单行为。

自定义函数的使用 uses-of-custom-function

在自适应Forms核心组件中使用自定义函数的优点包括：

自定义函数本质上是添加到JavaScript文件中的客户端库。 创建自定义函数后，该函数即可在规则编辑器中供用户在自适应表单中选择。 自定义函数由规则编辑器中的JavaScript注释标识。

自定义函数支持的JavaScript批注 js-annotations

JavaScript注释为JavaScript代码​提供元数据。 它包含以特定符号（例如，/**和@）开头的注释。 注释提供了有关代码中的函数、变量和其他元素的重要信息。 自适应表单支持自定义函数的以下JavaScript注释：

名称

Name​用于标识自适应表单的规则编辑器中的自定义函数。 以下语法用于命名自定义函数：

参数

参数​是自定义函数使用的参数列表。 函数可以支持多个参数。 以下语法用于定义自定义函数中的参数：

参数类型为​不区分大小写，参数名称中不允许有空格。

<Parameter Description>包含有关参数用途的详细信息。 它可以有多个单词。

返回类型

返回类型指定自定义函数在执行后返回的值的类型。 以下语法用于在自定义函数中定义退货类型：

返回类型不区分大小写。

专用

声明为私有的自定义函数不会出现在自适应表单的规则编辑器的自定义函数列表中。 默认情况下，自定义函数是公用的。 将自定义函数声明为private的语法为@private。

创建自定义函数时的准则 considerations

要在规则编辑器中列出自定义函数，您可以使用以下任意格式：

包含或不包含jsdoc注释的函数语句

您可以创建包含或不包含jsdoc注释的自定义函数。

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

如果用户没有将任何JavaScript注释添加到自定义函数，则它按函数名称在规则编辑器中列出。 但是，建议包含JavaScript注释，以提高自定义函数的可读性。

带有强制JavaScript注释或注释的Arrow函数

您可以使用箭头函数语法创建自定义函数：

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

如果用户没有将任何JavaScript注释添加到自定义函数，则该自定义函数不会列在自适应表单的规则编辑器中。

带有必需JavaScript注释或注释的函数表达式

要在自适应表单的规则编辑器中列出自定义函数，请以下列格式创建自定义函数：

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

如果用户没有将任何JavaScript注释添加到自定义函数，则该自定义函数不会列在自适应表单的规则编辑器中。

创建自定义函数的先决条件

在开始将自定义函数添加到自适应Forms之前，请确保在计算机上安装了以下软件：

创建自定义功能 create-custom-function

创建自定义函数的步骤包括：

使用AEM项目原型创建客户端库 create-client-library-archetype

您可以向使用AEM项目原型🔗创建的项目中添加客户端库，从而添加自定义函数。
如果您现有项目，则可以直接将自定义函数添加到本地项目。

创建原型项目或使用现有项目后，请创建客户端库。 要创建客户端库，请执行以下步骤：

添加客户端库文件夹

要将新的客户端库文件夹添加到[AEM项目目录]，请执行以下步骤：

将文件和文件夹添加到客户端库文件夹

将以下内容添加到添加的客户端库文件夹：

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

在上例中，当用户以(YYYY-MM-DD)格式输入出生日期时，将调用自定义函数calculateAge并返回年龄。

让我们预览表单，观察自定义函数如何通过规则编辑器实现：

在自定义函数中支持异步函数 support-of-async-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);
    });
}

在上述示例中，asyncFunction函数是asynchronous function。 它通过向https://petstore.swagger.io/v2/store/inventory发出GET请求来执行异步操作。 它使用await等待响应，使用response.json()将响应正文解析为JSON，然后返回数据。 callAsyncFunction函数是一个同步自定义函数，它调用asyncFunction函数并在控制台中显示响应数据。 虽然callAsyncFunction函数是同步的，但它调用异步asyncFunction函数并使用then和catch语句处理其结果。

要查看其是否有效，让我们添加一个按钮，并为按钮创建一个规则，该规则会在单击按钮时调用异步函数。

请参考控制台窗口的插图以演示当用户单击Fetch按钮时，将调用自定义函数callAsyncFunction，进而调用异步函数asyncFunction。 检查控制台窗口以查看按钮单击时的响应：

让我们深入了解一下自定义函数的功能。

自定义函数的各种功能

您可以使用自定义函数向表单添加个性化功能。 这些函数支持各种功能，例如使用特定字段、使用全局字段或缓存。 这种灵活性允许您根据组织的要求自定义表单。

自定义函数中的字段和全局范围对象 support-field-and-global-objects

字段对象是指表单中的单个组件或元素，例如文本字段和复选框。 全局对象包含只读变量，例如表单实例、目标字段实例以及在自定义函数中修改表单的方法。

让我们了解自定义函数如何在Contact Us表单的帮助下使用字段和全局对象，该表单使用不同的用例。

用例：使用SetProperty规则显示面板

将以下代码添加到create-custom-function部分中说明的自定义函数中，以将表单字段设置为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});
       }
    }

在此示例中，personaldetails面板的验证是在单击按钮时进行的。 如果在面板中未检测到错误，则单击按钮后，另一个面板（feedback面板）将变为可见。

让我们为Next按钮创建一个规则，该规则将验证personaldetails面板，并在用户单击Next按钮时使feedback面板可见。

请参阅下图以演示单击Next按钮时验证personaldetails面板的位置。 如果personaldetails中的所有字段都已验证，feedback面板将变为可见。

如果personaldetails面板的字段中存在错误，则单击Next按钮时会在字段级别显示这些错误，并且feedback面板将保持不可见。

用例：验证字段。

按照create-custom-function部分中的说明，在自定义函数中添加以下代码以验证字段。

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

        globals.functions.validate(field);

    }

在此示例中，自定义验证模式应用于contact字段。 用户需要输入以10开头后接8位数的电话号码。 如果用户输入的电话号码不以10开头或包含多或少8位数，则单击该按钮时将显示验证错误消息：

现在，下一步是为Next按钮创建一个规则，以验证单击按钮时的contact字段。

请参阅下图以演示，如果用户输入的电话号码不是以10开头，则在字段级别将显示错误消息：

如果用户输入有效的电话号码并且验证personaldetails面板中的所有字段，屏幕上会显示feedback面板：

用例：重置面板

按照create-custom-function部分中的说明，在自定义函数中添加以下代码以重置面板。

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

        globals.functions.reset(field);

    }

在此示例中，personaldetails面板在单击Clear按钮时重置。 下一步是为Clear按钮创建一个规则，该规则将在单击按钮时重置面板。

请参阅下图以显示，如果用户单击clear按钮，personaldetails面板将重置：

用例：在字段级别显示自定义消息并将字段标记为无效

您可以使用markFieldAsInvalid()函数将字段定义为无效，并在字段级别设置自定义错误消息。 fieldIdentifier值可以是fieldId、field qualifiedName或field dataRef。 名为option的对象的值可以是{useId: true}、{useQualifiedName: true}或{useDataRef: true}。
用于将字段标记为无效并设置自定义消息的语法包括：

按照create-custom-function部分中的说明，在自定义函数中添加以下代码，以在字段级别启用自定义消息。

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

在此示例中，如果用户在“注释”文本框中输入的字符数少于15个，则会在字段级别显示自定义消息。

下一步是为comments字段创建规则：

请参阅下面的演示，说明在comments字段中输入负反馈会触发字段级别的自定义消息显示：

如果用户在“评论”文本框中输入的字符超过15个，则验证该字段并提交表单：

用例：将更改的数据提交到服务器

以下代码行：
globals.functions.submitForm(globals.functions.exportData(), false);用于在操作后提交表单数据。

按照create-custom-function部分中的说明，在自定义函数中添加以下代码，以在服务器上提交操作数据：

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

在此示例中，如果用户将comments文本框留空，则NA在提交表单时提交给服务器。

现在，为提交数据的Submit按钮创建规则：

请参阅以下console window的图示，以演示如果用户将comments文本框留空，则在服务器上提交值为NA：

您还可以检查控制台窗口以查看提交到服务器的数据：

对自定义函数的缓存支持

自适应Forms在规则编辑器中检索自定义函数列表时，为自定义函数实施缓存以增强响应时间。 error.log文件中显示一条消息，名称为Fetched following custom functions list from cache。

支持缓存的

如果修改了自定义函数，缓存将失效，并且会进行解析。

疑难解答 troubleshooting

注意事项