開發Forms (Classic UI) developing-forms-classic-ui

表單的基本結構為:

  • 表單開始
  • 表單元素
  • 表單結尾

所有這些都是透過一系列預設值實現的 表單元件,適用於標準AEM安裝。

除了 開發新元件 若要在您的表單上使用,您也可以:

使用指令碼 以視需要擴充功能。

NOTE
本檔案著重於使用開發表單 基礎元件 在傳統UI中。 Adobe建議使用新的 核心元件隱藏條件 用於觸控式UI中的表單開發。

預先載入表單值 preloading-form-values

表單開始元件提供 載入路徑,此選用的路徑會指向存放庫中的節點。

載入路徑是節點屬性的路徑,用來將預先定義的值載入表單上的多個欄位中。

此選擇性欄位指定存放庫中節點的路徑。 當此節點具有符合欄位名稱的屬性時,則表單上的適當欄位將使用這些屬性的值預先載入。 如果不存在相符專案,則欄位會包含預設值。

NOTE
A 表單動作 也可以設定載入初始值的來源。 這是使用來完成的 FormsHelper#setFormLoadResource 裡面 init.jsp.
唯有未設定時,作者才會從起始表單元件中設定的路徑填入表單。

預先載入具有多個值的表單欄位 preloading-form-fields-with-multiple-values

各種表單欄位也具有 專案載入路徑,也是指向存放庫中的節點的選用路徑。

專案載入路徑 是節點屬性的路徑,用來將預先定義的值載入表單上的特定欄位,例如 下拉式清單核取方塊群組選項按鈕群組.

範例 — 預先載入含有多個值的下拉式清單 example-preloading-a-dropdown-list-with-multiple-values

下拉式清單可以設定您選取的值範圍。

專案載入路徑 可用來從存放庫中的資料夾存取清單,並將這些檔案預先載入欄位中:

  1. 建立sling資料夾( sling:Folder)例如, /etc/designs/<myDesign>/formlistvalues

  2. 新增屬性(例如, myList)的字串( String[]),以包含下拉式專案清單。 也可以使用指令碼匯入內容,例如使用JSP指令碼或shell指令碼中的cURL。

  3. 使用中的完整路徑 專案載入路徑 欄位:例如 /etc/designs/geometrixx/formlistvalues/myList

請注意,如果 String[] 格式如下:

  • AL=Alabama
  • AK=Alaska

依此類推,則AEM產生清單為:

  • <option value="AL">Alabama</option>
  • <option value="AK">Alaska</option>

舉例來說,這項功能在多語言設定中可以妥善運用。

開發您自己的表單動作 developing-your-own-form-actions

表單需要動作。 動作會定義隨使用者資料提交表單時所執行的操作。

標準AEM安裝會提供一系列動作,您可以在下列位置看到這些動作:

/libs/foundation/components/form/actions

動作型別 「 」清單 表單 元件:

chlimage_1-8

本節說明如何開發自己的表單動作以包含在此清單中。

