カスタム関数の開発と使用の例

この記事では、コアコンポーネントに基づくアダプティブフォームのカスタム関数の詳細な例を示し、様々なシナリオでの効果的な実装に関する貴重なインサイトを提供します。 カスタム関数は、AEM Formsのルールエディターで使用されます。これにより、開発者は、フォームの動作を制御するロジックを定義および制御できます。
この記事では、カスタム関数の様々な実装について説明し、特定の要件に合わせてフォームをカスタマイズし、全体的な機能を強化する方法を示します。

カスタム関数を使用したドロップダウンリストのオプションへの入力

コアコンポーネントのルールエディターは、実行時にドロップダウンリストのオプションに動的に値を入力する オプションを設定 プロパティをサポートしていません。 ただし、カスタム関数を使用してドロップダウンリストのオプションに値を入力することにより、特定のロジックに基づいてオプションを取得できます。 カスタム関数を使用すると、ドロップダウンオプションの入力方法とタイミングをより柔軟に制御でき、ユーザーエクスペリエンスが向上します。

カスタム関数を使用してドロップダウンリストのオプションに値を入力するには、「create-custom-function」セクションで説明されているように、次のコードを追加します。

    /**
    * @name setEnums
    * @returns {string[]}
    **/
    function setEnums() {
    return ["0","1","2","3","4","5","6"];
    }

    /**
    * @name setEnumNames
    * @returns {string[]}
    **/
    function setEnumNames() {
    return ["Sunday","Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
    }

上記のコードでは、setEnums を使用して enum プロパティを設定し、setEnumNames を使用してドロップダウンの enumNames プロパティを設定しています。

ユーザーが「Next」ボタンをクリックしたときにドロップダウンリストの値オプションを設定する「Next」ボタン用のルールを作成してみましょう。

「表示」ボタンをクリックしたときにドロップダウンリストのオプションが設定される場所を示すには、次の図を参照してください。

SetProperty ルールを使用したパネルの表示

カスタム関数でフィールドおよびグローバルオブジェクトを使用する方法を、Contact Us フォームを使用して説明します。

create-custom-function の節で説明したように、カスタム関数に次のコードを追加して、フォームフィールドを Required として設定します。

    /**
    * enablePanel
    * @name enablePanel
    * @param {object} field1
    * @param {object} field2
    * @param {scope} globals
    */

    function enablePanel(field1,field2, globals)
    {
       if(globals.functions.validate(field1).length === 0)
       {
       globals.functions.setProperty(field2, {visible: true});
       }
    }

この例では、ボタンをクリックすると personaldetails パネルの検証が行われます。 パネルでエラーが検出されない場合は、ボタンをクリックすると、feedback のパネルが表示されます。

Next ボタンのルールを作成してみましょう。このルールは、personaldetails パネルを検証し、ユーザーが Next ボタンをクリックすると feedback パネルが表示されるようにします。

「Next」ボタンをクリックしたときに personaldetails パネルが検証される場所を示すには、以下の図を参照してください。 personaldetails ージ内のすべてのフィールドが検証されると、feedback のパネルが表示されます。

personaldetails パネルのフィールドにエラーがある場合、エラーは「Next」ボタンをクリックするとフィールドレベルに表示され、feedback パネルは非表示のままになります。

フィールドを検証

カスタム関数がフィールドオブジェクトとグローバルオブジェクトを使用して、Contact Us フォームを使用してフィールドを検証する方法を説明します。

create-custom-function の節で説明したように、カスタム関数に次のコードを追加して、フィールドを検証します。

    /**
    * validateField
    * @name validateField
    * @param {object} field
    * @param {scope} globals
    */
    function validateField(field,globals)
    {

        globals.functions.validate(field);

    }

この例では、「contact」フィールドにカスタムの検証パターンが適用されます。 ユーザーは、10 で始まり、その後 8 桁が続く電話番号を入力する必要があります。 ユーザーが 10 で始まらない電話番号や、8 桁以下の電話番号を入力した場合、ボタンをクリックすると検証エラーメッセージが表示されます。

次の手順では、ボタンクリック時に contact フィールドを検証する Next ボタンのルールを作成します。

次の図を参照して、ユーザーが 10 で始まらない電話番号を入力した場合、フィールドレベルにエラーメッセージが表示されることを示してください。

ユーザーが有効な電話番号を入力し、personaldetails ントロールパネル内のすべてのフィールドが検証されると、feedback ントロールパネルが画面に表示されます。

パネルのリセット

カスタム関数がフィールドとグローバルオブジェクトを使用して、Contact Us フォームを使用してフィールドをリセットする方法を説明します。

create-custom-function の節で説明したように、カスタム関数に次のコードを追加して、パネルをリセットします。

    /**
    * resetField
    * @name  resetField
    * @param {string} input1
    * @param {object} field
    * @param {scope} globals
    */
    function  resetField(field,globals)
    {

        globals.functions.reset(field);

    }

この例では、「Clear」ボタンをクリックすると、personaldetails パネルがリセットされます。 次の手順では、ボタンクリック時にパネルをリセットする Clear ボタンのルールを作成します。

ユーザーが「clear」ボタンをクリックすると、personaldetails パネルがリセットされることを示す次の図を参照してください。

フィールドレベルでカスタムメッセージを表示し、フィールドを無効としてマークするには

カスタム関数で、フィールドとグローバルオブジェクトを使用して、フィールドレベルでカスタムメッセージを表示し、Contact Us フォームを使用してフィールドを無効としてマークする方法を説明します。

markFieldAsInvalid() 関数を使用して、フィールドを無効として定義し、フィールドレベルでカスタムのエラーメッセージを設定できます。 fieldIdentifier の値は、fieldId、field qualifiedName、field dataRef のいずれかです。 option という名前のオブジェクトの値は、{useId: true}、{useQualifiedName: true}、{useDataRef: true} のいずれかです。
フィールドを無効としてマークし、カスタムメッセージを設定するために使用される構文は次のとおりです。

create-custom-function の節で説明したように、カスタム関数に次のコードを追加して、フィールドレベルでカスタムメッセージを有効にします。

    /**
    * customMessage
    * @name customMessage
    * @param {object} field
    * @param {scope} globals
    */
    function customMessage(field, globals) {
    const minLength = 15;
    const comments = field.$value.trim();
    if (comments.length < minLength) {
        globals.functions.markFieldAsInvalid(field.$id, "Comments must be at least 15 characters long.", { useId: true });
    }
}

この例では、ユーザーがコメント テキストボックスに 15 文字未満で入力すると、カスタムメッセージがフィールドレベルに表示されます。

次に、comments フィールドのルールを作成します。

comments のフィールドに負のフィードバックを入力すると、フィールドレベルでのカスタムメッセージの表示がトリガーされることを示す、以下のデモを参照してください。

ユーザーが「コメント」テキストボックスに 15 文字を超えて入力すると、フィールドが検証され、フォームが送信されます。

変更したデータをサーバーに送信

カスタム関数がフィールドとグローバルオブジェクトを使用して、Contact Us フォームを使用してサーバーで操作データを送信する方法を説明します。

次のコード行：
globals.functions.submitForm(globals.functions.exportData(), false); は、操作後にフォームデータを送信するために使用されます。

create-custom-function の節で説明したように、カスタム関数に次のコードを追加して、操作されたデータをサーバーで送信します。

    /**
    * submitData
    * @name submitData
    * @param {object} field
    * @param {scope} globals
    */
    function submitData(globals)
    {

    var data = globals.functions.exportData();
    if(!data.comments) {
    data.comments = 'NA';
    }
    console.log('After update:{}',data);
    globals.functions.submitForm(data, false);
    }

この例では、ユーザーが comments テキストボックスを空のままにした場合、NA ータはフォームの送信時にサーバーに送信されます。

次に、データを送信する Submit ボタンのルールを作成します。

ユーザーが comments テキストボックスを空のままにした場合、NA の値がサーバーで送信されることを示すには、以下の console window の図を参照してください。

また、コンソールウィンドウを調べて、サーバーに送信されたデータを表示することもできます。

フォーム送信の成功およびエラーハンドラーのオーバーライド

カスタム関数でフィールドおよびグローバルオブジェクトを使用して、Contact Us フォームを利用して送信ハンドラーを上書きする方法を説明します。

create-custom-functionas の節で説明したように、次のコード行を追加して、フォーム送信の送信メッセージまたは失敗メッセージをカスタマイズし、フォーム送信メッセージをモーダルボックスに表示します。

/**
 * Handles the success response after a form submission.
 *
 * @param {scope} globals - This object contains a read-only form instance, target field instance, triggered event, and methods for performing form modifications within custom functions.
 * @returns {void}
 */
function customSubmitSuccessHandler(globals) {
    var event = globals.event;
    var submitSuccessResponse = event.payload.body;
    var form = globals.form;

    if (submitSuccessResponse) {
        if (submitSuccessResponse.redirectUrl) {
            window.location.href = encodeURI(submitSuccessResponse.redirectUrl);
        } else if (submitSuccessResponse.thankYouMessage) {
            showModal("success", submitSuccessResponse.thankYouMessage);
        }
    }
}

/**
 * Handles the error response after a form submission.
 *
 * @param {string} customSubmitErrorMessage - The custom error message.
 * @param {scope} globals - This object contains a read-only form instance, target field instance, triggered event, and methods for performing form modifications within custom functions.
 * @returns {void}
 */
function customSubmitErrorHandler(customSubmitErrorMessage, globals) {
    showModal("error", customSubmitErrorMessage);
}
function showModal(type, message) {
    // Remove any existing modals
    var existingModal = document.getElementById("modal");
    if (existingModal) {
        existingModal.remove();
    }

    // Create the modal dialog
    var modal = document.createElement("div");
    modal.setAttribute("id", "modal");
    modal.setAttribute("class", "modal");

    // Create the modal content
    var modalContent = document.createElement("div");
    modalContent.setAttribute("class", "modal-content");

    // Create the modal header
    var modalHeader = document.createElement("div");
    modalHeader.setAttribute("class", "modal-header");
    modalHeader.innerHTML = "<h2>" + (type === "success" ? "Thank You" : "Error") + "</h2>";

    // Create the modal body
    var modalBody = document.createElement("div");
    modalBody.setAttribute("class", "modal-body");
    modalBody.innerHTML = "<p class='" + type + "-message'>" + message + "</p>";

    // Create the modal footer
    var modalFooter = document.createElement("div");
    modalFooter.setAttribute("class", "modal-footer");

    // Create the close button
    var closeButton = document.createElement("button");
    closeButton.setAttribute("class", "close-button");
    closeButton.innerHTML = "Close";
    closeButton.onclick = function() {
        modal.remove();
    };

    // Append the elements to the modal content
    modalFooter.appendChild(closeButton);
    modalContent.appendChild(modalHeader);
    modalContent.appendChild(modalBody);
    modalContent.appendChild(modalFooter);

    // Append the modal content to the modal
    modal.appendChild(modalContent);

    // Append the modal to the document body
    document.body.appendChild(modal);
}

この例では、ユーザーが customSubmitSuccessHandler 関数および customSubmitErrorHandler のカスタム関数を使用する場合、成功メッセージと失敗メッセージがモーダルに表示されます。 JavaScript関数 showModal(type, message) は、モーダルダイアログボックスを動的に作成して画面に表示するために使用されます。

次に、フォーム送信が成功するためのルールを作成します。

フォームが正常に送信されると成功メッセージがモーダルに表示されることを示すには、以下の図を参照してください。

同様に、失敗したフォーム送信に対するルールを作成します。

フォームの送信に失敗したときにエラーメッセージがモーダルに表示されることを示すには、次の図を参照してください。

フォーム送信の成功と失敗をデフォルトの方法で表示するには、Default submit Form Success Handler 関数と Default submit Form Error Handler 関数を標準で使用できます。

既存のAEM プロジェクトまたはフォームでカスタム送信ハンドラーが期待どおりに実行されない場合は、 トラブルシューティングの節を参照してください。

繰り返し可能なパネルの特定のインスタンスでのアクションの実行

繰り返し可能なパネル上でビジュアルルールエディターを使用して作成されたルールは、繰り返し可能なパネルの最後のインスタンスに適用されます。 繰り返し可能なパネルの特定のインスタンスに対するルールを作成するには、カスタム関数を使用します。

目的地に向かう旅行者に関する情報を収集するた Booking Form に、別のフォームを作成しましょう。 旅行者パネルは、繰り返し可能なパネルとして追加され、ユーザーは「Add Traveler」ボタンを使用して 5 人の旅行者の詳細を追加できます。

create-custom-function の節で説明したように、次のコード行を追加して、最後のコード行以外の繰り返し可能なパネルの特定のインスタンスでアクションを実行します。

/**
* @name hidePanelInRepeatablePanel
* @param {scope} globals
*/
function hidePanelInRepeatablePanel(globals)
{
    var repeatablePanel = globals.form.travelerinfo;
    // hides a panel inside second instance of repeatable panel
    globals.functions.setProperty(repeatablePanel[1].traveler, {visible : false});
}

この例では、hidePanelInRepeatablePanel カスタム関数が繰り返し可能なパネルの特定のインスタンスでアクションを実行します。 上記コードの場合、travelerinfo は繰り返し可能なパネルを表します。 repeatablePanel[1].traveler, {visible: false} のコードは、繰り返し可能なパネルの 2 番目のインスタンスでパネルを非表示にします。

Hide というラベルの付いたボタンを追加し、繰り返し可能なパネルの 2 つ目のインスタンスを非表示にするルールを追加します。

次のビデオを参照して、Hide をクリックすると、2 番目の繰り返し可能インスタンス内のパネルが非表示になることを示します。

フォームの読み込み時に値をフィールドに事前入力

カスタム関数で、フィールドとグローバルオブジェクトを使用して、フ Booking Form ームを利用してフィールドに事前入力する方法を説明します。

create-custom-function の節で説明したように、次のコード行を追加して、フォームの初期化時にフィールドに事前入力された値を読み込みます。

/**
 * Tests import data
 * @name testImportData
 * @param {scope} globals
 */
function testImportData(globals)
{
    globals.functions.importData(Object.fromEntries([['amount','10000']]));
}

上記のコードでは、フォームの読み込み時に、testImportData 関数が「Booking Amount」テキストフィールドの前に値を設定します。 予約フォームで、最小予約金額を 10,000 定する必要があるとします。

次に、フォームの初期化時に、フォームの読み込み時に「Booking Amount」テキストフィールドの値に、指定した値が事前入力されるルールを作成します。

以下のスクリーンショットを参照してください。これは、フォームの読み込み時に、Booking Amount テキストボックスの値が指定した値で事前入力されることを示しています。

特定のフィールドにフォーカスを設定する

カスタム関数で field オブジェクトと global オブジェクトを使用して、Booking Form を利用して特定のフィールドにフォーカスを設定する方法を説明します。

create-custom-function の節で説明しているように、次のコード行を追加して、「Submit」ボタンがクリックされたときに指定されたフィールドにフォーカスを設定します。

/**
 * @name testSetFocus
 * @param {object} emailField
 * @param {scope} globals
 */
    function testSetFocus(field, globals)
    {
        globals.functions.setFocus(field);
    }

Submit ボタンにルールを追加して、Email ID のテキストボックスがクリックされたときにフィールドにフォーカスを設定します。

Submit ボタンがクリックされると、Email ID のフィールドにフォーカスが設定されることを示す、以下のスクリーンショットを参照してください。

dispatchEvent プロパティを使用した繰り返し可能なパネルの追加または削除

カスタム関数で、フィールドおよびグローバルオブジェクトを使用して、dispatchEvent プロパティを利用し繰り返し可能なパネルを追加または削除する方法を Booking Form で説明します。

create-custom-function の節で説明しているように、dispatchEvent プロパティを使用して「Add Traveler」ボタンがクリックされたときにパネルを追加するコードの行を追加します。

/**
 * Tests add instance with dispatchEvent
 * @name testAddInstance
 * @param {scope} globals
 */
function testAddInstance(globals)
{
    var repeatablePanel = globals.form.traveler;
    globals.functions.dispatchEvent(repeatablePanel,'addInstance');
}

Add Traveler ボタンにルールを追加して、繰り返し可能なパネルをクリックして追加します。

下の gif を参照してください。これは、「Add Traveler」ボタンがクリックされると、dispatchEvent プロパティを使用してパネルが追加されることを示しています。

同様に、「create-custom-function」の節で説明しているように、dispatchEvent プロパティを使用して Delete Traveler ボタンがクリックされたときにパネルを削除するコード行を追加します。

/**

 * @name testRemoveInstance
 * @param {scope} globals
 */
function testRemoveInstance(globals)
{
    var repeatablePanel = globals.form.traveler;
    globals.functions.dispatchEvent(repeatablePanel, 'removeInstance');
}

繰り返し可能なパネルをクリックして削除するルールを「Delete Traveler」ボタンに追加しましょう。

下の gif を参照してください。これは、「Delete Traveler」ボタンがクリックされると、dispatchEvent プロパティを使用してトラベラーパネルが削除されることを示しています。

トラブルシューティング

関連トピック