為最適化表單欄位建立自訂外觀

簡介

最適化表單運用外觀架構,協助您建立最適化表單欄位的自訂外觀,並提供不同的使用者體驗。 例如,以切換按鈕取代選項按鈕和核取方塊,或使用自訂jQuery增效模組來限制使用者在諸如電話號碼或電子郵件ID等欄位中的輸入。

本檔案說明如何使用jQuery外掛程式來建立最適化表單欄位的替代體驗。 此外,它還展示了一個示例,用於為數字欄位元件建立自定義外觀,以顯示為數字步進器或滑塊。

我們先來看一下本文使用的關鍵術語和概念。

觀:指最適化表單欄位中各種元素的樣式、外觀和組織。它通常包含標籤、提供輸入的互動區域、說明圖示,以及欄位的簡短和長篇說明。 本文討論的外觀定制適用於該領域輸入區域的外觀。

jQuery plugin提供基於jQuery Widget架構的標準機制,以實作替代外觀。

ClientLib 由複雜的JavaScript和CSS程式碼驅動的AEM用戶端處理中的用戶端程式庫系統。如需詳細資訊,請參閱使用用戶端程式庫。

ArchetypeA Maven專案範本工具套件,定義為Maven專案的原始圖樣或模型。如需詳細資訊,請參閱原型簡介。

User Control指介面工具集中包含欄位值的主要元素,並由外觀架構用來將自訂介面工具集UI與最適化表單模型系結。

建立自訂外觀的步驟

建立自定義外觀的高級步驟如下:

  1. 建立專案:建立Maven專案,以產生要部署在AEM上的內容套件。

  2. 擴充現有的Widget類別:擴充現有的介面工具集類別並覆寫所需的類別。

  3. 建立客戶端庫:建立程 clientLib: af.customwidget 式庫並新增所需的JavaScript和CSS檔案。

  4. 建立並安裝專案:建立Maven專案,並在AEM上安裝產生的內容套件。

  5. 更新最適化表單:更新最適化表單欄位屬性,以使用自訂外觀。

建立專案

主原型是建立自訂外觀的起點。 待用原型的詳細內容如下:

  • 儲存庫:https://repo.adobe.com/nexus/content/groups/public/
  • 對象ID:自訂外觀原型
  • 群組ID:com.adobe.aemforms
  • 版本:1.0.4

執行以下命令以基於原型建立本地項目:

mvn archetype:generate -DarchetypeRepository=https://repo.adobe.com/nexus/content/groups/public/ -DarchetypeGroupId=com.adobe.aemforms -DarchetypeArtifactId=custom-appearance-archetype -DarchetypeVersion=1.0.4

該命令從儲存庫下載Maven插件和原型資訊,並根據以下資訊生成項目:

  • groupId:產生的Maven專案所使用的群組ID
  • artifactId:生成的Maven項目使用的對象ID。
  • 版本:產生的Maven專案版本。
  • package:用於檔案結構的包。
  • artifactName:產生的AEM套件的對象名稱。
  • packageGroup:產生的AEM套件的套件群組。
  • widgetName:用於參考的外觀名稱。

生成的項目具有以下結構:

─<artifactId>

 └───src

     └───main

         └───content

             └───jcr_root

                 └───etc

                     └───clientlibs

                         └───custom

                             └───<widgetName>

                                 ├───common [client library - af.customwidgets which encapsulates below clientLibs]

                                 ├───integration [client library - af.customwidgets.<widgetName>_widget which contains template files for integrating a third-party plugin with Adaptive Forms]

                                 │   ├───css

                                 │   └───javascript

                                 └───jqueryplugin [client library - af.customwidgets.<widgetName>_plugin which holds the third-party plugins and related dependencies]

                                     ├───css

                                     └───javascript

擴充現有的Widget類別

建立專案範本後,請視需要進行下列變更:

  1. 將協力廠商外掛程式相依性加入專案。

    1. 將協力廠商或自訂jQuery增效模組置於jqueryplugin/javascript檔案夾,並將相關的CSS檔案置於jqueryplugin/css檔案夾。 如需詳細資訊,請參閱jqueryplugin/javascript and jqueryplugin/css資料夾下的JS和CSS檔案。

    2. 修改js.txtcss.txt檔案,以包含jQuery外掛程式的任何其他JavaScript和CSS檔案。

  2. 將協力廠商外掛程式與架構整合,讓自訂外觀架構與jQuery外掛程式之間互動。 新介面工具集只有在您擴充或覆寫下列函式後,才能運作。

