アダプティブフォームフィールドのカスタム外観の作成

概要

アダプティブフォームは外観フレームワークを強化することで、アダプティブフォームフィールドの外観をカスタマイズして独自のユーザーエクスペリエンスの提供を実現します。たとえば、ラジオボタンとチェックボックスをトグルボタンで置き換える、またはカスタムの jQuery プラグインを使用して、電話番号や電子メール ID といったフィールドにおけるユーザーの入力を制限するなどです。

このドキュメントでは、アダプティブフォームフィールドで jQuery プラグインを使用して、これらの代替エクスペリエンスを作成する方法を説明します。加えて、外観をカスタマイズして数値フィールドのコンポーネントを数値ステッパーまたはスライダーとして表示する例も紹介します。

まずは、この記事で使用される重要な用語と概念について見てみましょう。

アピアランス：アダプティブフォームフィールドの様々なエレメントのスタイル、ルックアンドフィール、編成です。通常、ラベル、入力用のインタラクティブ領域、ヘルプアイコン、ならびにフィールドについての短い説明や長い説明などが含まれます。この記事で扱われる外観のカスタマイズは、フィールドの入力領域の外観に適用できます。

jQuery プラグイン：jQuery ウィジェットのフレームワークに基づいた、代替のアピアランスを実装するための標準的なメカニズムを提供します。

ClientLib：複雑な JavaScript と CSS コードにより駆動する AEM のクライアント側プロセスのライブラリシステムです。詳しくは、「クライアント側ライブラリの使用」を参照してください。

アーキタイプ：Maven プロジェクトのオリジナルパターンまたはモデルとして定義される Maven プロジェクトテンプレートツールキットです。詳しくは、「アーキタイプの概要」を参照してください。

ユーザーコントロール：フィールドの値を含み、カスタムのウィジェット UI をアダプティブフォームモデルとバインドするためのアピアランスフレームワークで使用される、ウィジェットの主な要素です。

カスタム外観の作成手順

カスタム外観を作成する手順は、高レベルでは次のようになります。

1. プロジェクトを作成する：AEM でデプロイするコンテンツパッケージを生成する Maven プロジェクトを作成します。

2. 既存の Widget クラスを拡張する：既存の Widget クラスを拡張して必要なクラスをオーバーライドします。

3. クライアントライブラリを作成する：clientLib: af.customwidget ライブラリを作成して、必要な JavaScript と CSS ファイルを追加します。

4. プロジェクトを構築してインストールする：Maven プロジェクトを構築して、生成したコンテンツパッケージをAEM にインストールします。

5. アダプティブフォームを更新する：アダプティブフォームフィールドのプロパティを更新して、カスタムアピアランスを使用します。

プロジェクトの作成

Maven アーキタイプは、カスタム外観作成の開始点です。使用するアーキタイプの詳細は、次のとおりです。

• リポジトリー：https://repo1.maven.org/maven2/com/adobe/
• アーティファクト ID：カスタムアピアランスのアーキタイプ
• グループ ID：com.adobe.aemforms
• バージョン：1.0.4

次のコマンドを実行して、アーキタイプに基づいたローカルプロジェクトを作成します。

mvn archetype:generate -DarchetypeRepository=https://repo1.maven.org/maven2/com/adobe/ -DarchetypeGroupId=com.adobe.aemforms -DarchetypeArtifactId=custom-appearance-archetype -DarchetypeVersion=1.0.4

このコマンドにより Maven プラグインおよびリポジトリからのアーキタイプ情報がダウンロードされ、次の情報に基づいたプロジェクトが生成されます。

• groupId：生成された Maven プロジェクトにより使用されるグループ ID です。
• artifactId：生成された Maven プロジェクトで使用されるアーティファクト ID です。
• version：生成した 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

既存のウィジェットのクラスの拡張

プロジェクトのテンプレートを作成したら、必要に応じて以下の変更を行います。

1. プロジェクトにサードパーティのプラグインを含めます。

   1. サードパーティまたはカスタムの jQuery プラグインを jqueryplugin/javascript フォルダーに入れ、関連する CSS ファイルを jqueryplugin/css フォルダーに入れます。詳しくは、jqueryplugin/javascript and jqueryplugin/css フォルダーの JS ファイルと CSS ファイルを参照してください。

   2. js.txt および css.txt ファイルを変更して、jQuery プラグインの追加の JavaScript ファイルと CSS ファイルが含まれるようにします。

2. フレームワーク内でサードパーティのプラグインを統合して、カスタム外観のフレームワークと jQuery プラグインとのインタラクションを有効にします。新しいウィジェットは、次の関数を拡張またはオーバーライドした後にのみ機能するようになります。

