自适应Forms中的错误处理程序

Adobe 建议使用现代、可扩展的数据捕获核心组件，以创建新的自适应表单或将自适应表单添加到 AEM Sites 页面。这些组件代表有关创建自适应表单的重大改进，确保实现令人印象深刻的用户体验。本文介绍了使用基础组件创作自适应表单的旧方法。

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

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

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

错误处理程序的用途

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

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

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

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

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

失败/错误响应格式

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

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

其中：

• errorCausedBy 描述失败的原因。
• errors 提及未能通过验证标准的字段的SOM表达式以及验证错误消息。
• 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":"<SOM expression 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 - if there is SERVER_SIDE_VALIDATION)
        "originMessage" : "<unstructured error message returned by service>" (optional - if there is SERVER_SIDE_VALIDATION)
    }

其中：

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

  • SERVER_SIDE_VALIDATION 指示因服务器端验证导致的失败。
  • FORM_SUBMISSION 指示表单提交期间发生的失败。
  • SERVICE_INVOCATION 指示第三方服务调用期间发生的失败。
  • FAILURE 指示常见失败。
  • VALIDATION_ERROR 指示因验证错误导致的失败。

• title (optional) 提供失败的标题或简要描述。

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

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

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

  • fieldname 提及未能通过验证标准的字段的SOM表达式。
  • dataRef 表示未通过验证的字段的 JSON 路径或 XPath。
  • details 包含带错误字段的验证错误消息。

• originCode (optional) 字段由 AEM 添加，包含由外部服务返回的 http 状态代码。

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

错误响应格式示例

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

前提条件

在自适应Forms中使用自定义错误处理程序之前：

• 基础知识到 创建自定义函数.
• 安装最新版本的 Apache Maven.

使用规则编辑器添加错误处理程序

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

利用规则编辑器，您可以：

• 添加默认错误处理程序函数
• 添加自定义错误处理程序函数

添加默认错误处理程序函数

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

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

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

添加自定义错误处理程序函数

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

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

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

自定义错误处理程序是一个函数（客户端库），旨在响应由外部服务返回的错误并向最终用户提供自定义响应。任何带注释 @errorHandler 的客户端库均被视为自定义错误处理程序函数。此注释有助于识别 .js 文件。

为了了解如何通过规则编辑器的调用服务操作来创建和使用自定义错误处理程序，我们以具有​宠物 ID 和​宠物名称​这两个字段的简单自适应表单为例，并在​宠物 ID 字段上使用自定义错误处理程序，以检查为调用外部服务而配置的 REST 端点所返回的各种错误，例如 200 - OK、404 - Not Found、400 - Bad Request。

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

1. 创建自定义错误处理程序
2. 使用规则编辑器配置自定义错误处理程序

1. 创建自定义错误处理程序

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

1. 登录 http://server:port/crx/de/index.jsp#.

2. 在 /apps 文件夹下创建一个文件夹。例如，创建一个名为的文件夹 experience-league.

3. 保存更改。

4. 导航到已创建的文件夹并创建节点类型 cq:ClientLibraryFolder 作为 clientlibs.

5. 导航到新创建的 clientlibs 文件夹并添加 allowProxy 和 categories 属性：

   

   注意

   您可以提供任意名称来取代 customfunctionsdemo.

6. 保存更改。

7. 创建名为的文件夹 js 在 clientlibs 文件夹。

8. 创建名为的JavaScript文件 functions.js 在 js 文件夹

9. 创建名为的文件 js.txt 在 clientlibs 文件夹。

10. 保存更改。
    创建的文件夹结构如下所示：

    

11. 双击 functions.js 文件以打开编辑器。 该文件包含自定义错误处理程序的代码。
    让我们将以下代码添加到该 JavaScript 文件中，以在浏览器控制台中显示从 REST 服务端点接收到的响应和标头。

        /**
        * Custom Error handler
        * @name customErrorHandler Custom Error Handler Function
        * @errorHandler
        */
        function customErrorHandler(response, headers)
        {
            console.log("Custom Error Handler processing start...");
            console.log("response:"+JSON.stringify(response));
            console.log("headers:"+JSON.stringify(headers));
            guidelib.dataIntegrationUtils.defaultErrorHandler(response, headers);
            console.log("Custom Error Handler processing end...");
        }
    

    要从自定义错误处理程序调用默认错误处理程序，请使用以下示例代码行：
    guidelib.dataIntegrationUtils.defaultErrorHandler(response, headers)

12. 保存 function.js.

13. 导航到 js.txt 并添加以下代码：

        #base=js
        functions.js
    

14. 保存 js.txt 文件。

现在，让我们了解如何使用 AEM Forms 中规则编辑器的调用服务来配置和使用自定义错误处理程序。

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

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

在本例中，客户端库名称提供为 customfunctionsdemo 在 .content.xml 文件。

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

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

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

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

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

附加信息

• 创建基于独立核心组件的自适应表单
• 为表单创建样式或主题
• 创建自适应表单或将自适应表单添加到 AEM Sites 页面