アダプティブForms（コアコンポーネント）のエラーハンドラー

AEM Forms には、すぐに使用できる、フォーム送信の成功ハンドラーと失敗ハンドラーが用意されています。また、エラーハンドラー関数をカスタマイズする機能もあります。例えば、特定のエラーコードに対してバックエンドでカスタムワークフローを呼び出したり、サービスが停止していることを顧客に通知したりできます。ハンドラーは、サーバー応答に基づいて実行されるクライアントサイド関数です。API を使用して外部サービスが呼び出されると、データが検証のためにサーバーに送信され、サーバーは送信の成功イベントまたはエラーイベントに関する情報と共に、応答をクライアントに返します。この情報は、関連するハンドラーにパラメーターとして渡され、関数が実行されます。エラーハンドラーは、発生したエラーや検証の問題を管理したり表示したりするのに役立ちます。

アダプティブフォームは、事前設定された検証条件に基づいて、フィールドに指定された入力を検証し、外部サービスを呼び出すように設定された REST エンドポイントから返される様々なエラーを確認します。アダプティブフォームで使用するデータソースに基づいて、検証条件を設定できます。例えば、RESTful web サービスをデータソースとして使用する場合、Swagger 定義ファイルで検証条件を定義できます。

入力値が検証条件を満たす場合、その値は他のデータソースに送信され、アダプティブフォームはエラーハンドラーを使用してエラーメッセージを表示します。 この方法と同様に、アダプティブフォームをカスタムエラーと統合して、データ検証を実行します。入力値が検証条件を満たさない場合、アダプティブフォームのフィールドレベルでエラーメッセージが表示されます。サーバーから返される検証エラーメッセージが、標準メッセージ形式の場合に発生します。

エラーハンドラーの使用

エラーハンドラーは、様々な目的で使用されます。エラーハンドラー関数の使用例の一部を以下に示します。

• 検証の実行：事前定義されたルールや条件に対してユーザー入力を検証することで、エラー処理を開始します。ユーザーがアダプティブフォームに入力すると、エラーハンドラーは入力を検証し、必要な形式、長さ、その他の制約が満たされていることを確認します。

• リアルタイムでのフィードバックの提供：エラーが検出されると、エラーハンドラーは、対応するフォームフィールドの下にフィードバック（インラインエラーメッセージなど）を、ユーザーに即時に表示します。このフィードバックは、ユーザーがフォームを送信して応答を待たなくても、エラーを特定して修正するのに役立ちます。

• エラーメッセージの表示：アダプティブフォームの送信で検証エラーが発生すると、エラーハンドラーは適切なエラーメッセージを表示します。 エラーメッセージは、明確かつ簡潔で、注意が必要な特定のフィールドをハイライト表示する必要があります。

• エラーのあるフィールドのハイライト表示：特定の誤ったフィールドにユーザーの注意を引くために、エラーハンドラーは対応するフィールドをハイライト表示するか、視覚的に区別します。この処理は、背景色の変更、アイコンや境界線の追加、またはユーザーがエラーを迅速に見つけて対処する上で役立つ、その他の視覚的なヒントを追加することによって実行されます。

失敗／エラー応答形式