函數 說明
render render函式返回構件的預設HTML元素的jQuery對象。 預設的HTML元素應為可聚焦類型。 例如,<a><input><li>。 傳回的元素會用作$userControl。 如果$userControl指定上述限制,則AbstractWidget類別的函式會如預期般運作,否則某些常用API(焦點,按一下)需要變更。
getEventMap 傳回將HTML事件轉換為XFA事件的地圖。
{ blur: XFA_EXIT_EVENT, }
此範例顯示 blur 是HTML事件, XFA_EXIT_EVENT 是對應的XFA事件。
getOptionsMap 傳回地圖,其中提供選項變更時要執行之動作的詳細資訊。 鍵是提供給介面工具集的選項,值是在偵測到選項變更時呼叫的函式。 介面工具集為所有常用選項(valuedisplayValue除外)提供處理常式。
getCommitValue 每當jQuery Widget的值儲存在XFA模型(例如在文字欄位的退出事件上)時,jQuery Widget架構就會載入函式。 實作應傳回儲存在介面工具集中的值。 處理常式會隨附選項的新值。
showValue 預設情況下,在XFA中,輸入事件時,將顯示該欄位的rawValue。 此函式被調用,以向用戶顯示rawValue
showDisplayValue 依預設,在退出事件時的XFA中,會顯示欄位的formattedValue。 此函式被調用,以向用戶顯示formattedValue
  1. 視需要更新integration/javascript資料夾中的JavaScript檔案。

    • 將文字__widgetName__取代為實際的介面工具集名稱。

    • 從適當的現成可用介面工具集類別擴充介面工具集。 在大多數情況下,它是與要替換的現有Widget對應的Widget類。 父類名稱用於多個位置,因此建議搜索檔案中字串xfaWidget.textField的所有實例,並將它們替換為實際使用的父類。

    • 擴充render方法以提供替代UI。 它是呼叫jQuery外掛程式以更新UI或互動行為的位置。 render方法應傳回使用者控制元素。

    • 延伸getOptionsMap方法,以覆寫因介面工具集變更而影響的任何選項設定。 函式返回映射,該映射提供了在選項更改時要執行的操作的詳細資訊。 鍵是提供給介面工具集的選項,而值是偵測到選項變更時呼叫的函式。

    • getEventMap方法會映射由介面工具集觸發的事件,以及最適化表單模型所需的事件。 預設值會對應預設介面工具集的標準HTML事件,若觸發替代事件,則需要更新。

    • showDisplayValueshowValue會套用顯示和編輯圖片子句,並可覆寫以具有替代行為。

    • commit事件發生時,最適化表單架構會呼叫getCommitValue方法。 通常是退出事件,但下拉式清單、選項按鈕和核取方塊元素在變更時除外)。 如需詳細資訊,請參閱最適化表單運算式

    • 範本檔案提供各種方法的範例實作。 移除不要擴充的方法。

建立客戶端庫

Maven原型產生的範例專案會自動建立必要的用戶端程式庫,並將它們封裝在具有af.customwidgets類別的用戶端程式庫中。 af.customwidgets中可用的JavaScript和CSS檔案會在執行時期中自動包含。

建立並安裝

若要建立專案,請在shell上執行下列命令,以產生需要安裝在AEM伺服器上的CRX套件。

mvn clean install

注意

主項目引用POM檔案中的遠程儲存庫。 這僅供參考,根據Maven標準,儲存庫資訊將在settings.xml檔案中捕獲。

更新最適化表單

要將自定義外觀應用於最適化表單域,請執行以下操作:

  1. 在編輯模式中開啟最適化表單。
  2. 為要應用自定義外觀的欄位開啟​屬性​對話框。
  3. 在​Styling​標籤中,更新CSS class屬性,以widget_<widgetName>格式新增外觀名稱。 例如:widget_numericstepper

範例:建立自訂外觀  

