建立最適化Forms的自訂提交動作 writing-custom-submit-action-for-adaptive-forms

版本
文章連結
AEM 6.5
按一下這裡
AEM as a Cloud Service
本文章

最適化表單提供多個立即可用的提交動作(OOTB)。 提交動作可指定要透過最適化表單收集之資料上執行的動作細節。 例如,以電子郵件傳送資料。

您可以建立自訂提交動作,以新增現成可用的提交動作中未包含或不支援的功能(透過單一OOTB提交動作)。 例如,將資料提交至工作流程、將資料儲存在資料存放區、傳送電子郵件通知給提交表單的人員,以及透過單一提交動作傳送電子郵件給負責處理已提交表單以供核准和拒絕的人員。

XML資料格式 xml-data-format

使用​ jcr:data ​要求引數將XML資料傳送至servlet。 提交動作可以存取引數以處理資料。 下列程式碼說明XML資料的格式。 與表單模型繫結的欄位會顯示在​ afBoundData ​區段中。 未繫結的欄位會出現在afUnoundData區段中。

<?xml ?>
<afData>
<afUnboundData>
<data>
<field1>value</field2>
<repeatablePanel>
    <field2>value</field2>
</repeatablePanel>
<repeatablePanel>
    <field2>value</field2>
</repeatablePanel>
</data>
</afUnboundData>
<afBoundData>
<!-- xml corresponding to the Form Model /XML Schema -->
</afBoundData>
</afData>

動作欄位 action-fields

提交動作可以將隱藏的輸入欄位(使用HTMLinput標籤)新增到演算後的表單HTML。 這些隱藏欄位可包含處理表單提交時所需的值。 提交表單時,這些欄位值會傳回為請求引數,「提交動作」可在提交處理期間使用這些引數。 輸入欄位稱為動作欄位。

例如,同時擷取填寫表單所用時間的提交動作可以新增隱藏的輸入欄位startTimeendTime

指令碼可在表單轉譯時及表單提交前分別提供startTimeendTime欄位的值。 提交動作指令碼post.jsp可以使用要求引數存取這些欄位,並計算填寫表單所需的總時間。

檔案附件 file-attachments

「提交動作」也可以使用您使用「檔案附件」元件上載的檔案附件。 提交動作指令碼可以使用Sling RequestParameter API存取這些檔案。 API的isFormField方法可協助識別要求引數是檔案或表單欄位。 您可以在「送出動作」中反複執行「要求」引數,以識別檔案附件引數。

下列範常式式碼會識別請求中的檔案附件。 接著,它會使用取得API將資料讀入檔案中。 最後,它會使用資料建立Document物件,並將其附加至清單。

RequestParameterMap requestParameterMap = slingRequest.getRequestParameterMap();
for (Map.Entry<String, RequestParameter[]> param : requestParameterMap.entrySet()) {
    RequestParameter rpm = param.getValue()[0];
    if(!rpm.isFormField()) {
        fileAttachments.add(new Document(rpm.get()));
    }
}

將檔案附加至最適化表單時,伺服器會在最適化表單提交後驗證檔案附件,並在下列情況下傳回錯誤訊息:

  • 檔案附件包含以(.)開頭的檔案名稱 字元,包含\ / : * ? 「 < > | ; % $$個字元,或包含保留給Windows作業系統的特殊檔案名稱,例如nulprnconlptcom

  • 檔案附件的大小為0位元組。

  • 在調適型表單中設定檔案附件元件時,支援的檔案型別區段中未定義檔案附件的格式。

轉寄路徑和重新導向URL forward-path-and-redirect-url

執行必要的動作後,提交servlet會將請求轉送至轉送路徑。 動作會使用setForwardPath API在指南提交servlet中設定轉寄路徑。

如果動作未提供轉寄路徑,則提交servlet會使用重新導向URL重新導向瀏覽器。 作者會使用「最適化表單編輯」對話方塊中的「感謝頁面」設定,來設定重新導向URL。 您也可以透過提交動作或指南提交servlet中的setRedirectUrl API來設定重新導向URL。 您也可以使用指南提交servlet中的setRedirectParameters API,設定傳送至重新導向URL的要求引數。

