基于核心组件的自适应表单的错误处理程序 error-handlers-in-adaptive-form

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

AEM Forms 为表单提交提供现成的成功和错误处理程序。它还提供用于自定义错误处理函数的功能。例如,可在后端为特定的错误代码调用自定义工作流或通知客户服务已停止。处理程序是根据服务器响应执行的客户端函数。在使用 API 调用外部服务时,数据会传输到服务器以进行验证,这会向客户端返回响应,其中包含有关提交的成功或错误事件的信息。该信息作为参数传递给相关处理程序以执行该函数。错误处理程序可帮助管理和显示遇到的错误或验证问题。

错误处理程序工作流,用于了解如何在表单中添加自定义错误处理程序

自适应表单根据预设验证标准验证您在字段中提供的输入,并检查为调用外部服务而配置的 REST 端点所返回的各种错误。您可以根据用于自适应表单的数据源设置验证标准。例如,如果您使用 RESTful Web 服务作为数据源,则可以在 Swagger 定义文件中定义验证标准。

如果输入值满足验证标准,则将值提交到数据源,否则自适应表单将使用错误处理程序显示错误消息。与此方法类似,自适应表单与自定义错误处理程序集成以执行数据验证。如果输入值未满足验证标准,错误消息将在自适应表单的字段级别显示。当服务器返回的验证错误消息采用标准消息格式时,会发生此情况。

错误处理程序的用途 uses-of-error-handler

错误处理程序具有多种用途。下面列出了错误处理程序函数的一些用途:

  • 执行验证:错误处理首先根据预定义的规则或标准验证用户输入。当用户填写自适应表单时,错误处理程序会验证输入,确保其满足所需的格式、长度或任何其他约束。

  • 提供实时反馈:当检测到任何错误时,错误处理程序会立即向用户显示反馈,例如相应表单字段下方的内联错误消息。此反馈可帮助用户识别和纠正错误,而无需提交表单并等待响应。

  • 显示错误信息:当自适应表单提交遇到任何验证错误时,错误处理程序会显示相应的错误消息。错误消息应清楚、简洁,并突出显示需要注意的特定字段。

  • 突出显示错误的字段:为了吸引用户对特定的错误字段的关注,错误处理程序会突出显示或在视觉上区分相应的字段。通过更改背景颜色、添加图标或边框或任何其他有助于用户快速找到和纠正错误的视觉提示来执行此操作。

失败/错误响应格式 failure-response-format

如果服务器验证错误消息采用以下标准格式,则自适应表单会在字段级别显示错误。
以下代码说明了现有的失败响应结构:

   {
    errorCausedBy : "SERVER_SIDE_VALIDATION/SERVICE_INVOCATION_FAILURE"
    errors : [
        {
             errorMessage / errorMessages : <validationMsg> / [<validationMsg>, <validationMsg>]
        }
    ]
    originCode : <target error Code>
    originMessage : <unstructured error message returned by service>
    }

其中:

  • errorCausedBy 描述失败的原因。
  • errors 提及未达到验证标准的字段的表达式以及验证错误消息。
  • originCode 字段由 AEM 添加,包含由外部服务返回的 http 状态代码。
  • originMessage 字段由 AEM 添加,包含由外部服务返回的原始错误数据。

随着 AEM Forms 版本的功能改进和后续更新,现有的失败响应结构变成了基于 RFC7807 的新格式,可向后兼容现有的失败响应结构:

    {
        "type": "SERVER_SIDE_VALIDATION/FORM_SUBMISSION/SERVICE_INVOCATION/FAILURE/VALIDATION_ERROR", (required)
        "title": "Server side validation failed/Third party service invocation failed", (optional)
        "detail": "", (optional)
        "instance": "", (optional)
        "validationErrors" : [ (required)
            {
                "fieldName":"<qualified fieldname of the field whose data sent is invalid>",
                "dataRef":<JSONPath (or XPath) of the data element which is invalid>
                "details": ["Error Message(s) for the field"] (required)

            }
        ],
        "originCode": <Origin http status code>, (optional - in case of SERVER_SIDE_VALIDATION)
        "originMessage" : "<unstructured error message returned by service>" (optional - in case of SERVER_SIDE_VALIDATION)
    }
