アダプティブ Forms コアコンポーネントのカスタム関数

この記事では、次のような最新の機能を備えた、最新のアダプティブフォームのコアコンポーネントを使用してカスタム関数を作成する方法について説明します。

カスタム関数の最新機能を使用するには、AEM Forms コアコンポーネント環境で 最新のフォームバージョンを設定してください。

はじめに

AEM Forms 6.5 には、ルールエディターを使用して複雑なビジネスルールを定義できるJavaScript関数が含まれています。 AEM Formsは様々な標準のカスタム関数を提供していますが、多くの場合、複数のフォームで使用するために独自のカスタム関数を定義する必要があります。 これらのカスタム関数は、入力されたデータを特定の要件に合わせて操作および処理できるようにすることで、フォームの機能を強化します。 さらに、定義済みの条件に基づいてフォームの動作を動的に変更できます。

カスタム関数の使用 uses-of-custom-function

アダプティブなForms コアコンポーネントでカスタム関数を使用する場合の利点は次のとおりです。

カスタム関数は基本的に、JavaScript ファイルに追加されるクライアントライブラリです。 カスタム関数を作成すると、ルールエディターで使用できるようになり、アダプティブフォーム内のユーザーが選択できるようになります。 カスタム関数は、ルールエディターのJavaScript アノテーションによって識別されます。

カスタム関数でサポートされるJavaScript注釈 js-annotations

JavaScript注釈は、JavaScript コード のメタデータを提供します。 /** や @ など、特定の記号で始まるコメントが含まれます。 注釈は、コード内の関数、変数、その他の要素に関する重要な情報を提供します。 アダプティブフォームは、カスタム関数に対して次のJavaScript注釈をサポートしています。

名前

Name は、アダプティブフォームのルールエディターでカスタム関数を識別するために使用します。 カスタム関数の名前には、次の構文を使用します。

パラメーター

パラメーター は、カスタム関数で使用される引数のリストです。 1 つの関数は、複数のパラメーターをサポートできます。 次の構文を使用して、カスタム関数でパラメーターを定義します。

パラメータータイプは 大文字と小文字は区別されません で、パラメーター名にはスペースを使用できません。

パラメ <Parameter Description> ターの目的に関する詳細が含まれています。 複数の単語を含めることができます。

戻り値タイプ

戻り値のタイプは、実行後にカスタム関数が返す値のタイプを指定します。 次の構文を使用して、カスタム関数で戻り値のタイプを定義します。

戻り値のタイプでは、大文字と小文字が区別されません。

非公開

プライベートとして宣言されたカスタム関数は、アダプティブフォームのルールエディターのカスタム関数のリストには表示されません。 デフォルトでは、カスタム関数はパブリックです。 カスタム関数をプライベートとして宣言する構文は @private です。

カスタム関数の作成時のガイドライン considerations

ルールエディターにカスタム関数を一覧表示するには、次のいずれかの形式を使用できます。

Jsdoc コメント付きまたは付きでない Function ステートメント

カスタム関数を作成する際に、jsdoc コメントを含めることも、含めないこともできます。

    function functionName(parameters)
        {
            // code to be executed
        }

ユーザーがカスタム関数にJavaScript アノテーションを追加しない場合は、関数名によってルールエディターに表示されます。 ただし、カスタム関数を読みやすくするために、JavaScript アノテーションを含めることをお勧めします。

必須のJavaScript注釈またはコメントを含む矢印関数

矢印関数の構文を使用して、カスタム関数を作成できます。

    /**
    * test function
    * @name testFunction
    * @param {string} a parameter description
    * @param {string=} b parameter description
    * @return {string}
    */
    testFunction = (a, b) => {
    return a + b;
    };
    /** */
    testFunction1=(a) => (return a)
    /** */
    testFunction2 = a => a + 100;

ユーザーがカスタム関数にJavaScript注釈を追加しない場合、カスタム関数はアダプティブフォームのルールエディターに表示されません。

必須のJavaScript注釈またはコメントを含む関数式

アダプティブフォームのルールエディターにカスタム関数をリストするには、次の形式でカスタム関数を作成します。

    /**
    * test function
    * @name testFunction
    * @param {string} input1 parameter description
    * @param {string=} input2 parameter description
    * @return {string}
    */
    testFunction = function(input1,input2)
        {
            // code to be executed
        }

ユーザーがカスタム関数にJavaScript注釈を追加しない場合、カスタム関数はアダプティブフォームのルールエディターに表示されません。

カスタム関数を作成するための前提条件

アダプティブFormsへのカスタム機能の追加を開始する前に、お使いのマシンに次のソフトウェアがインストールされていることを確認してください。

カスタム関数の作成 create-custom-function

カスタム関数の作成手順は次のとおりです。

AEM プロジェクトアーキタイプを使用したクライアントライブラリの作成 create-client-library-archetype

AEM プロジェクトアーキタイプを使用して作成したプロジェクトにクライアントライブラリを追加することで、カスタム関数を追加できます。
既存のプロジェクトがある場合 、ローカルプロジェクトに カスタム関数を直接追加できます。

アーキタイププロジェクトを作成するか既存のプロジェクトを使用したら、クライアントライブラリを作成します。 クライアントライブラリを作成するには、次の手順を実行します。

クライアントライブラリフォルダーの追加

[AEM プロジェクトディレクトリ ] に新しいクライアントライブラリフォルダーを追加するには、次の手順に従います。

クライアントライブラリフォルダーへのファイルとフォルダーの追加

追加したクライアントライブラリフォルダーに次の内容を追加します。

Location is: [AEMaaCS project directory]/ui.apps/src/main/content/jcr_root/apps/experience-league/customclientlibs/