NOTE
作者會提供重新導向URL (使用感謝頁面設定)。 OOTB提交動作使用重新導向URL,從轉送路徑參照的資源重新導向瀏覽器。
您可以撰寫自訂提交動作,將請求轉送至資源或servlet。 Adobe建議在處理完成時,為轉送路徑執行資源處理的指令碼會將要求重新導向至重新導向URL。

提交動作 submit-action

提交動作是sling:Folder,包含下列專案:

  • addfields.jsp:此指令碼提供在轉譯期間新增到HTML檔案中的動作欄位。 使用此指令碼,在post.post.jsp.jsp指令碼中新增提交期間所需的隱藏POST引數。

  • dialog.xml:此指令碼類似於CQ元件對話方塊。 它提供作者自訂的設定資訊。 當您選取提交動作時,欄位會顯示在「最適化表單編輯」對話方塊的「提交動作」索引標籤中。

  • post.servlet.jsp:「提交」Servlet會呼叫此指令碼,其中包含您提交的資料以及先前章節中的其他資料。POST 在此頁面中只要提到要執行動作,就表示要執行post.post.jspPOST檔。 若要向最適化Forms註冊提交動作以顯示於最適化表單編輯對話方塊中,請將這些屬性新增到sling:Folder

    • guideComponentType,型別為String,值為​ fd/af/components/guidesubmittype

    • guideDataModel,型別為String,指定適用提交動作的最適化表單型別。 以XSD為基礎的最適化Forms支援​xsd。 不使用XDP或XSD的最適化Forms支援​ basic。 若要顯示多種最適化Forms型別的動作,請新增對應的字串。 以逗號分隔每個字串。 例如,若要讓動作顯示在XSD式Adaptive Forms上,請指定值為 xsd

    • jcr:description ​屬於字串型別。 此屬性的值會顯示在「最適化表單編輯」對話方塊之「提交動作」索引標籤的「提交動作」清單中。 OOTB動作存在於CRX存放庫中​ /libs/fd/af/components/guidessubmittype ​位置。

    • submitService (型別為String)。 如需詳細資訊,請參閱排程自訂動作的最適化表單提交

建立自訂提交動作 creating-a-custom-submit-action

