本文包含Override form submission success and error handlers作为预发行版功能。 预发行功能只能通过我们的 预发行渠道.

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

版本
文章链接
AEM 6.5
单击此处
AEM as a Cloud Service
本文

简介

AEM Forms支持自定义函数,允许用户定义用于实现复杂业务规则的JavaScript函数。 这些自定义函数通过简化输入数据的操作和处理来扩展表单的功能,以满足特定要求。 它们还支持根据预定义标准动态更改表单行为。

NOTE
确保 核心组件 设置为最新版本以使用最新功能。

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

在自适应Forms中使用自定义函数的优点包括:

  • 数据处理:自定义函数有助于处理输入到表单字段中的数据。
  • 数据验证:通过自定义函数,可对表单输入执行自定义检查并提供指定的错误消息。
  • 动态行为:自定义函数允许您根据特定条件控制表单的动态行为。 例如,您可以显示/隐藏字段、修改字段值或动态调整表单逻辑。
  • 集成:您可以使用自定义函数与外部API或服务集成。 它有助于从外部源获取数据,将数据发送到外部Rest端点,或根据外部事件执行自定义操作。

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

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

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

名称

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

  • @name [functionName] <Function Name>
  • @function [functionName] <Function Name>
  • @func [functionName] <Function Name>
    functionName 是函数的名称。 不允许使用空格。
    <Function Name> 是自适应表单的规则编辑器中函数的显示名称。
    如果函数名称与函数本身的名称相同,则可以忽略 [functionName] 语法中的。

参数

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

  • @param {type} name <Parameter Description>

  • @argument {type} name <Parameter Description>

  • @arg {type} name <Parameter Description>.
    {type} 表示参数类型。 允许的参数类型包括:

    • string:表示单个字符串值。
    • 数字:表示单个数值。
    • 布尔值:表示单个布尔值(true或false)。
    • 字符串[]:表示字符串值的数组。
    • 数字[]:表示数字值的数组。
    • 布尔型[]:表示布尔值的数组。
    • 日期:表示单个日期值。
    • 日期[]:表示日期值的数组。
    • array:表示包含各种类型值的泛型数组。
    • 对象:表示传递到自定义函数的表单对象,而不是直接传递其值。
    • 范围:表示全局对象,其中包含只读变量,如表单实例、目标字段实例以及在自定义函数中执行表单修改的方法。 此变量声明为JavaScript注释中的最后一个参数,在自适应表单的规则编辑器中不可见。 scope参数可访问表单或组件的对象,以触发表单处理所需的规则或事件。 有关Globals对象及其使用方式的更多信息, 单击此处.

参数类型不区分大小写,并且参数名称中不允许有空格。

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

可选参数
默认情况下,所有参数都是必需的。 通过添加以下任一项,可将参数定义为可选参数 = 在参数类型后面或将参数名称括在 []. 在JavaScript注释中定义为可选的参数在规则编辑器中显示为可选。
要将变量定义为可选参数,可以使用以下任意语法:

  • @param {type=} Input1

在上一行代码中, Input1 是一个可选参数,没有任何默认值。 使用默认值声明可选参数:
@param {string=<value>} input1

input1 作为可选参数,默认值设置为 value.

  • @param {type} [Input1]

在上一行代码中, Input1 是一个可选参数,没有任何默认值。 使用默认值声明可选参数:
@param {array} [input1=<value>]
input1 是数组类型的可选参数,其默认值设置为 value.
确保将参数类型括在大括号中 {} 并且参数名称用方括号括起来。

请考虑以下代码段,其中input2被定义为可选参数:

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

下图使用 OptionalParameterFunction 规则编辑器中的自定义函数:

可选或必需的参数

您可以保存规则而不为所需的参数指定值,但不会执行规则并显示警告消息:

规则不完整警告

当用户将可选参数留空时,“未定义”值将传递到可选参数的自定义函数。

要详细了解如何在JSDocs中定义可选参数, 单击此处.

返回类型

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

  • @return {type}

  • @returns {type}
    {type} 表示函数的返回类型。 允许的返回类型包括:

    • string:表示单个字符串值。
    • 数字:表示单个数值。
    • 布尔值:表示单个布尔值(true或false)。
    • 字符串[]:表示字符串值的数组。
    • 数字[]:表示数字值的数组。
    • 布尔型[]:表示布尔值的数组。
    • 日期:表示单个日期值。
    • 日期[]:表示日期值的数组。
    • array:表示包含各种类型值的泛型数组。
    • 对象:表示表单对象,而不是直接表示其值。

    返回类型不区分大小写。