NOTE
  • 确保错误响应结构包括 fieldNamedataRef
  • 确保 ContentType 标头是 application/problem+json

其中:

  • type (required) 指定失败类型。它可以是下列任一值:

    • SERVER_SIDE_VALIDATION 指示因服务器端验证导致的失败。
    • FORM_SUBMISSION 指示表单提交期间发生的失败。
    • SERVICE_INVOCATION 指示第三方服务调用期间发生的失败。
    • FAILURE 指示常见失败。
    • VALIDATION_ERROR 指示因验证错误导致的失败。
  • title (optional) 提供失败的标题或简要描述。

  • detail (optional) 提供有关失败的其他详细信息(如有必要)。

  • instance (optional) 表示与失败相关的实例或标识符,并可帮助跟踪或识别具体发生的失败。

  • validationErrors (required) 包含有关验证错误的信息。它包含以下字段:

    • fieldname 提及未通过验证标准的字段的限定字段名。
    • dataRef 表示未通过验证的字段的 JSON 路径或 XPath。
    • details 包含带错误字段的验证错误消息。
  • originCode (optional) 字段由 AEM 添加,包含由外部服务返回的 http 状态代码。

  • originMessage (optional) 字段由 AEM 添加,包含由外部服务返回的原始错误数据。

错误响应格式示例 sample-error-response-format

用于显示错误响应的一些选项是:

基于自适应表单 fieldName 属性
  • Header: content-type:application/problem+json

  • Response:

    code language-javascript
            {
                "type": "VALIDATION_ERROR",
                "validationErrors": [
                {
                "fieldName": "$form.PetId",
                "dataRef": "",
                "details": [
                "Invalid ID supplied. Provided value is not correct!"
            ]
            }
            ]}
    
基于自适应表单绑定引用属性
  • Header: content-type:application/problem+json

  • Response:

    code language-javascript
        {
            "type": "VALIDATION_ERROR",
            "validationErrors": [
            {
                "fieldName": "",
                "dataRef": "$.Pet.id",
                "details": [
                "Invalid ID supplied. Provided value is not correct!"
                ]
                }
        ]}
    

您可以在表单组件的​ 属性 ​窗口中查看 dataRef 的值。

使用规则编辑器的调用服务添加错误处理程序的要求 before-you-start-to-add-error-handler

在使用规则编辑器的调用服务添加错误处理程序之前:

使用规则编辑器添加错误处理程序 add-error-handler-using-rule-editor

通过使用规则编辑器的调用服务操作,可以根据用于自适应表单的数据源来定义验证标准。如果您使用 RESTful Web 服务作为数据源,则可以在 Swagger 定义文件中定义验证标准。通过在自适应表单中使用错误处理函数和规则编辑器,可以有效地管理和自定义错误处理。可以使用规则编辑器定义条件,并配置在触发规则时要执行的所需操作。自适应表单根据预设验证标准验证您在字段中输入的信息。如果输入值未达到验证标准,则将在自适应表单的字段级别显示错误消息。

NOTE
  • 要将错误处理程序与规则编辑器的调用服务操作结合使用,请使用表单数据模型(FDM)配置自适应Forms。
  • 如果错误响应位于标准架构中,则提供默认错误处理程序以在字段上显示错误消息。还可以从自定义错误处理程序函数调用默认错误处理程序。

利用规则编辑器,您可以:

添加默认错误处理程序函数 add-default-errror-handler