サーバー検証エラーメッセージが次の標準形式の場合、アダプティブフォームはフィールドレベルでエラーを表示します。
次のコードは、既存の失敗応答構造を示しています。

   {
    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 - 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 は、検証条件を満たさなかったフィールドの修飾フィールド名に言及します。
  • dataRef は、検証に失敗したフィールドの JSON パスまたは XPath を表します。
  • details には、検証エラーメッセージとエラーのあるフィールドが含まれています。

• originCode (optional) は、AEMによって追加されたフィールドで、外部サービスから返された http ステータスコードが含まれています。

• originMessage (optional) は、AEMによって追加されたフィールドで、外部サービスから返された生のエラーデータが含まれています。

エラー応答形式のサンプル

エラー応答を表示するオプションの一部を次に示します。

前提条件

アダプティブFormsでエラーハンドラーを使用する前に、次の手順を実行します。

• 環境でのアダプティブFormsコアコンポーネントの有効化.
• 基本知識 カスタム関数の作成.
• Apache Maven の最新リリースをインストールします。

ルールエディターを使用してエラーハンドラーを追加

ルールエディターのサービスの呼び出しアクションを使用して、アダプティブフォームで使用するデータソースに基づいて検証条件を定義します。RESTful web サービスをデータソースとして使用する場合、Swagger 定義ファイルで検証条件を定義できます。アダプティブフォームのエラーハンドラー関数とルールエディターを利用すると、エラー処理を効果的に管理およびカスタマイズできます。ルールエディターを使用して条件を定義し、ルールがトリガーされたときに実行するアクションを設定します。アダプティブフォームは、事前設定された検証条件に基づいて、フィールドに入力した内容を検証します。入力値が検証条件を満たさない場合、エラーメッセージはアダプティブフォームのフィールドレベルで表示されます。

ルールエディターを使用して、次の操作を実行できます。

• デフォルトのエラーハンドラー関数を追加
• カスタムエラーハンドラー関数を追加

デフォルトのエラーハンドラー関数を追加

デフォルトのエラーハンドラーは、エラー応答が標準スキーマの場合、またはサーバーサイドの検証エラーの場合に、フィールドにエラーメッセージを表示する機能をサポートしています。
ルールエディターのサービスの呼び出し action, take an example of a simple Adaptive Form with two fieldsアクションを使用してカスタムエラーハンドラーを作成および使用する方法を理解するために、「ペット ID」および「ペット名」という 2 つのフィールドを持つアダプティブフォームを例に、「ペット ID」でカスタムエラーハンドラーを使用して、200 - OK、404 - Not Found、400 - Bad Request などの外部サービスを呼び出すように設定された REST エンドポイントが返す様々なエラーをチェックしましょう。ルールエディターのサービスの呼び出しアクションを使用してデフォルトのエラーハンドラーを追加するには、次の手順を実行します。

1. アダプティブフォームをオーサリングモードで開き、フォームコンポーネントを選択して、 ルールエディター をクリックして、ルールエディターを開きます。
2. 「作成」を選択します。
3. ルールの​条件​セクションで条件を作成します。例： 条件[ペット ID フィールドの名前] が変更されました。 「 」を 状態を選択 」ドロップダウンリストから選択できます。
4. 「Then」セクションの​アクションの選択​ドロップダウンリストで「サービスの呼び出し」を選択します。
5. 「入力」セクションから、Post サービス​とそれに対応するデータ連結を選択します。例えば、ペット ID を検証する場合は、Post サービス​を GET /pet/{petId} として選択し、「入力」セクションで「ペット ID」を選択します。
6. 「出力」セクションからデータ連結を選択します。例えば、「出力」セクションで「ペット名」を選択します。
7. 「エラーハンドラー」セクションから「カスタムエラーハンドラー」を選択します。
8. 「完了」をクリックします。

このルールの結果、REST エンドポイントによって呼び出された外部サービスを使用して、ペット ID に入力した値が​ペット名​の検証をチェックします。データソースに基づく検証条件が失敗した場合は、エラーメッセージがフィールドレベルで表示されます。

カスタムエラーハンドラー関数を追加

カスタムエラーハンドラー関数を追加して、次のようなアクションを実行できます。

• 非標準または標準のエラー応答を使用するエラー応答を処理します。これらの非標準のエラー応答は、エラー応答の標準スキーマに準拠していないことに注意する必要があります。
• 分析イベントを任意の分析プラットフォームに送信します。例：Adobe Analytics.
• エラーメッセージが表示されるモーダルダイアログを表示します。

上記のアクションに加えて、カスタムエラーハンドラーを使用して、特定のユーザー要件を満たすカスタマイズされた関数を実行できます。

カスタムエラーハンドラーは、外部サービスから返されたエラーに応答し、カスタマイズされた応答をエンドユーザーに配信するように設計された関数（クライアントライブラリ）です。注釈 @errorHandler 付きのクライアントライブラリは、カスタムエラーハンドラー関数と見なされます。この注釈は、 .js ファイル。

ルールエディターのサービスの呼び出しアクションを使用してカスタムエラーハンドラーを作成および使用する方法を理解するために、「ペット ID」および「ペット名」という 2 つのフィールドを持つアダプティブフォームを例に、「ペット ID」でカスタムエラーハンドラーを使用して、200 - OK、404 - Not Found、400 - Bad Request などの外部サービスを呼び出すように設定された REST エンドポイントが返す様々なエラーをチェックしましょう。

アダプティブフォームにカスタムエラーハンドラーを追加して使用するには、次の手順を実行します。

1. カスタムエラーハンドラーを作成
2. ルールエディターを使用してカスタムエラーハンドラーを設定

1. カスタムエラーハンドラーを作成

カスタムエラー関数を作成するには、次の手順を実行します。

1. ログイン http://server:port/crx/de/index.jsp#.

2. の下にフォルダーを作成します。 /apps フォルダー。 例えば、という名前のフォルダーを作成します。 experience-league.

3. 変更を保存します。

4. 作成したフォルダーに移動し、タイプのノードを作成します。 cq:ClientLibraryFolder as 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, globals)
        {
            console.log("Custom Error Handler processing start...");
            console.log("response:"+JSON.stringify(response));
            console.log("headers:"+JSON.stringify(headers));
            alert("CustomErrorHandler - Please enter valid PetId.")
            globals.invoke('defaultErrorHandler',response, headers)
            console.log("Custom Error Handler processing end...");
        }
    

    カスタムエラーハンドラーからデフォルトのエラーハンドラーを呼び出すには、サンプルコードの次の行が使用されます。
    globals.invoke('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. ルールの​条件​セクションで条件を作成します。例えば、[ペット ID の名前フィールド]​が変更された場合は、「状態を選択 」ドロップダウンリストから「変更済み」を選択します。
4. 「Then」セクションの​アクションの選択​ドロップダウンリストで「サービスの呼び出し」を選択します。
5. 「入力」セクションから、Post サービス​とそれに対応するデータ連結を選択します。例えば、ペット ID を検証する場合は、Post サービス​を GET /pet/{petId} として選択し、「入力」セクションで「ペット ID」を選択します。
6. 「出力」セクションからデータ連結を選択します。例えば、「出力」セクションで「ペット名」を選択します。
7. 「エラーハンドラー」セクションから「カスタムエラーハンドラー」を選択します。
8. 「完了」をクリックします。

このルールの結果、REST エンドポイントによって呼び出された外部サービスを使用して、ペット ID に入力した値が​ペット名​の検証をチェックします。データソースに基づく検証条件が失敗した場合は、エラーメッセージがフィールドレベルで表示されます。

ブラウザーコンソールを開き、REST サービスエンドポイントから受け取った応答とヘッダーで、検証エラーメッセージを確認します。

カスタムエラーハンドラー関数は、エラー応答に基づいて、モーダルダイアログの表示や分析イベントの送信など、追加のアクションを実行します。カスタムエラーハンドラー関数を使用すると、特定のユーザー要件に合わせて柔軟にエラー処理をカスタマイズできます。

関連トピック

• スタンドアロンのコアコンポーネントベースのアダプティブフォームを作成
• フォームのスタイルまたはテーマを作成
• AEM Sites ページへのアダプティブフォームの作成または追加