執行以下步驟來建立自訂提交動作,將資料儲存至CRX存放庫,然後傳送電子郵件給您。 最適化表單包含OOTB提交動作存放區內容(已棄用),可將資料儲存至CRX存放庫。 此外,AEM還提供可用於傳送電子郵件的郵件 API。 使用Mail API之前,請透過系統主控台設定Day CQ Mail服務。 您可以重複使用「儲存內容(已棄用)」動作,將資料儲存在存放庫中。 存放區內容(已棄用)動作可在CRX存放庫中的/libs/fd/af/components/guidessubmittype/store位置取得。

  1. 在URL https://<server>:<port>/crx/de/index.jsp登入CRXDE Lite。 在/apps/custom_submit_action資料夾中建立具有sling:Folder屬性並命名為store_and_mail的節點。 建立custom_submit_action資料夾(如果尚未存在)。

    描述使用屬性sling:Folder 建立節點的熒幕擷圖

  2. 提供必要設定欄位。

    新增存放區動作所需的設定。 將存放區動作的​ cq:dialog ​節點從/libs/fd/af/components/guidesubmittype/store複製到/apps/custom_submit_action/store_and_email的動作資料夾。

    熒幕擷圖顯示對話方塊節點複製到動作資料夾

  3. 提供設定欄位,以提示作者設定電子郵件。

    最適化表單還提供電子郵件動作,可向使用者傳送電子郵件。 根據您的需求自訂此動作。 導覽至/libs/fd/af/components/guidessubmittype/email/dialog。 將cq:dialog節點內的節點複製到提交動作(https://experienceleague.adobe.com/apps/custom_submit_action/store_and_email/dialog?lang=zh-Hant)的cq:dialog節點。

    自訂電子郵件動作

  4. 讓動作可在最適化表單編輯對話方塊中使用。

    在store_and_email節點中新增下列屬性:

    • guideComponentType,型別為​ String,值為​ fd/af/components/guidesubmittype

    • guideDataModel,型別為​ 字串,值為​ xsd,基本

    • jcr:description,型別為​ String,值為​ 存放區與電子郵件動作

    • submitService (型別為​ String)和值​ Store and Email。 如需詳細資訊,請參閱排程自訂動作的最適化表單提交

  5. 開啟任何最適化表單。 按一下​ 開始 ​旁的​ 編輯 ​按鈕,開啟最適化表單容器的​ 編輯 ​對話方塊。 新動作會顯示在​ 提交動作 ​索引標籤中。 選取​ 存放區和電子郵件動作 ​會顯示對話方塊節點中新增的組態。

    提交動作設定對話方塊

  6. 使用此動作完成工作。

    將post.jsp.jspPOST碼新增至您的動作。 (https://experienceleague.adobe.com/apps/custom_submit_action/store_and_mail/?lang=zh-Hant)。

    執行OOTB存放區動作(post.javaScript.jspPOST碼)。 使用CQ在程式碼中提供的FormsHelper.runAction(java.lang.String, java.lang.String, org.apache.sling.api.resource.Resource, org.apache.sling.api.SlingHttpServletRequest, org.apache.sling.api.SlingHttpServletResponse) API來執行存放區動作。 在JSP檔案中新增下列程式碼:

    FormsHelper.runAction("/libs/fd/af/components/guidesubmittype/store", "post", resource, slingRequest, slingResponse);

    若要傳送電子郵件,程式碼會從設定中讀取收件者的電子郵件地址。 若要在動作的指令碼中擷取設定值,請使用下列程式碼讀取目前資源的屬性。 同樣地,您可以讀取其他組態檔。

    ValueMap properties = ResourceUtil.getValueMap(resource);

    String mailTo = properties.get("mailTo");

    最後,使用CQ Mail API傳送電子郵件。 使用SimpleEmail類別來建立電子郵件物件,如下所示:

    note note
    NOTE
    確定JSP檔案的名稱為post.postPOST.jsp。
    code language-java
    <%@include file="/libs/fd/af/components/guidesglobal.jsp" %>
    <%@page import="com.day.cq.wcm.foundation.forms.FormsHelper,
           org.apache.sling.api.resource.ResourceUtil,
           org.apache.sling.api.resource.ValueMap,
                    com.day.cq.mailer.MessageGatewayService,
      com.day.cq.mailer.MessageGateway,
      org.apache.commons.mail.Email,
                    org.apache.commons.mail.SimpleEmail" %>
    <%@taglib prefix="sling"
                    uri="https://sling.apache.org/taglibs/sling/1.0" %>
    <%@taglib prefix="cq"
                    uri="https://www.day.com/taglibs/cq/1.0"
    %>
    <cq:defineObjects/>
    <sling:defineObjects/>
    <%
            String storeContent =
                        "/libs/fd/af/components/guidesubmittype/store";
            FormsHelper.runAction(storeContent, "post", resource,
                                    slingRequest, slingResponse);
     ValueMap props = ResourceUtil.getValueMap(resource);
     Email email = new SimpleEmail();
     String[] mailTo = props.get("mailto", new String[0]);
     email.setFrom((String)props.get("from"));
            for (String toAddr : mailTo) {
                email.addTo(toAddr);
       }
     email.setMsg((String)props.get("template"));
     email.setSubject((String)props.get("subject"));
     MessageGatewayService messageGatewayService =
                        sling.getService(MessageGatewayService.class);
     MessageGateway messageGateway =
                    messageGatewayService.getGateway(SimpleEmail.class);
     messageGateway.send(email);
    %>
    

    選取最適化表單中的動作。 動作會傳送電子郵件並儲存資料。

使用自訂提交動作的submitService屬性 submitservice-property

當您設定包含submitService屬性的自訂提交動作時,表單會在提交時觸發FormSubmitActionServiceFormSubmitActionService使用getServiceName方法來擷取submitService屬性的值。 服務會根據submitService屬性的值,叫用適當的送出方法。 將FormSubmitActionService加入您上傳至AEM Forms伺服器的自訂套件組合。

將字串型別的submitService屬性新增至自訂提交動作的sling:Folder,以啟用最適化表單的Adobe Sign。 只有在設定自訂提交動作的submitService屬性值之後,才能在Adaptive Form容器屬性的​ 電子簽章 ​區段中選取​ 啟用Adobe Sign ​選項。

送出服務屬性

recommendation-more-help
fbcff2a9-b6fe-4574-b04a-21e75df764ab