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

概要

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

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

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

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

jQuery pluginjQueryウィジェットフレームワークに基づく、代替の外観を実装するための標準的なメカニズムを提供します。

ClientLib複雑なJavaScriptとCSSコードによって実行される、AEMのクライアントサイドの処理におけるクライアントサイドのライブラリシステム。 詳しくは、「クライアント側ライブラリの使用」を参照してください。

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

ユーザー 制御フィールドの値を含むウィジェットのメイン要素を指し、カスタムウィジェットUIとアダプティブフォームモデルを連結する外観フレームワークで使用されます。

カスタム外観の作成手順

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

  1. プロジェクトの作成:AEMに展開するコンテンツパッケージを生成するMavenプロジェクトを作成します。

  2. 既存のウィジェットクラスを拡張します:既存のウィジェットクラスを拡張し、必要なクラスをオーバーライドします。

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

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

  5. アダプティブフォームの更新:カスタム外観を使用するようにアダプティブフォームフィールドのプロパティを更新します。

プロジェクトの作成

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

  • リポジトリ: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 です。
  • 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 プラグインとのインタラクションを有効にします。新しいウィジェットは、次の関数を拡張または上書きした後でのみ機能します。

Function 説明
render レンダリング関数は、ウィジェットのデフォルト HTML 要素のための jQuery オブジェクトを返します。デフォルトの HTML 要素は、フォーカス可能タイプとします。例えば、<a><input><li>のように指定します。 返される要素は$userControlとして使用されます。 $userControlが上記の制約を指定する場合、AbstractWidgetクラスの関数は期待どおりに動作します。そうでない場合、一部の一般的なAPI (フォーカス、クリック)は変更を必要とします。
getEventMap HTML イベントを XFA イベントに変換するマップを返します。
{ blur: XFA_EXIT_EVENT, }
この例は、がHTMLイベント blur で、対応するXFAイベント XFA_EXIT_EVENT であることを示しています。
getOptionsMap オプションの変更時に、実行すべきアクションの詳細を提供するマップを返します。キーはウィジェットに提供されるオプションです。値はオプションの変更が検出されるたびに呼び出される関数です。 ウィジェットには、すべての一般的なオプション(valuedisplayValue を除く)のハンドラーが用意されています。
getCommitValue jQuery ウィジェットフレームワークは、jQuery ウィジェットの値が XFA モデルに保存されたときに(例えばテキストフィールドの exit イベント時に)毎回この関数を読み込みます。実装は、ウィジェットに保存された値を返す必要があります。ハンドラーには、オプションの新しい値が指定されます。
showValue デフォルトでは、XFA での enter イベント時に、フィールドの rawValue が表示されます。この関数が呼び出され、rawValueがユーザーに表示されます。
showDisplayValue デフォルトでは、XFA での exit イベント時に、フィールドの formattedValue が表示されます。この関数が呼び出され、formattedValueがユーザーに表示されます。
  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

メモ

Maven プロジェクトは、POM ファイル内のリモートリポジトリを参照します。これは単に参照目的であり、Maven 標準では、リポジトリ情報は settings.xml ファイルで取得されます。

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

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

  1. アダプティブフォームを編集モードで開きます。
  2. カスタム外観を適用するフィールドの Property ダイアログを開きます。
  3. スタイル設定」タブで、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. customWidgetsartifactID プロパティで指定された値)ディレクトリに移動して、次のコマンドを実行し Eclipse プロジェクトを生成します。

    mvn eclipse:eclipse

  3. Eclipse ツールを開き、以下の手順を実行して Eclipse プロジェクトをインポートします。

    1. ファイル/取り込み/既存プロジェクトをワークスペースへ​を選択します。

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

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

      eclipse-screenshot

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

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

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

    • 数値ステッパーは- $.xfaWidget.numericInputから拡張する必要があります。

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

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

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

    • サンプルではステッパーのスタイル設定を実行しないため、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 を追加します。

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

このページ

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