1. 必要に応じて integration/javascript フォルダーの JavaScript ファイルを更新します。

   • テキスト __widgetName__ を実際のウィジェットの名前に置き換えます。

   • 適切なデフォルトのウィジェットクラスからウィジェットを拡張します。多くの場合は、置き換えられる既存のウィジェットに対応したウィジェットクラスになります。親クラス名は複数の場所で使用されるため、ファイル内すべての文字列 xfaWidget.textField のインスタンスを検索して、実際使用する親クラスで置き換えることを推奨します。

   • render メソッドを拡張して代替の UI を設定します。その場所から jQuery プラグインが起動し、UI またはインタラクション動作を更新します。render メソッドは、ユーザーコントロール要素を返します。

   • getOptionsMap メソッドを拡張して、ウィジェット内の変更により影響を受けるオプション設定をオーバーライドします。この機能は、オプションの変更時に実行すべきアクションの詳細を提供するマッピングを返します。キーはウィジェットに提供されるオプションです。値はそのオプションの変更が検出されたときに毎回呼び出される関数です。

   • getEventMap メソッドは、そのウィジェットによりトリガーされるイベントを、アダプティブフォームモデルが必要とするイベントとあわせてマッピングします。デフォルト値ではデフォルトのウィジェットの標準 HTML イベントがマッピングされ、代替のイベントがトリガーされる場合は更新の必要があります。

   • showDisplayValue および showValue は、表示値を適用し、パターン形式文字列を編集します。また、別の動作にオーバーライドすることができます。

   • getCommitValue メソッドは commit イベント発生時にアダプティブフォームのフレームワークにより呼び出されます。通常これは exit イベントですが、変更により生じるドロップダウン、ラジオボタン、チェックボックス要素は例外とします。詳しくは、「アダプティブフォームの数式」を参照してください。

   • テンプレートファイルでは、さまざまなメソッドでの導入例が紹介されています。拡張しないメソッドは削除してください。

クライアントライブラリの作成

Maven アーキタイプで生成されたサンプルプロジェクトは、必要なクライアントライブラリを自動で作成し、af.customwidgets カテゴリでそれらをクライアントライブラリに含めます。af.customwidgets で使用できる JavaScript および CSS ファイルは実行時に自動で含まれます。

構築とインストール

プロジェクトを構築するには、シェルで以下のコマンドを実行して AEM サーバーにインストールする必要のある CRX パッケージを生成します。

mvn clean install

アダプティブフォームの更新

カスタム外観をアダプティブフォームフィールドに適用する方法は、次のとおりです。

1. アダプティブフォームを編集モードで開きます。
2. カスタム外観を適用するフィールドの Property ダイアログを開きます。
3. 「スタイル設定」タブで、CSS class プロパティを更新して widget_<widgetName> フォーマットにアピアランスの名前を追加します。例えば、widget_numericstepper です。

サンプル：カスタム外観の作成

それでは、数値のフィールドを数値ステッパーまたはスライダーとして表示されるようにカスタム外観を作成する例をみてみましょう。以下の手順を実行します。

1. 以下のコマンドを実行して、Maven アーキタイプをベースとするローカルプロジェクトを作成します。

   mvn archetype:generate -DarchetypeRepository=https://repo1.maven.org/maven2/com/adobe/ -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. ファイル／取り込み／既存プロジェクトをワークスペースへ​を選択します。

   2. 参照して、archetype:generate コマンドを実行したフォルダを選択します。

   3. 「Finish」をクリックします。

      

4. カスタム外観で使用するウィジェットを選択します。このサンプルでは、次の数値ステッパーウィジェットを使用します。

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

   Eclipse プロジェクトでは、plugin.js ファイルのプラグインコードを見直して、外観の要件を満たすようにします。このサンプルでは、外観は以下の要件を満たしています。

   • 数値ステッパーが - $.xfaWidget.numericInput から拡張します。

   • フィールドにフォーカスすると、ウィジェットの set value メソッドが値を設定します。これは、アダプティブフォームウィジェットでは必須要件です。

   • bootstrapNumber メソッドを起動するには、render メソッドをオーバーライドする必要があります。

   • プラグインのメインソースコード以外でプラグインに依存しません。

   • サンプルではステッパーのスタイル設定を実行しないため、CSS の追加を必要としません。

   • $userControl オブジェクトは、render メソッドで使用可能です。これは、text タイプのフィールドであり、プラグインコードで複製されます。

   • フィールドが無効の場合に「+」および「-」ボタンが無効になります。

5. bootstrap-number-input.js（jQuery プラグイン）のコンテンツを 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 パッケージマネージャーを使ってパッケージをインストールします。

10. カスタム外観を適用するアダプティブフォームを編集モードで開き、次の手順を実行します。

    1. カスタム外観を適用するフィールドを右クリックしてから、「編集」をクリックしてコンポーネントを編集ダイアログを開きます。

    2. 「スタイル設定」タブで、CSS クラス プロパティを更新して widget_numericStepper を追加します。

これで、作成した新しい外観を使用できるようになりました。

Business.Adobe.com リソース

Content Insights Auto Form Fill Mobile Forms Content As A Service Web Content Management Digital Rights Management