专用

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

创建自定义函数时的准则

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

包含或不包含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注释添加到自定义函数,则该自定义函数不会列在自适应表单的规则编辑器中。

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

创建客户端库以在规则编辑器中调用自定义函数。 有关更多信息,请参阅 使用客户端库.

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

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

在开始将自定义函数添加到自适应Forms之前,请确保您满足以下条件:

软件:

  • 纯文本编辑器(IDE):虽然任何纯文本编辑器都可以工作,但诸如Microsoft Visual Studio Code之类的集成开发环境(IDE)可提供高级功能以便更轻松地编辑。

  • Git: 此版本控制系统是管理代码更改所必需的。 如果未安装,请从https://git-scm.com下载。

创建客户端库 create-client-library

您可以通过添加客户端库来添加自定义函数。 要创建客户端库,请执行以下步骤:

克隆存储库

克隆您的 AEM Formsas a Cloud Service存储库

  1. 打开命令行或终端窗口。

  2. 导航到要在计算机上存储存储库的所需位置。

  3. 运行以下命令以克隆存储库:

    git clone [Git Repository URL]

此命令下载存储库并在计算机上创建克隆存储库的本地文件夹。 在本指南中,我们将此文件夹称为 [AEMaaCS项目目录].

添加客户端库文件夹