您可以在底下新增自己的動作 /apps 如下所示:

  1. 建立型別節點 sling:Folder. 指定可反映要實作之動作的名稱。

    例如:

    /apps/myProject/components/customFormAction

  2. 在此節點上定義下列屬性,然後按一下 全部儲存 若要保留您的變更:

    • sling:resourceType — 設為 foundation/components/form/action

    • componentGroup — 定義為 .hidden

    • 選擇性:

      • jcr:title — 指定您選擇的標題,這會顯示在下拉式選擇清單中。 如果未設定,則會顯示節點名稱

      • jcr:description — 輸入您選擇的說明

  3. 在資料夾中建立對話方塊節點:

    1. 新增欄位,以便在選擇動作後,作者可以編輯表單對話方塊。
  4. 在資料夾中建立:

    1. 後置指令碼。
      指令碼的名稱為 post.POST.<extension>例如, post.POST.jsp
      提交表單以處理表單時會叫用後置指令碼,其中包含處理表單所送出資料的程式碼 POST.

    2. 新增在提交表單時叫用的轉寄指令碼。
      指令碼的名稱為 forward.<extension>,例如, forward.jsp
      此指令碼可定義路徑。 接著會將目前的請求轉送至指定的路徑。

    必要的呼叫是 FormsHelper#setForwardPath (2種變體)。 典型案例是執行一些驗證或邏輯來尋找目標路徑,然後前進到該路徑,讓預設的SlingPOSTservlet實際執行JCR中的儲存。

    也可能會有另一個servlet執行實際處理,在這種情況下,表單動作和 forward.jsp 只會作為「貼上」程式碼。 這方面的範例為郵件動作: /libs/foundation/components/form/actions/mail,會將詳細資料轉送至 <currentpath>.mail.html郵件servlet所在的位置。

    所以:

    • a post.POST.jsp 對於完全由動作本身完成的小型作業非常有用
    • forward.jsp 在只需要委派時很有用。

    指令碼的執行順序為:

    • 在轉譯表單時( GET):

      1. init.jsp
      2. 對於所有欄位的限制: clientvalidation.jsp
      3. 表單的validationRT: clientvalidation.jsp
      4. 表單已透過載入資源載入(如果已設定)
      5. addfields.jsp 在演算內部時 <form></form>
    • 處理表單時 POST

      1. init.jsp

      2. 對於所有欄位的限制: servervalidation.jsp

      3. 表單的validationRT: servervalidation.jsp

      4. forward.jsp

      5. 若已設定正向路徑( FormsHelper.setForwardPath)、轉送要求,然後呼叫 cleanup.jsp

      6. 如果未設定轉送路徑,請呼叫 post.POST.jsp (到此結束,否 cleanup.jsp 已呼叫)

  5. 再次在資料夾中選擇性地新增:

    1. 用於新增欄位的指令碼。
      指令碼的名稱為 addfields.<extension>例如, addfields.jsp
      一個 addfields 在寫入表單開始的HTML後,會立即叫用指令碼。 這可讓動作在表單內新增自訂輸入欄位或其他此類HTML。

    2. 初始化指令碼。
      指令碼的名稱為 init.<extension>例如, init.jsp
      此指令碼會在表單轉譯時叫用。 這可用來初始化動作細節。

    3. 清除指令碼。
      指令碼的名稱為 cleanup.<extension>例如, cleanup.jsp
      此指令碼可用於執行清理。

  6. 使用 Forms parsys中的元件。 此 動作型別 下拉式清單現在會包含您的新動作。

    note note
    NOTE
    若要檢視屬於產品一部分的預設動作:
    /libs/foundation/components/form/actions

開發您自己的表單限制 developing-your-own-form-constraints

可在兩個層級施加限制:

個別欄位的限制 constraints-for-individual-fields

您可以為個別欄位新增自己的限制(在 /apps)如下所示:

  1. 建立型別節點 sling:Folder. 指定反映要實作之限制的名稱。

    例如:

    /apps/myProject/components/customFormConstraint

  2. 在此節點上定義下列屬性,然後按一下 全部儲存 若要保留您的變更:

    • sling:resourceType — 設為 foundation/components/form/constraint

    • constraintMessage — 提交表單時,如果欄位無效,根據限制顯示的自訂訊息

    • 選擇性:

      • jcr:title — 指定您選取的標題,這會顯示在選取專案清單中。 如果未設定,則會顯示節點名稱
      • hint — 使用者有關如何使用欄位的其他資訊
  3. 在此資料夾中,您需要下列指令碼:

    • 使用者端驗證指令碼:指令碼的名稱為 clientvalidation.<extension>例如, clientvalidation.jsp
      這會在表單欄位轉譯時叫用。 它可用來建立使用者端JavaScript,以驗證使用者端上的欄位。

    • 伺服器驗證指令碼:指令碼的名稱為 servervalidation.<extension>例如, servervalidation.jsp
      這會在表單提交時叫用。 它可用於在提交欄位後驗證伺服器上的欄位。

NOTE
範例限制可見於:
/libs/foundation/components/form/constraints

表單全域限制 form-global-constraints

表單全域驗證是透過在起始表單元件( validationRT)。 例如:

apps/myProject/components/form/validation

