アダプティブフォームフィールドのカスタム外観の作成 create-custom-appearances-for-adaptive-form-fields
概要 introduction
アダプティブフォームでは、 外観フレームワーク アダプティブフォームフィールドのカスタム外観を作成し、異なるユーザーエクスペリエンスを提供するのに役立ちます。 たとえば、ラジオボタンとチェックボックスをトグルボタンで置き換える、またはカスタムの jQuery プラグインを使用して、電話番号やメール ID といったフィールドにおけるユーザーの入力を制限するなどです。
このドキュメントでは、jQuery プラグインを使用して、アダプティブフォームフィールド用にこれらの代替エクスペリエンスを作成する方法を説明します。 さらに、数値フィールドコンポーネントが数値ステッパーまたはスライダーとして表示されるカスタム外観を作成する例を示します。
まず、この記事で使用される主な用語と概念について見てみましょう。
アピアランス:アダプティブフォームフィールドの様々なエレメントのスタイル、ルックアンドフィール、編成です。通常、ラベル、入力用のインタラクティブ領域、ヘルプアイコン、フィールドの短い説明や長い説明が含まれます。 この記事で説明する外観のカスタマイズは、フィールドの入力領域の外観に適用できます。
jQuery プラグイン:jQuery ウィジェットのフレームワークに基づいた、代替のアピアランスを実装するための標準的なメカニズムを提供します。
ClientLib:複雑な JavaScript と CSS コードにより駆動する AEM のクライアント側プロセスのライブラリシステムです。詳しくは、「クライアント側ライブラリの使用」を参照してください。
アーキタイプ:Maven プロジェクトのオリジナルパターンまたはモデルとして定義される Maven プロジェクトテンプレートツールキットです。詳しくは、「アーキタイプの概要」を参照してください。
ユーザーコントロール:フィールドの値を含み、カスタムのウィジェット UI をアダプティブフォームモデルとバインドするためのアピアランスフレームワークで使用される、ウィジェットの主な要素です。
カスタム外観の作成手順 steps-to-create-a-custom-appearance
カスタム外観を作成する手順は、大まかに次のとおりです。
-
プロジェクトを作成する:AEM でデプロイするコンテンツパッケージを生成する Maven プロジェクトを作成します。
-
既存の Widget クラスを拡張する:既存の Widget クラスを拡張して必要なクラスをオーバーライドします。
-
クライアントライブラリを作成する:
clientLib: af.customwidget
ライブラリを作成して、必要な JavaScript と CSS ファイルを追加します。 -
プロジェクトを構築してインストールする:Maven プロジェクトを構築して、生成したコンテンツパッケージをAEM にインストールします。
-
アダプティブフォームを更新する:アダプティブフォームフィールドのプロパティを更新して、カスタムアピアランスを使用します。
プロジェクトの作成 create-a-project
Maven アーキタイプは、カスタム外観を作成するための出発点です。 使用するアーキタイプの詳細を次に示します。
- リポジトリ//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 プロジェクトのバージョン。
- パッケージ:ファイル構造に使用するパッケージ。
- 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
既存のウィジェットクラスの拡張 extend-an-existing-widget-class
プロジェクトテンプレートを作成したら、必要に応じて次の変更を行います。
-
サードパーティのプラグインの依存関係をプロジェクトに含めます。
- サードパーティまたはカスタムの jQuery プラグインを
jqueryplugin/javascript
フォルダーに入れ、関連する CSS ファイルをjqueryplugin/css
フォルダーに入れます。詳しくは、jqueryplugin/javascript and jqueryplugin/css
フォルダーの JS ファイルと CSS ファイルを参照してください。 js.txt
およびcss.txt
ファイルを変更して、jQuery プラグインの追加の JavaScript ファイルと CSS ファイルが含まれるようにします。
- サードパーティまたはカスタムの jQuery プラグインを
-
フレームワーク内でサードパーティのプラグインを統合して、カスタム外観のフレームワークと jQuery プラグインとのインタラクションを有効にします。新しいウィジェットは、次の関数を拡張またはオーバーライドした後にのみ機能するようになります。
-
必要に応じて
integration/javascript
フォルダーの JavaScript ファイルを更新します。- テキスト
__widgetName__
を実際のウィジェットの名前に置き換えます。 - 適切な標準のウィジェットクラスからウィジェットを拡張します。 ほとんどの場合、置き換えられる既存のウィジェットに対応するウィジェットクラスです。 親クラス名は複数の場所で使用されるため、ファイル内すべての文字列
xfaWidget.textField
のインスタンスを検索して、実際使用する親クラスで置き換えることを推奨します。 render
メソッドを拡張して代替の UI を設定します。その場所から jQuery プラグインが起動し、UI またはインタラクション動作を更新します。render
メソッドは、ユーザーコントロール要素を返します。getOptionsMap
メソッドを拡張して、ウィジェット内の変更により影響を受けるオプション設定をオーバーライドします。この機能は、オプションの変更時に実行すべきアクションの詳細を提供するマッピングを返します。キーはウィジェットに提供されるオプションです。値はそのオプションの変更が検出されたときに毎回呼び出される関数です。getEventMap
メソッドは、そのウィジェットによりトリガーされるイベントを、アダプティブフォームモデルが必要とするイベントとあわせてマッピングします。デフォルト値ではデフォルトのウィジェットの標準 HTML イベントがマッピングされ、代替のイベントがトリガーされる場合は更新の必要があります。showDisplayValue
およびshowValue
は、表示値を適用し、パターン形式文字列を編集します。また、別の動作にオーバーライドすることができます。getCommitValue
メソッドはcommit
イベント発生時にアダプティブフォームのフレームワークにより呼び出されます。一般に、これは exit イベントです(変更時に発生するドロップダウン、ラジオボタンおよびチェックボックス要素を除く)。 詳しくは、 アダプティブForms式.- テンプレートファイルは、様々なメソッドの実装例を提供します。 拡張しないメソッドを削除します。
- テキスト
クライアントライブラリの作成 create-a-client-library
Maven アーキタイプで生成されたサンプルプロジェクトは、必要なクライアントライブラリを自動で作成し、af.customwidgets
カテゴリでそれらをクライアントライブラリに含めます。af.customwidgets
で使用できる JavaScript および CSS ファイルは実行時に自動で含まれます。
ビルドとインストール build-and-install
プロジェクトをビルドするには、シェルで次のコマンドを実行して、AEMサーバーにインストールする必要のある CRX パッケージを生成します。
mvn clean install
settings.xml
ファイルで取得されます。アダプティブフォームの更新 update-the-adaptive-form
アダプティブフォームフィールドにカスタム外観を適用するには:
- アダプティブフォームを編集モードで開きます。
- を開きます。 プロパティ カスタム外観を適用するフィールド用のダイアログ。
- 「スタイル設定」タブで、
CSS class
プロパティを更新してwidget_<widgetName>
フォーマットにアピアランスの名前を追加します。例: widget_numericstepper
サンプル:カスタム外観の作成 sample-create-a-custom-appearance-nbsp
次に、数値フィールドが数値ステッパーまたはスライダーとして表示されるようにカスタムの外観を作成する例を見てみましょう。 以下の手順を実行します。
-
次のコマンドを実行して、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
-
customWidgets
(artifactID
プロパティで指定された値)ディレクトリに移動して、次のコマンドを実行し Eclipse プロジェクトを生成します。mvn eclipse:eclipse
-
Eclipse ツールを開き、以下の手順を実行して Eclipse プロジェクトをインポートします。
-
ファイル/取り込み/既存プロジェクトをワークスペースへ を選択します。
-
参照して、
archetype:generate
コマンドを実行したフォルダを選択します。 -
「Finish」をクリックします。
-
-
カスタム外観に使用するウィジェットを選択します。 この例では、次の数値ステッパーウィジェットを使用しています。
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
タイプのフィールドであり、プラグインコードで複製されます。- フィールドが無効の場合に「+」および「-」ボタンが無効になります。
- 数値ステッパーが
-
bootstrap-number-input.js
(jQuery プラグイン)のコンテンツをnumericStepper-plugin.js
ファイルのコンテンツに置き換えます。 -
numericStepper-widget.js
ファイルで、以下のコードを追加して、プラグインを起動するレンダリングメソッドをオーバーライドし、$userControl
オブジェクトを返します。code language-java 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; }
-
numericStepper-widget.js
ファイルで、getOptionsMap
プロパティをオーバーライドしてアクセスオプションを上書きし、無効モードで「+」および 「-」ボタンを非表示にします。code language-java 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; }
-
変更を保存し、
pom.xml
ファイルを含むフォルダーに移動したら、次の Maven コマンドを実行してプロジェクトを構築します。mvn clean install
-
AEM パッケージマネージャーを使ってパッケージをインストールします。
-
カスタム外観を適用するアダプティブフォームを編集モードで開き、次の手順を実行します。
-
カスタム外観を適用するフィールドを右クリックしてから、「編集」をクリックしてコンポーネントを編集ダイアログを開きます。
-
「スタイル設定」タブで、CSS クラス プロパティを更新して
widget_numericStepper
を追加します。
-
これで、作成した新しい外観を使用できるようになりました。