新規フォルダーを filter.xml に含めます:

CRXDE を通じたカスタム関数の作成とデプロイ create-add-custom-function

最新のAEM FormsおよびForms アドオンを使用している場合は、CRXDE を通じてカスタム関数を作成し、カスタム関数の最新のアップデートを使用できます。 それには、次の手順を実行します。

次の カスタム関数フォルダーを参照できます。 このフォルダーをダウンロードしてAEM インスタンスにインストールします。

これで、クライアントライブラリを追加して、アダプティブフォームでカスタム関数を使用できるようになりました。

アダプティブフォームへのクライアントライブラリの追加 add-client-library

クライアントライブラリをAEM Forms環境にデプロイしたら、アダプティブフォームでその機能を使用します。 アダプティブフォームにクライアントライブラリを追加するには、次の手順に従います

これで、ルールエディターでカスタム関数を使用するルールを作成できます。

次に、AEM Forms 6.5 で ルールエディターの呼び出しサービスを使用してカスタム関数を設定および使用する方法を説明しす。

アダプティブフォームでのカスタム関数の使用 use-custom-functions

アダプティブフォームでは、 ルールエディター内のカスタム関数を使用できます。
JavaScriptのファイル（Function.js ファイル）に次のコードを追加して、生年月日（YYYY-MM-DD）に基づいて年齢を計算しましょう。 生年月日を入力として取得し、年齢を返すカスタム関数を calculateAge() として作成します。

    /**
        * Calculates Age
        * @name calculateAge
        * @param {object} field
        * @return {string}
    */

    function calculateAge(field) {
    var dob = new Date(field);
    var now = new Date();

    var age = now.getFullYear() - dob.getFullYear();
    var monthDiff = now.getMonth() - dob.getMonth();

    if (monthDiff < 0 || (monthDiff === 0 && now.getDate() < dob.getDate())) {
    age--;
    }

    return age;
    }

上記の例では、ユーザーが誕生日を（YYYY-MM-DD）形式で入力すると、カスタム関数 calculateAge が呼び出され、年齢が返されます。

フォームをプレビューして、ルールエディターを介してカスタム関数がどのように実装されているかを確認します。

カスタム関数での非同期関数のサポート support-of-async-functions

非同期カスタム関数がルールエディターリストに表示されない。 ただし、同期関数式を使用して作成されたカスタム関数内で、非同期関数を呼び出すことができます。

カスタム関数を使用して非同期関数を呼び出す方法については、以下のコードを参照してください。

    async function asyncFunction() {
    const response = await fetch('https://petstore.swagger.io/v2/store/inventory');
    const data = await response.json();
    return data;
    }

    /**
    * callAsyncFunction
    * @name callAsyncFunction callAsyncFunction
    */
    function callAsyncFunction() {
    asyncFunction()
        .then(responseData => {
        console.log('Response data:', responseData);
        })
        .catch(error => {
         console.error('Error:', error);
    });
}

上記の例では、asyncFunction 関数は asynchronous function です。 https://petstore.swagger.io/v2/store/inventory に対して GET リクエストを実行することで、非同期操作を実行します。 await を使用して応答を待ち、response.json() を使用して応答本文を JSON として解析し、データを返します。 callAsyncFunction 関数は、asyncFunction 関数を呼び出してコンソールに応答データを表示する同期カスタム関数です。 callAsyncFunction 関数は同期していますが、非同期の asyncFunction 関数を呼び出し、then 文と catch 文で結果を処理します。

動作を確認するには、ボタンを追加し、ボタンクリック時に非同期関数を呼び出すボタンのルールを作成します。

ユーザーが「Fetch」ボタンをクリックすると、カスタム関数 callAsyncFunction が呼び出され、非同期関数 asyncFunction が呼び出されることを示すには、以下のコンソールウィンドウの図を参照してください。 コンソールウィンドウをInspectして、ボタンがクリックされたときの応答を確認します。

カスタム関数の機能について説明します。

カスタム関数の様々な機能

カスタム関数を使用すると、パーソナライズされた機能をフォームに追加できます。 これらの関数は、特定フィールドの操作、グローバルフィールドの使用、キャッシュなど、様々な機能をサポートします。 この柔軟性により、組織の要件に応じてフォームをカスタマイズできます。

カスタム関数のフィールド オブジェクトとグローバル スコープ オブジェクト support-field-and-global-objects

フィールドオブジェクトとは、テキストフィールド、チェックボックスなど、フォーム内の個々のコンポーネントまたは要素を指します。 Globals オブジェクトには、フォームインスタンス、ターゲットフィールドインスタンス、カスタム関数内でフォームの変更を実行するメソッドなどの読み取り専用変数が含まれています。

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

ユースケース:SetProperty ルールを使用したパネルの表示

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 パネルは非表示のままになります。

ユースケース：フィールドを検証します。

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 ントロールパネルが画面に表示されます。

ユースケース：パネルのリセット

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 パネルがリセットされることを示す次の図を参照してください。

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

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 文字を超える文字を入力すると、フィールドが検証され、フォームが送信されます。

ユースケース：変更されたデータのサーバーへの送信

次のコード行：
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 の図を参照してください。

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

カスタム関数のキャッシュサポート

アダプティブFormsは、カスタム関数のキャッシュを実装して、ルールエディターでカスタム関数のリストを取得する際の応答時間を短縮します。 error.log ファイルに Fetched following custom functions list from cache のようなメッセージが表示されます。

カスタム関数が変更されると、キャッシュが無効化され、解析されます。

トラブルシューティング troubleshooting

考慮事項