如果错误响应处于标准架构或服务器端验证失败,则支持默认错误处理程序以在字段上显示错误消息。
为了了解如何通过规则编辑器的调用服务操作来使用默认错误处理程序,以具有​ 宠物 ID 和​ 宠物名称 ​这两个字段的简单自适应表单为例,并在​ 宠物 ID 字段上使用默认错误处理程序,以检查为调用外部服务而配置的 REST 端点所返回的各种错误,例如 200 - OK404 - Not Found400 - Bad Request。要使用规则编辑器的调用服务操作添加默认错误处理程序,请执行以下步骤:

  1. 在创作模式下打开自适应表单,选择表单组件,然后选择 规则编辑器 以打开规则编辑器。
  2. 选择​ 创建
  3. 在规则的 When 部分中创建条件。例如,在更改[宠物名称 ID 字段] ​时,会从​ 选择状态 ​下拉列表中更改选择。
  4. Then 部分中,从​ 选择操作 ​下拉列表中选择​ 调用服务
  5. 从​ 输入 ​部分中选择​ 发布服务 ​及其相应的数据绑定。例如,要验证​ 宠物 ID,选择​ 发布服务 ​作为 GET /pet/{petId},并在​ 输入 ​部分中选择​ 宠物 ID
  6. 从​ 输出 ​部分中选择数据绑定。在​ 输出 ​部分中选择​ 宠物名称
  7. 从​ 错误处理程序 ​部分中选择​ 默认错误处理程序
  8. 单击​ 完成

为表单中的字段验证检查添加默认错误处理程序

根据此规则,将使用 REST 端点所调用的外部服务针对您为​ 宠物 ID 输入的值来检查验证​ 宠物名称。如果未达到基于数据源的验证标准,错误消息将在字段级别显示。

在表单中添加默认错误处理程序来处理错误响应时显示默认错误消息

添加自定义错误处理程序函数 add-custom-errror-handler

您可以添加自定义错误处理程序函数来执行一些操作,例如:

  • 处理使用非标准或标准错误响应的错误响应。请务必注意,这些非标准错误响应不符合错误响应的标准架构
  • 将分析事件发送到任何分析平台。例如,Adobe Analytics。
  • 显示带错误消息的模式对话框。

除了提及的操作之外,自定义错误处理程序还可用于执行满足特定用户要求的自定义函数。

自定义错误处理程序是一个函数(客户端库),旨在响应由外部服务返回的错误并向最终用户提供自定义响应。任何带注释 @errorHandler 的客户端库均被视为自定义错误处理程序函数。该注释有助于识别 .js 文件中指定的错误处理程序函数。
为了了解如何通过规则编辑器的调用服务操作来创建和使用自定义错误处理程序,我们以具有​ 宠物 ID 和​ 宠物名称 ​这两个字段的简单自适应表单为例,并在​ 宠物 ID 字段上使用自定义错误处理程序,以检查为调用外部服务而配置的 REST 端点所返回的各种错误,例如 200 - OK404 - Not Found400 - Bad Request

要在自适应表单中添加和使用自定义错误处理程序,请执行以下步骤:

1. 创建自定义错误处理程序 create-custom-error-message

要创建自定义错误函数,请执行以下步骤:

要创建自定义错误函数,请执行以下步骤:

  1. 克隆您的 AEM Forms as a Cloud Service 存储库。

  2. [AEM Forms as a Cloud Service repository folder]/apps/ 文件夹下创建一个文件夹。例如,创建一个名为 experience-league 的文件夹

  3. 导航到 [AEM Forms as a Cloud Service repository folder]/apps/[AEM Project Folder]/experience-league/ 并创建一个ClientLibraryFolder 作为 clientlibs

  4. 创建一个名为 js 的文件夹。

  5. 导航到 [AEM Forms as a Cloud Service repository folder]/apps/[AEM Project Folder]/clientlibs/js 文件夹。

  6. 添加JavaScript文件,例如, function.js. 该文件包含自定义错误处理程序的代码。
    让我们将以下代码添加到该 JavaScript 文件中,以在浏览器控制台中显示从 REST 服务端点接收到的响应和标头。

    code language-javascript
        /**
        Custom Error handler
        * @name customErrorHandler Custom Error Handler Function
        * @errorHandler
        */
        function customErrorHandler(response, headers, globals)
    {
        console.log("Custom Error Handler processing start...");
        console.log("response:"+JSON.stringify(response));
        console.log("headers:"+JSON.stringify(headers));
        alert("CustomErrorHandler - Enter valid PetId.")
        console.log("Custom Error Handler processing end...");
        return true; // true - call default error handler, false - don't call default error handler.
    }
    

    在上面的代码中, return true 自动调用默认错误处理程序。 要防止默认调用错误处理程序,请包括 return false.

    note note
    NOTE
    .content.xml 文件中,添加 categories = [custom-errorhandler-name]。例如,在此情况下,提供 [custom-errorhandler-name] 作为 customfunctionsdemoV2
  7. 保存 function.js 文件。

  8. 导航到 [AEM Forms as a Cloud Service repository folder]/apps/[AEM Project Folder]/clientlibs/js 文件夹。

  9. 添加文本文件作为 js.txt。该文件包含:

    code language-javascript
        #base=js
        functions.js
    
  10. 保存 js.txt 文件。
    创建的文件夹结构如下所示:

    创建的客户端库文件夹结构

    note note
    NOTE
    要了解有关如何创建自定义函数的更多信息,请单击规则编辑器中的自定义函数
  11. 使用以下命令在存储库中添加、提交和推送更改:

    code language-javascript
        git add .
        git commit -a -m "Adding error handling files"
        git push
    
  12. 运行管道。

成功执行管道后,便能在自适应表单规则编辑器中使用自定义错误处理程序。现在,让我们了解如何使用 AEM Forms 中规则编辑器的调用服务来配置和使用自定义错误处理程序。

2. 使用规则编辑器配置自定义错误处理程序 use-custom-error-handler

在自适应表单中实施自定义错误处理程序之前,请确保​ 客户端库类别 ​中的客户端库名称与 .content.xml 文件的类别选项中指定的名称一致。

在自适应表单容器配置中添加客户端库的名称

要通过​ 规则编辑器的调用服务 ​操作使用自定义错误处理程序,请执行以下操作:

  1. 在创作模式下打开自适应表单,选择表单组件,然后选择 规则编辑器 以打开规则编辑器。
  2. 选择​ 创建
  3. 在规则的 When 部分中创建条件。例如,在更改​ [宠物名称 ID 字段] ​时,会从​ 选择状态 ​下拉列表​ 更改 ​选择。
  4. Then 部分中,从​ 选择操作 ​下拉列表中选择​ 调用服务
  5. 从​ 输入 ​部分中选择​ 发布服务 ​及其相应的数据绑定。例如,要验证​ 宠物 ID,选择​ 发布服务 ​作为 GET /pet/{petId},并在​ 输入 ​部分中选择​ 宠物 ID
  6. 从​ 输出 ​部分中选择数据绑定。例如,在​ 输出 ​部分中选择​ 宠物名称
  7. 从​ 错误处理程序 ​部分中选择​ 自定义错误处理程序
  8. 单击​ 完成

在表单中添加自定义错误处理程序来处理错误响应

根据此规则,将使用 REST 端点所调用的外部服务针对您为​ 宠物 ID 输入的值来检查验证​ 宠物名称。如果未达到基于数据源的验证标准,错误消息将在字段级别显示。

在表单中添加自定义错误处理程序来处理错误响应

打开浏览器控制台,并检查从 REST 服务端点接收的响应和标头中是否有验证错误消息。

自定义错误处理程序函数负责根据错误响应来执行其他操作,例如显示模式对话框或发送分析事件。利用自定义错误处理程序函数,可以灵活地处理错误以满足具体用户要求。

附加信息 additional-information

另请参阅 see-also

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