要将新的客户端库文件夹添加到 [AEMaaCS项目目录],请按照以下步骤操作:

  1. 打开 [AEMaaCS项目目录] 在编辑器中。

    自定义函数文件夹结构

  2. 定位 ui.apps.

  3. 添加新文件夹。 例如,添加一个名为的文件夹 experience-league.

  4. 导航到 /experience-league/ 文件夹并添加 ClientLibraryFolder. 例如,创建一个名为的客户端库文件夹 customclientlibs.

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

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

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

  • .content.xml文件
  • js.txt文件
  • js文件夹

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

  1. .content.xml 添加以下代码行:

    code language-javascript
    <?xml version="1.0" encoding="UTF-8"?>
    <jcr:root xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
    jcr:primaryType="cq:ClientLibraryFolder"
    categories="[customfunctionscategory]"/>
    
    note note
    NOTE
    您可以选择任意名称 client library foldercategories 属性。
  2. js.txt 添加以下代码行:

    code language-javascript
          #base=js
        function.js
    
  3. js 文件夹,将javascript文件添加为 function.js 具体包括以下自定义函数:

    code language-javascript
     /**
         * 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;
     }
    
  4. 保存文件。

自定义函数文件夹结构

在filter.xml中包含新文件夹

  1. 导航至 /ui.apps/src/main/content/META-INF/vault/filter.xml 文件中的文件 [AEMaaCS项目目录].

  2. 打开文件,并在末尾添加以下行:

    <filter root="/apps/experience-league" />

  3. 保存文件。

自定义函数筛选器xml

将新创建的客户端库文件夹部署到AEM环境

部署AEMas a Cloud Service, [AEMaaCS项目目录],添加到您的Cloud Service环境。 要部署到Cloud Service环境,请执行以下操作:

  1. 提交更改

    1. 使用以下命令在存储库中添加、提交和推送更改:
    code language-javascript
        git add .
        git commit -a -m "Adding custom functions"
        git push
    
  2. 部署更新的代码:

    1. 通过现有的全栈管道触发代码部署。 这会自动构建和部署更新的代码。

如果尚未设置管道,请参阅上的指南 如何设置AEM Formsas a Cloud Service的管道.

成功执行管道后,客户端库中添加的自定义函数即可在中使用 自适应表单规则编辑器.

将客户端库添加到自适应表单 use-custom-function

将客户端库部署到Forms CS环境后,请在自适应表单中使用其功能。 在自适应表单中添加客户端库

  1. 在编辑模式下打开表单。 要在编辑模式下打开表单,请选择一个表单,然后选择 编辑.

  2. 打开内容浏览器,然后选择自适应表单的​ 指南容器 ​组件。

  3. 单击指南容器属性 指南属性 图标。这将打开“自适应表单容器”对话框。

  4. 打开 基本 选项卡并选择的名称 客户端库类别 (在本例中,选择 customfunctionscategory)。

    添加自定义函数客户端库

    note note
    NOTE
    通过在 客户端库类别 字段。
  5. 单击​ 完成

您可以使用中的自定义函数 自适应表单的规则编辑器 使用 JavaScript注释.

在自适应表单中使用自定义函数

在自适应表单中,您可以使用 规则编辑器中的自定义函数. 让我们将以下代码添加到JavaScript文件(Function.js 文件),以根据出生日期计算年龄(YYYY-MM-DD)。 创建自定义函数为 calculateAge() ,以出生日期作为输入并返回年龄:

    /**
        * 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 将调用并返回年龄。

在规则编辑器中重新计算自定义函数

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

在规则编辑器表单预览中再次计算自定义函数

NOTE
您可以参考以下内容 自定义函数 文件夹。 使用下载此文件夹并将其安装到您的AEM实例中 包管理器.

使用自定义函数设置下拉列表选项

核心组件中的规则编辑器不支持 设置选项 属性,用于在运行时设置下拉列表选项。 但是,您可以使用自定义函数设置下拉列表选项。

查看以下代码,了解如何使用自定义函数设置下拉列表选项:

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

在上述代码中, setEnums 用于设置 enum 属性和 setEnumNames 用于设置 enumNames 下拉列表的属性。

让我们为 Next 按钮,设置用户单击 Next 按钮:

下拉列表选项

请参阅下图以演示单击“显示”按钮时下拉列表的选项设置位置:

规则编辑器中的下拉选项

在自定义函数中支持异步函数 support-of-async-functions

异步自定义函数未出现在规则编辑器列表中。 但是,可以在使用同步函数表达式创建的自定义函数中调用异步函数。

同步和异步自定义函数

NOTE
在自定义函数中调用异步函数的优势在于,异步函数允许并行执行多个任务,并且自定义函数中使用了每个函数的结果。

查看以下代码,了解如何使用自定义函数调用异步函数:


    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. 它执行异步操作,方法是 GET 请求给 https://petstore.swagger.io/v2/store/inventory. 它使用以下方式等待响应 await,使用将响应正文解析为JSON response.json(),然后返回数据。 此 callAsyncFunction 函数是一个同步自定义函数,可调用 asyncFunction 函数并在控制台中显示响应数据。 尽管 callAsyncFunction 函数是同步的,它调用异步asyncFunction函数并使用处理其结果 thencatch 语句。

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

创建异步函数的规则

请参阅下面的控制台窗口插图,以演示当用户单击 Fetch 按钮,自定义函数 callAsyncFunction 将调用,从而调用异步函数 asyncFunction. 在控制台窗口中Inspect以查看对单击按钮的响应:

控制台窗口

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

自定义函数的各种功能

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

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

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

NOTE
param {scope} globals 必须是最后一个参数,且不会显示在自适应表单的规则编辑器中。

让我们了解自定义函数如何在 Contact Us 使用不同用例的表单。

联系我们表单

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

在自定义函数中添加以下代码,如 create-custom-function 部分,将表单字段设置为 Required.

code language-javascript

    /**
    * 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});
       }
    }
note note
NOTE
  • 您可以使用中的可用属性配置字段属性 [form-path]/jcr:content/guideContainer.model.json.
  • 使用对表单进行的修改 setProperty globals对象的方法本质上是异步的,在执行自定义函数期间不会反映出来。

在此示例中,验证 personaldetails 单击按钮时会出现面板。 如果在面板、其他面板、 feedback 面板中,单击按钮后会变为可见。

让我们为 Next 按钮,用于验证 personaldetails 面板并将 feedback 用户单击 Next 按钮。

设置属性

请参阅下图以演示 personaldetails 单击 Next 按钮。 如果 personaldetails 经过验证, feedback 面板将变为可见。

设置属性表单预览

如果的字段中出现错误 personaldetails 面板中,单击 Next 按钮,以及 feedback 面板将保持不可见。

设置属性表单预览

用例:验证字段。

在自定义函数中添加以下代码,如 create-custom-function 部分,以验证字段。

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

        globals.functions.validate(field);

    }
note note
NOTE
如果未在中传递参数 validate() 函数中,它验证表单。

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

电子邮件地址验证模式

现在,下一步是为创建规则 Next 验证 contact 字段单击。

验证模式

请参阅下图以演示,如果用户输入的电话号码开头不是 10,则字段级别会显示一条错误消息:

电子邮件地址验证模式

如果用户输入有效的电话号码和 personaldetails 面板已经过验证, feedback 屏幕上会显示以下面板:

电子邮件地址验证模式

用例:重置面板

在自定义函数中添加以下代码,如 create-custom-function 部分,以重置面板。

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

        globals.functions.reset(field);

    }
note note
NOTE
如果未在中传递参数 reset() 函数中,它验证表单。

在此示例中, personaldetails 单击 Clear 按钮。 下一步是为创建规则 Clear 按钮上用于重置面板的按钮单击。

清除按钮

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

重置表单

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

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

  • globals.functions.markFieldAsInvalid(field.$id,"[custom message]",{useId: true});
  • globals.functions.markFieldAsInvalid(field.$qualifiedName, "[custom message]", {useQualifiedName: true});
  • globals.functions.markFieldAsInvalid(field.$dataRef, "[custom message]", {useDataRef: true});

在自定义函数中添加以下代码,如 create-custom-function 部分,以在字段级别启用自定义消息。

code language-javascript
    /**
    * 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); 用于在操作后提交表单数据。

  • 第一个参数是要提交的数据。
  • 第二个参数表示在提交之前是否验证表单。 它是 optional 并设置为 true 默认情况下。
  • 第三个理由是 contentType ,此选项也是可选的,默认值为 multipart/form-data. 其他值可以是 application/jsonapplication/x-www-form-urlencoded.

在自定义函数中添加以下代码,如 create-custom-function 部分,在服务器上提交操作数据:

code language-javascript
    /**
    * 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 在服务器上提交:

在控制台窗口中提交数据

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

控制台窗口中的Inspect数据

用例:覆盖表单提交成功和错误处理程序

添加以下代码行,如 create-custom-function 部分,自定义表单提交的提交或失败消息,并在模式框中显示表单提交消息:

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

在此示例中,当用户使用 customSubmitSuccessHandlercustomSubmitErrorHandler 自定义函数中,成功和失败消息会以模式显示。 JavaScript函数 showModal(type, message) 用于在屏幕上动态创建和显示模式对话框。

现在,为成功的表单提交创建规则:

表单提交成功

请参阅下图以演示成功提交表单后,成功消息将以模式显示:

表单提交成功消息

同样,让我们为失败的表单提交创建规则:

表单提交失败

请参阅下图以演示,当表单提交失败时,将以模式模式显示错误消息:

表单提交失败消息

要以默认方式显示表单提交成功和失败,请 Default submit Form Success HandlerDefault submit Form Error Handler 函数开箱即用。

如果自定义提交处理程序无法按预期在现有AEM项目或表单中执行,请参阅 故障排除 部分。

用例:在可重复面板的特定实例中执行操作

使用可重复面板上的可视规则编辑器创建的规则将应用于可重复面板的最后一个实例。 要为可重复面板的特定实例编写规则,我们可以使用自定义函数。

让我们创建另一个表单,以收集有关前往目的地的旅行者的信息。 添加了一个旅客面板作为可重复面板,用户可以在其中使用 Add Traveler 按钮。

旅行者信息

添加以下代码行,如 create-custom-function 部分,要在可重复面板的特定实例中执行操作(最后一个实例除外),请执行以下操作:

code language-javascript
/**
* @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});
}

在此示例中, hidePanelInRepeatablePanel 自定义函数在可重复面板的特定实例中执行操作。 在上述代码中, travelerinfo 表示可重复面板。 此 repeatablePanel[1].traveler, {visible: false} 代码隐藏可重复面板的第二个实例中的面板。

让我们添加一个标记为的按钮 Hide 并添加规则以隐藏可重复面板的第二个实例。

隐藏面板规则

请参阅以下视频,以演示 Hide 单击,第二个可重复实例中的面板将隐藏:

embed

https://video.tv.adobe.com/v/3429554?quality=12&learn=on

用例:加载表单时使用值预填字段

添加以下代码行,如 create-custom-function 部分,以在初始化表单时在字段中加载预填充值:

code language-javascript
/**
 * Tests import data
 * @name testImportData
 * @param {scope} globals
 */