現在,讓我們看一個示例,以建立數字欄位的自定義外觀,使其顯示為數字步進器或滑塊。 執行以下步驟:

  1. 執行以下命令以基於Maven原型建立本地項目:

    mvn archetype:generate -DarchetypeRepository=https://repo.adobe.com/nexus/content/groups/public/ -DarchetypeGroupId=com.adobe.aemforms -DarchetypeArtifactId=custom-appearance-archetype -DarchetypeVersion=1.0.4

    它提示您指定下列參數的值。
    此範例中使用的值會以粗體反白顯示

    Define value for property 'groupId': com.adobe.afwidgets

    Define value for property 'artifactId': customWidgets

    Define value for property 'version': 1.0.1-SNAPSHOT

    Define value for property 'package': com.adobe.afwidgets

    Define value for property 'artifactName': customWidgets

    Define value for property 'packageGroup': adobe/customWidgets

    Define value for property 'widgetName': numericStepper

  2. 導覽至customWidgets(為artifactID屬性指定的值)目錄,然後執行下列命令以產生Eclipse專案:

    mvn eclipse:eclipse

  3. 開啟Eclipse工具並執行下列動作以匯入Eclipse專案:

    1. 選擇「檔案>匯入>現有專案」至Workspace

    2. 瀏覽並選擇執行archetype:generate命令的資料夾。

    3. 按一下​完成

      eclipse-screption

  4. 選擇要用於自訂外觀的介面工具集。 此範例使用下列數值步進器Widget:

    https://www.jqueryscript.net/form/User-Friendly-Number-Input-Spinner-with-jQuery-Bootstrap.html

    在Eclipse專案中,請檢閱plugin.js檔案中的外掛程式碼,以確保它符合外觀的要求。 在此示例中,外觀滿足以下要求:

    • 數字步進器應從- $.xfaWidget.numericInput擴展。

    • 介面工具集的set value方法會在焦點位於欄位後設定值。 這是最適化表單Widget的必備要求。

    • render方法需要被覆寫,才能調用bootstrapNumber方法。

    • 除了外掛程式的主要原始碼外,外掛程式沒有其他相依性。

    • 範例不會在步進器上執行任何樣式,因此不需要額外的CSS。

    • $userControl物件應可用於render方法。 它是text類型的欄位,使用插件代碼克隆。

    • 在禁用欄位時,+​和​-​按鈕應禁用。

  5. bootstrap-number-input.js(jQuery plugin)的內容取代為numericStepper-plugin.js檔案的內容。

  6. numericStepper-widget.js檔案中,新增下列程式碼以覆寫演算方法以叫用外掛程式並傳回$userControl物件:

    render : function() {
         var control = $.xfaWidget.numericInput.prototype.render.apply(this, arguments);
         var $control = $(control);
         var controlObject;
         try{
             if($control){
             $control.bootstrapNumber();
             var id = $control.attr("id");
             controlObject = $("#"+id);
             }
         }catch (exc){
              console.log(exc);
         }
         return controlObject;
    }
    
  7. numericStepper-widget.js檔案中,覆寫getOptionsMap屬性以覆寫存取選項,並隱藏停用模式中的+和——按鈕。

    getOptionsMap: function(){
        var parentOptionsMap = $.xfaWidget.numericInput.prototype.getOptionsMap.apply(this,arguments),
    
        newMap = $.extend({},parentOptionsMap,
    
         {
    
               "access": function(val) {
               switch(val) {
                  case "open" :
                    this.$userControl.removeAttr("readOnly");
                    this.$userControl.removeAttr("aria-readonly");
                    this.$userControl.removeAttr("disabled");
                    this.$userControl.removeAttr("aria-disabled");
                    this.$userControl.parent().find(".input-group-btn button").prop('disabled',false);
                    break;
                  case "nonInteractive" :
                  case "protected" :
                    this.$userControl.attr("disabled", "disabled");
                    this.$userControl.attr("aria-disabled", "true");
                    this.$userControl.parent().find(".input-group-btn button").prop('disabled',true);
                    break;
                 case "readOnly" :
                    this.$userControl.attr("readOnly", "readOnly");
                    this.$userControl.attr("aria-readonly", "true");
                    this.$userControl.parent().find(".input-group-btn button").prop('disabled',true);
                    break;
                default :
                    this.$userControl.removeAttr("disabled");
                    this.$userControl.removeAttr("aria-disabled");
                    this.$userControl.parent().find(".input-group-btn button").prop('disabled',false);
                    break;
              }
           },
       });
       return newMap;
     }
    
  8. 保存更改,導航到包含pom.xml檔案的資料夾,然後執行以下Maven命令來生成項目:

    mvn clean install

  9. 使用AEM Package Manager安裝套件。

  10. 在編輯模式中開啟您要套用自訂外觀的最適化表單,並執行下列動作:

    1. 按一下右鍵要應用外觀的欄位,然後按一下​Edit​開啟「編輯元件」對話框。

    2. 在「樣式」標籤中,更新​CSS類別​屬性以新增widget_numericStepper

您剛建立的新外觀現在可供使用。

本頁內容

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now