適用性表單的標準驗證錯誤訊息

上次更新: 2023-05-04
  • 建立對象:
  • User
注意

AEM 6.4已結束延伸支援,本檔案不再更新。 如需詳細資訊,請參閱 技術支援期. 尋找支援的版本 此處.

適用性表單會根據預先設定的驗證標準,驗證您在欄位中提供的輸入。 驗證條件會參考最適化表單中欄位可接受的輸入值。 您可以根據與最適化表單搭配使用的資料來源來設定驗證條件。 例如,如果您使用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 包含外部服務傳回的錯誤代碼
  • originMessage 包含外部服務傳回的原始錯誤資料

設定最適化表單提交以新增自訂處理常式

如果伺服器驗證錯誤訊息未以標準格式顯示,您可以啟用非同步提交,並在適用性表單提交時新增自訂錯誤處理常式,將訊息轉換為標準格式。

設定非同步最適化表單提交

新增自訂處理常式之前,您必須設定非同步提交的最適化表單。 執行下列步驟:

  1. 在最適化表單製作模式中,選取「表單容器」物件並點選 適用性表單屬性 來開啟其屬性。

  2. 提交 屬性部分,啟用 使用非同步提交.

  3. 選擇 在伺服器上重新驗證 在提交之前驗證伺服器上的輸入欄位值。

  4. 選擇提交操作:

    • 選擇 使用表單資料模型提交 並選擇適當的資料模型(如果使用基於RESTful Web服務) 表單資料模型 作為資料來源。
    • 選擇 提交到REST端點 和指定 重新導向URL/路徑,以使用RESTful網站服務作為資料來源。

    適用性表單提交屬性

  5. 點選 儲存 以儲存屬性。

在最適化表單提交上新增自訂錯誤處理常式

AEM Forms為表單提交提供現成可用的成功和錯誤處理常式。 處理常式是根據伺服器回應執行的用戶端函式。 提交表單時,將資料發送到伺服器進行驗證,伺服器會向客戶端返回一個響應,其中包含有關提交成功或錯誤事件的資訊。 資訊會以參數形式傳遞至相關處理常式,以執行函式。

執行下列步驟,在適用性表單提交上新增自訂錯誤處理常式:

  1. 在製作模式中開啟最適化表單、選取任何表單物件,然後點選 來開啟規則編輯器。
  2. 選擇 表單 在「表單對象」樹中,並點選 建立.
  3. 選擇 提交錯誤 從「事件」下拉式清單中。
  4. 編寫規則以將自定義錯誤結構轉換為標準錯誤結構並點選 完成 來儲存規則。

以下是將自訂錯誤結構轉換為標準錯誤結構的范常式式碼:

var data = $event.data;
var som_map = {
    "id": "guide[0].guide1[0].guideRootPanel[0].Pet[0].id_1[0]",
    "name": "guide[0].guide1[0].guideRootPanel[0].Pet[0].name_2[0]",
    "status": "guide[0].guide1[0].guideRootPanel[0].Pet[0].status[0]"
};

var errorJson = {};
errorJson.errors = [];

if (data) {
    if (data.originMessage) {
        var errorData;
        try {
            errorData = JSON.parse(data.originMessage);
        } catch (err) {
            // not in json format
        }

        if (errorData) {
            Object.keys(errorData).forEach(function(key) {
                var som_key = som_map[key];
                if (som_key) {
                    var error = {};
                    error.somExpression = som_key;
                    error.errorMessage = errorData[key];
                    errorJson.errors.push(error);
                }
            });
        }
        window.guideBridge.handleServerValidationError(errorJson);
    } else {
        window.guideBridge.handleServerValidationError(data);
    }
}

var som_map 列出要轉換為標準格式的最適化表單欄位的SOM表達式。 您可以點選欄位並選取,以在最適化表單中檢視任何欄位的SOM運算式 查看SOM表達式.

此自訂錯誤處理常式會轉換 var som_map 格式。 因此,驗證錯誤訊息會以最適化表單的欄位層級顯示。

使用Invoke Service操作添加自定義處理程式

執行下列步驟來新增錯誤處理常式,以使用將自訂錯誤結構轉換為標準錯誤結構 規則編輯器的 調用服務操作:

  1. 在製作模式中開啟最適化表單、選取任何表單物件,然後點選 規則編輯器 來開啟規則編輯器。
  2. 點選 建立.
  3. 區段。 例如,當[欄位名稱] 已變更。 選擇 已變更選擇狀態 下拉式清單來達成此條件。
  4. 然後 部分,選擇 調用服務選擇操作 下拉式清單。
  5. 輸入 區段。 例如,如果您要驗證 名稱, ID,和 狀態 欄位,選取貼文服務(pet),然後選取pet.name、pet.id和pet.status(位於 輸入 區段。

因為此規則,您為輸入的值 名稱, ID,和 狀態 當步驟2中定義的欄位變更,且您從表單中的欄位中取出索引標籤時,欄位即會經過驗證。

  1. 選擇 代碼編輯器 從「模式選擇」下拉清單中。

  2. 點選 編輯代碼.

  3. 從現有程式碼中刪除下列行:

    guidelib.dataIntegrationUtils.executeOperation(operationInfo, inputs, outputs);
    
  4. 編寫規則以將自定義錯誤結構轉換為標準錯誤結構並點選 完成 來儲存規則。
    例如,在結尾處新增下列范常式式碼,以將自訂錯誤結構轉換為標準錯誤結構:

    var errorHandler = function(jqXHR, data) {
    var som_map = {
        "id": "guide[0].guide1[0].guideRootPanel[0].Pet[0].id_1[0]",
        "name": "guide[0].guide1[0].guideRootPanel[0].Pet[0].name_2[0]",
        "status": "guide[0].guide1[0].guideRootPanel[0].Pet[0].status[0]"
    };
    
    
    var errorJson = {};
    errorJson.errors = [];
    
    if (data) {
        if (data.originMessage) {
            var errorData;
            try {
                errorData = JSON.parse(data.originMessage);
            } catch (err) {
                // not in json format
            }
    
            if (errorData) {
                Object.keys(errorData).forEach(function(key) {
                    var som_key = som_map[key];
                    if (som_key) {
                        var error = {};
                        error.somExpression = som_key;
                        error.errorMessage = errorData[key];
                        errorJson.errors.push(error);
                    }
                });
            }
            window.guideBridge.handleServerValidationError(errorJson);
        } else {
            window.guideBridge.handleServerValidationError(data);
        }
      }
    };
    
    guidelib.dataIntegrationUtils.executeOperation(operationInfo, inputs, outputs, null, errorHandler);
    

    var som_map 列出要轉換為標準格式的最適化表單欄位的SOM表達式。 您可以點選欄位並選取,以在最適化表單中檢視任何欄位的SOM運算式 查看SOM表達式更多選項 (…)功能表。

    請確定您將下列程式碼範例行複製到自訂錯誤處理常式:

    guidelib.dataIntegrationUtils.executeOperation(operationInfo, inputs, outputs, null, errorHandler);
    

    executeOperation API包含 nullerrorHandler 參數(以新的自訂錯誤處理常式為基礎)。

    此自訂錯誤處理常式會轉換 var som_map 格式。 因此,驗證錯誤訊息會以最適化表單的欄位層級顯示。

本頁內容