function testImportData(globals)
{
    globals.functions.importData(Object.fromEntries([['amount','10000']]));
}

在上述法典中, testImportData 函数预填充 Booking Amount 加载表单时显示的文本框字段。 假设预订表单要求最低预订金额为 10,000.

让我们在表单初始化时创建一个规则,其中 Booking Amount 加载表单时,文本框字段预填充指定的值:

导入数据规则

请参阅下面的屏幕截图,其中演示了加载表单时, Booking Amount 文本框已预填充指定的值:

导入数据规则表单

用例:将焦点设置为特定字段

添加以下代码行,如 create-custom-function 部分,以在 Submit 已单击按钮。:

code language-javascript
/**
 * @name testSetFocus
 * @param {object} emailField
 * @param {scope} globals
 */
    function testSetFocus(field, globals)
    {
        globals.functions.setFocus(field);
    }

让我们将规则添加到 Submit 按钮来设置焦点 Email ID 文本框字段:

设置焦点规则

请参阅下面的屏幕截图,其中演示了 Submit 单击按钮时,焦点将位于 Email ID 字段:

设置焦点规则

note note
NOTE
您可以使用可选的 $focusOption 参数(如果要集中显示相对于的下一个或上一个字段) email 字段。
用例:使用添加或删除可重复面板 dispatchEvent 属性