接著,您可以定義:

  • a clientvalidation.jsp — 插入至欄位的使用者端驗證指令碼之後
  • servervalidation.jsp — 也是在個別欄位伺服器驗證之後呼叫 POST.

顯示和隱藏表單元件 showing-and-hiding-form-components

您可以根據表單中其他欄位的值,設定表單以顯示或隱藏表單元件。

只有在特定條件下才需要表單欄位時,變更欄位的可見度會很有用。 例如,在意見回饋表單上,系統會詢問客戶是否希望以電子郵件傳送產品資訊。 選取「是」後,會出現文字欄位,讓客戶輸入其電子郵件地址。

使用 編輯顯示/隱藏規則 對話方塊,指定顯示或隱藏表單元件的條件。

showhideeditor

使用對話方塊頂端的欄位來指定下列資訊:

  • 指定隱藏或顯示元件的條件。
  • 是否需有任何或所有條件必須為true才能顯示或隱藏元件。

一或多個條件會顯示在這些欄位下方。 條件會將另一個表單元件(位於相同表單)的值與一個值比較。 如果欄位中的實際值符合條件,則條件的評估結果為true。 條件包括下列資訊:

  • 測試的表單欄位的標題。
  • 運運算元。
  • 比對的值會與欄位值比較。

例如,標題為「 」的「選項群組」元件 Receive email notifications?* *包含 YesNo 選項按鈕。 標題為的文字欄位元件 Email Address 會使用以下條件,使其在以下情況下可見: Yes 已選取:

潮濕條件

在JavaScript中,條件會使用Element Name屬性的值來參照欄位。 在上一個範例中,選項群組元件的「元素名稱」屬性為 contact. 下列程式碼為該範例的等效JavaScript程式碼:

((contact == "Yes"))

若要顯示或隱藏表單元件:

  1. 編輯特定的表單元件。

  2. 選取 顯示/隱藏 以開啟 編輯顯示/隱藏規則 對話方塊:

    • 在第一個下拉式清單中選取 顯示隱藏 以指定條件是否決定要顯示或隱藏元件。

    • 在上行末端的下拉式清單中選取:

      • 全部 — 如果所有條件都必須為true才能顯示或隱藏元件
      • 任何 — 如果只有一個或多個條件必須為true才能顯示或隱藏元件
    • 在條件行(其中一個顯示為預設值)中,選取元件、運運算元,然後指定值。

    • 視需要按一下「 」,新增更多條件 新增條件.

    例如:

    chlimage_1-9

  3. 按一下 確定 以儲存定義。

  4. 儲存定義後, 編輯規則 連結會出現在 顯示/隱藏 選項來建立表單。 按一下此連結以開啟 編輯顯示/隱藏規則 進行變更的對話方塊。

    按一下 確定 以儲存所有變更。

    chlimage_1-10

    note caution
    CAUTION
    可以看見並測試「顯示/隱藏」定義的效果:
    • 預覽 作者環境上的模式(第一次切換為預覽時需要重新載入頁面)

    • 在發佈環境中

處理中斷的元件參照 handling-broken-component-references

顯示/隱藏條件會使用Element Name屬性的值來參照表單中的其他元件。 當任何條件引用已刪除或已變更Element Name屬性的元件時,顯示/隱藏設定無效。 發生這種情況時,您需要手動更新條件,否則表單載入時發生錯誤。

當顯示/隱藏設定無效時,設定僅以JavaScript程式碼形式提供。 編輯程式碼以修正問題。程式碼使用原本用來參考元件的Element Name屬性。

開發指令碼以與Forms搭配使用 developing-scripts-for-use-with-forms

如需可在編寫指令碼時使用的API元素的詳細資訊,請參閱 與表單相關的Javadoc.

您可以將此用於動作,例如在提交表單前呼叫服務,以及在服務失敗時取消服務:

  • 定義驗證資源型別

  • 包含用於驗證的指令碼:

    • 在您的JSP中,呼叫您的Web服務並建立 com.day.cq.wcm.foundation.forms.ValidationInfo 包含錯誤訊息的物件。 如果發生錯誤,將不會張貼表單資料。
recommendation-more-help
19ffd973-7af2-44d0-84b5-d547b0dffee2