添加以下代码行,如 create-custom-function 部分,以在 Add Traveler 使用单击按钮 dispatchEvent 属性:

code language-javascript
/**
 * Tests add instance with dispatchEvent
 * @name testAddInstance
 * @param {scope} globals
 */
function testAddInstance(globals)
{
    var repeatablePanel = globals.form.traveler;
    globals.functions.dispatchEvent(repeatablePanel,'addInstance');
}

让我们将规则添加到 Add Traveler 按钮,在单击可重复面板时添加该面板:

添加面板规则

请参阅下面的gif,其中演示了当 Add Traveler 单击按钮后,会使用添加面板 dispatchEvent 属性:

添加面板

同样,添加以下代码行,如 create-custom-function 部分,以在 Delete Traveler 使用单击按钮 dispatchEvent 属性:

code language-javascript
/**

 * @name testRemoveInstance
 * @param {scope} globals
 */
function testRemoveInstance(globals)
{
    var repeatablePanel = globals.form.traveler;
    globals.functions.dispatchEvent(repeatablePanel, 'removeInstance');
}

让我们将规则添加到 Delete Traveler 按钮在单击可重复面板时将其删除:

删除面板规则

请参阅下面的gif,其中演示了当 Delete Traveler 单击“ ”按钮,将使用删除“旅客”面板 dispatchEvent 属性:

删除面板

对自定义函数的缓存支持

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

支持缓存的自定义函数

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

疑难解答 troubleshooting

  • 如果自定义提交处理程序无法按预期在现有AEM项目或表单中执行,请执行以下步骤:

    • 确保 核心组件版本已更新至3.0.18及更高版本. 但是,对于现有AEM项目和表单,还需要执行其他步骤:

    • 对于AEM项目,用户应替换 submitForm('custom:submitSuccess', 'custom:submitError') 替换为 submitForm() 和通过Cloud Manager管道部署项目。

    • 对于现有表单,如果自定义提交处理程序无法正常运行,用户需要打开并保存 submitForm 规则 提交 按钮。 此操作替换中的现有规则 submitForm('custom:submitSuccess', 'custom:submitError') 替换为 submitForm() 在表格中。

  • 如果包含自定义函数代码的JavaScript文件出错,则自定义函数将不会在自适应表单的规则编辑器中列出。 要检查自定义函数列表,您可以导航到 error.log 文件查找错误。 如果出现错误,自定义函数列表显示为空:

    错误日志文件

    如果没有错误,则会获取自定义函数并显示在 error.log 文件。 消息为 Fetched following custom functions list 显示在 error.log 文件:

    使用正确的自定义函数创建错误日志文件

注意事项

  • parameter typereturn type 不支持 None.

  • 自定义函数列表中不支持的函数包括:

    • 生成器函数
    • 异步/等待函数
    • 方法定义
    • 类方法
    • 默认参数
    • Rest参数

另请参阅 see-also

recommendation-more-help
fbcff2a9-b6fe-4574-b04a-21e75df764ab