AEM コンポーネントを使用して、web ページ上で使用できるコンテンツを保持、書式設定およびレンダリングします。
ページをオーサリングするとき、作成者はコンポーネントを使用してコンテンツを編集および設定できます。
パブリッシュインスタンス上では、コンポーネントがコンテンツをレンダリングし、適切なタイミングで web サイト訪問者に表示します。
このページの内容は、AEM コンポーネント - 基本を踏まえたものです。
/libs/cq/gui/components/authoring/dialog
の下にあるコンポーネントは、エディター(オーサリングのコンポーネントダイアログ)で使用することのみが意図されています。他の場所で使用すると(インスタンスのウィザードダイアログ内など)、予期したとおりに動作しないことがあります。
このページでは、AEM 用の新しいコンポーネントの開発に必要なリファレンスドキュメント(またはリファレンスドキュメントへのリンク)を紹介します。実践的な例については、AEM コンポーネントの開発 - コードサンプルを参照してください。
コンポーネントの基本構造については、AEM コンポーネント - 基本のページで説明しています。このドキュメントでは、タッチ対応 UI とクラシック UI の両方を扱っています。新しいコンポーネントでクラシック設定を使用する必要がない場合でも、既存のコンポーネントから継承する際にクラシック設定について知っていると役立ちます。
実装するコンポーネントによっては、構造全体を最初から定義して開発するのではなく、既存インスタンスを拡張したり、カスタマイズしたりするだけで済むことがあります。
既存のコンポーネントまたはダイアログを拡張またはカスタマイズする際に、構造全体またはダイアログに必要な構造をコピーまたは複製してから変更を加えることができます。
既存コンポーネントは、リソースタイプ階層および関連する継承メカニズムを使用して拡張できます。
コンポーネントは、検索パスロジックに基づいたオーバーレイを使用して再定義することもできます。ただし、そのような場合は Sling Resource Merger が呼び出されないので、/apps
でオーバーレイ全体を定義する必要があります。
コンテンツフラグメントコンポーネントもカスタマイズおよび拡張できますが、構造全体やアセットとの関係を考慮する必要があります。
Sling Resource Merger を使用し、sling:resourceSuperType
プロパティを定義することで、コンポーネントダイアログをオーバーライドすることもできます。
つまり、ダイアログ全体を(sling:resourceSuperType
を使用して)再定義するのとは対照的に、再定義する必要があるのは相違点だけです。これは、推奨されるコンポーネントダイアログ拡張方法です。
詳しくは、Sling Resource Merger を参照してください。
コンポーネントは HTML を使用してレンダリングされます。コンポーネントでは、必要なコンテンツを取得して、オーサリング環境とパブリッシュ環境の両方で必要に応じてレンダリングするために必要な HTML を定義しなければなりません。
HTML テンプレート言語(HTL)は、AEM 6.0 で JSP(JavaServer Pages)に代わって導入されたスクリプティング言語であり、HTML の扱いに適した、推奨されるサーバーサイドテンプレートシステムです。堅牢なエンタープライズ web サイトを構築する必要のある web 開発者にとって、HTL は安全性と開発効率の向上に役立ちます。
HTL と JSP のどちらを使用してもコンポーネントを開発できますが、AEM の推奨スクリプティング言語は HTL なので、ここでは HTL を使用した開発について説明します。
このオプションのロジックでは、レンダリングするコンテンツの選択や計算を行います。このロジックは、適切な Use-API パターンを持つ HTL 式から呼び出されます。
このようにロジックを外観から分離するメカニズムは、特定のビューで何が呼び出されるかを明確化するために役立ちます。同じリソースの異なるビューに対し、異なるロジックを使用することもできます。
HTL Java Use-API を使用すると、HTL ファイルからカスタム Java クラスのヘルパーメソッドへのアクセスが可能になります。そのため、Java コードを使用して、コンポーネントのコンテンツを選択および設定するためのロジックを実装できます。
HTL JavaScript Use-API を使用すると、HTL ファイルから JavaScript で書かれたヘルパーコードへのアクセスが可能になります。これにより、JavaScript コードを使用して、コンポーネントコンテンツの選択と設定のロジックを実装できます。
最近の web サイトは、複雑な JavaScript や CSS コードを利用したクライアント側の処理に大きく依存しています。このコードの提供を編成および最適化することが厄介な問題となることがあります。
この問題に対処するために、AEMでは次の機能を提供しています。 クライアント側ライブラリフォルダー:クライアント側コードをリポジトリに保存し、カテゴリに整理し、コードの各カテゴリをクライアントに提供するタイミングと方法を定義できます。 その後、クライアント側ライブラリシステムにより、最終的な web ページで、正しいコードを読み込むための正しいリンクが作成されます。
詳しくは、クライアントサイド HTML ライブラリの使用を参照してください。
コンポーネントの編集動作を設定できます。編集動作には、コンポーネントに使用できるアクション、インプレースエディターの特性、コンポーネントに対するイベントに関連するリスナーなどの属性が含まれます。固有の相違点は多少ありますが、設定はタッチ対応 UI とクラシック UI の両方に共通です。
タイプ cq:EditConfig
の cq:editConfig
ノードをコンポーネントノード(タイプ cq:Component
)の下に追加し、特定のプロパティと子ノードを追加することによって、コンポーネントの編集動作が設定されます。
プレビューモードに切り替えると、ページが更新されなくても WCM モード Cookie が設定されます。
レンダリングが WCM モードの影響を受けるコンポーネントの場合は、明確にそのコンポーネントを更新し、この Cookie の値を使用するように定義する必要があります。
値 EDIT
と PREVIEW
は、タッチ操作対応 UI でのみ WCM モード Cookie に使用されます。
作成者はダイアログを使用してコンポーネントとやり取りできます。ダイアログを使用することで、作成者や管理者はコンテンツを編集したり、コンポーネントを設定したり、(デザインダイアログを使用して)デザインパラメーターを定義したりできます。
AEM の現代的なルックアンドフィールは Coral UI と Granite UI で定義されています。
Granite UI で提供される幅広い基本コンポーネント(ウィジェット)は、オーサリング環境でダイアログを作成するために使用されます。必要な場合には、選択したウィジェットを拡張し、独自のウィジェットを作成することができます。
詳しくは、以下を参照してください。
Coral UI
Granite UI
Granite UI コンポーネントの性質(および ExtJS ウィジェットとの違い)により、タッチ操作対応 UI とクラシック UI では、コンポーネントとのやり取りにいくつかの相違点があります。
タッチ操作対応 UI 用ダイアログは、以下のように実装されます。
cq:dialog
という名前です。
sling:resourceType
プロパティが設定された nt:unstructured
ノードとして定義されます。
cq:Component
ノードの下のコンポーネント定義の横にあります。
コンテンツ構造と sling:resourceType
プロパティに基づいて、サーバーサイドに(Sling コンポーネントとして)レンダリングされます。
Granite UI フレームワークを使用します。
ダイアログ内のフィールドを記述したノード構造を含みます。
sling:resourceType
プロパティを持つ nt:unstructured
ノードです。ノード構造の例は次のとおりです。
newComponent (cq:Component)
cq:dialog (nt:unstructured)
content
layout
items
column
items
file
description
ダイアログのカスタマイズは、ダイアログ自体がコンポーネントなので、コンポーネントの開発に似ています(コンポーネントスクリプトでレンダリングするマークアップや、クライアントライブラリで提供する動作やスタイルなど)。
例については、以下を参照してください。
/libs/foundation/components/text/cq:dialog
/libs/foundation/components/download/cq:dialog
コンポーネントにタッチ操作向け UI 用のダイアログが定義されていない場合は、クラシック UI ダイアログが互換性レイヤー内でフォールバックとして使用されます。そのようなダイアログをカスタマイズするには、クラシック UI ダイアログをカスタマイズする必要があります。詳しくは、クラシック UI 用の AEM コンポーネントを参照してください。
次を参照してください。
タッチ操作向け UI 用のウィジェットは、Granite UI コンポーネントとして実装されています。
タッチ操作向け UI 用のコンポーネントダイアログで使用する新しいウィジェットを作成するには、新しい Granite UI フィールドコンポーネントを作成する必要があります。
Granite UI について詳しくは、Granite UI ドキュメントを参照してください。
ダイアログをフォーム要素の単純なコンテナと見なす場合、ダイアログコンテンツの主なコンテンツをフォームフィールドとして表示することもできます。新しいフォームフィールドを作成するには、リソースタイプを作成する必要があります。これは、新しいコンポーネントの作成と同じです。この作業を容易にするために、Granite UI は、sling:resourceSuperType
を使用して以下を継承する汎用フィールドコンポーネントを提供しています。
/libs/granite/ui/components/coral/foundation/form/field
Granite UI には、具体的に言えばダイアログ(一般的に言えばフォーム)での使用に適した、幅広いフィールドコンポーネントが用意されています。
この点はクラシック UI とは異なります。クラシック UI では、ウィジェットは cq:Widgets
ノードによって表され、各ノードには対応する ExtJS ウィジェットとの関係を確立するための特定の xtype
があります。実装の観点では、これらのウィジェットは ExtJS フレームワークによってクライアントサイドでレンダリングされていました。
リソースタイプを作成したら、sling:resourceType
プロパティで参照して新しいノードをダイアログに追加することで、フィールドをインスタンス化できます。
コンポーネントのスタイル設定と動作を定義する場合は、カスタム CSS/LESS および JS を定義する専用のクライアントライブラリを作成できます。
クライアントライブラリをコンポーネントダイアログ用にのみ読み込む(別のコンポーネント用に読み込まれない)には、プロパティを設定する必要があります extraClientlibs
ダイアログの「 」から、先ほど作成したクライアントライブラリのカテゴリ名に変更します。 この方法は、クライアントライブラリが非常に大きい場合や、フィールドがそのダイアログに固有で、他のダイアログで必要になることがない場合にお勧めです。
クライアントライブラリをすべてのダイアログ用に読み込むには、クライアントライブラリのカテゴリプロパティを cq.authoring.dialog
に設定します。これは、すべてのダイアログのレンダリング時にデフォルトで含まれるクライアントライブラリのカテゴリ名です。クライアントライブラリが小さい場合や、フィールドが汎用的で、他のダイアログで再利用できる場合には、この方法を使用できます。
例えば、次を参照してください。
cqgems/customizingfield/components/colorpicker/clientlibs
要件に応じて、次のどちらかを実行できます。
sling:resourceSuperType
)で拡張するレンダリング条件(rendercondition
)を使用して、ダイアログ内の特定のタブやフィールドへのアクセス権を持つユーザーを制御することもできます。以下に例を示します。
+ mybutton
- sling:resourceType = granite/ui/components/coral/foundation/button
+ rendercondition
- sling:resourceType = myapp/components/renderconditions/group
- groups = ["administrators"]
ダイアログフィールドのイベントの処理は、カスタムクライアントライブラリのリスナーで行われるようになりました。これは以前の方法からの変更点です。以前は、コンテンツ構造のリスナーを使用していました。
フィールドにロジックを挿入するには、以下を実行する必要があります。
これを実現するには、やり取りする、基になるウィジェットライブラリについて理解する必要があります。反応するイベントの識別については、Coral UI ドキュメントを参照してくださいExtJS を使用して実行する必要があったプロセスと非常によく似ています。指定されたウィジェットのドキュメントページを探し、そのイベント API の詳細を確認してください。
例えば、次を参照してください。
cqgems/customizingfield/components/clientlibs/customizingfield
ExtJS を使用するクラシック UI では、コンテンツ構造内に指定のウィジェットのリスナーを用意することが普通でした。タッチ操作向け UI では、同じことを別の方法で実現します。JS のリスナーコード(またはあらゆるコード)はコンテンツ内で定義されないからです。
コンテンツ構造は意味構造を記述するものであり、基となるウィジェットの性質を示すものであってはなりません。コンテンツ構造に JS コードを含めないことで、コンテンツ構造を変更せずに実装の詳細を変更することが可能になります。言い換えると、コンテンツ構造に触れることなく、ウィジェットライブラリを変更できます。
ダイアログが使用可能で準備が整ったときにのみ実行する必要があるカスタム JavaScript がある場合は、dialog-ready
イベントをリッスンする必要があります。
このイベントは、ダイアログが読み込まれて(または再度読み込まれて)、使用の準備ができたときにトリガーされます。つまり、ダイアログの DOM に変更(作成/更新)がある場合に必ずトリガーされます。
dialog-ready
は、ダイアログ内のフィールドや類似のタスクをカスタマイズする JavaScript カスタムコードをフックするために使用できます。
指定されたフィールドを「必須」としてマークするには、フィールドのコンテンツノードに次のプロパティを設定します。
required
Boolean
例えば、次を参照してください。
/libs/foundation/components/page/cq:dialog/content/items/tabs/items/basic/items/column/items/title/items/title
Granite UI でのフィールド検証および Granite UI コンポーネント(ウィジェットと同等)のフィールド検証は、foundation-validation
API を使用して実行します。詳しくは、foundation-valdiation
Granite のドキュメントを参照してください。
詳しくは、例えば、以下を参照してください。
cqgems/customizingfield/components/clientlibs/customizingfield/js/validations.js
/libs/cq/gui/components/authoring/dialog/clientlibs/dialog/js/validations.js
コンポーネントにデザインモードで編集できるデザイン詳細がある場合は、デザインダイアログが表示されます。
デザインダイアログの定義は、コンテンツの編集に使用されるダイアログの定義によく似ています。違いはノードとして定義される点です。
cq:design_dialog
nt:unstructured
インプレースエディターを使用すると、ダイアログを開くことなく、段落フロー内で直接コンテンツを編集できます。例えば、標準のテキストとタイトルのコンポーネントには、どちらもインプレースエディターがあります。
インプレースエディターは、すべてのコンポーネントタイプで必要または重要なものではありません。
詳しくは、ページオーサリングの拡張 - 新しいインプレースエディターを追加を参照してください。
コンポーネントツールバーは、ユーザーがコンポーネントに対する幅広いアクション(編集、設定、コピー、削除など)にアクセスできるようにする機能です。
詳しくは、ページオーサリングの拡張 - 新しいアクションをコンポーネントツールバーに追加を参照してください。
新しいコンポーネントが他のページのコンテンツを参照する場合は、参照レールの「借りたコンテンツ」セクションおよび「貸したコンテンツ」セクションに影響を与えるかどうかを考慮できます。
初期状態の AEM は参照コンポーネントのみを確認します。コンポーネントを追加するには、OSGi バンドル WCM オーサリングコンテンツ参照設定を設定する必要があります。
定義に新しいエントリを作成し、確認するプロパティと共にコンポーネントを指定します。次に例を示します。
/apps/<*your-Project*>/components/reference@parentPath
AEM と連携する場合は、いくつかの方法でこのようなサービスの設定を管理できます。詳細および推奨事項については、OSGi の設定を参照してください。
コンポーネントを開発したら、必要なページで使用できるよう、適切な段落システムでの使用を有効にする必要があります。
次のいずれかの方法で有効化できます。
components
プロパティを定義する。AEM では、ページの段落システムを設定するときに、常に空のコンテンツをページにドラッグするのではなく、ユーザーが(適切な)アセットをページのインスタンスにドラッグすると新しいコンポーネントのインスタンスが自動的に作成されるような設定にすることができます。
この動作と、必要なアセットとコンポーネントの関連付けは、次の方法で設定できます。
ページデザインの段落定義の下に、例:
/etc/designs/<myApp>/page/par
新しいノードを作成します。
cq:authoring
nt:unstructured
この下に、アセットとコンポーネントのマッピングをすべて保持する新しいノードを作成します。
assetToComponentMapping
nt:unstructured
アセットとコンポーネントのマッピングごとに、ノードを作成します。
nt:unstructured
それぞれが以下のプロパティを持ちます。
assetGroup
:
String
media
)assetMimetype
:
String
image/*
)droptarget
:
String
image
)resourceType
:
String
foundation/components/image
)type
:
String
Images
)例えば、次を参照してください。
/etc/designs/geometrixx/jcr:content/page/par/cq:authoring
/etc/designs/geometrixx-outdoors/jcr:content/page/par/cq:authoring
/etc/designs/geometrixx-media/jcr:content/article/article-content-par/cq:authoring
GitHub のコード
このページのコードは GitHub にあります
コンポーネントインスタンスの自動作成は、コアコンポーネントと編集可能テンプレートの使用時に UI 内で簡単に設定できるようになりました。特定のメディアタイプに自動的に関連付けるコンポーネントの定義について詳しくは、ページテンプレートの作成を参照してください。
AEM Brackets 拡張は、AEM コンポーネントおよびクライアントライブラリを編集するためのスムーズなワークフローを提供します。この拡張は、Brackets コードエディターをベースとしています。
この拡張には、次の機能があります。
Brackets は、コンポーネントを作成するための推奨メカニズムです。Brackets は、クラシック UI 向けに設計された CRXDE Lite のコンポーネント作成機能の代わりになります。
クラシック UI で使用するようにデザインされたコンポーネントを、タッチ操作対応 UI 専用または両方の UI で使用できるコンポーネントに移行する場合は、以下の問題を考慮する必要があります。
HTL
コンポーネント
cq:listener
コードを移行します。cq:listener
コードを移行します。ダイアログ
クラシック UI 向けにデザインされたプロジェクトを移行する場合は、cq:listener
コード(およびコンポーネントに関連するクライアント側ライブラリ)でクラシック UI 固有の関数(CQ.wcm.*
など)を使用してください。移行するには、タッチ操作対応 UI で同等のオブジェクトまたは関数を使用して、このようなコードを更新する必要があります。
プロジェクトをタッチ操作向け UI に完全に移行する場合は、タッチ操作向け UI に関連するオブジェクトや関数を使用するように、このようなコードを置き換える必要があります。
ただし、移行期間中にプロジェクトがクラシック UI とタッチ操作向け UI の両方に対応する必要がある場合(通常のシナリオ)は、適切なオブジェクトを参照する別々のコードを区別するためのスイッチを実装する必要があります。
このスイッチメカニズムは、次のように実装できます。
if (Granite.author) {
// touch UI
} else {
// classic UI
}
開発者は、以下をすばやく把握できるようにコンポーネントドキュメントに簡単にアクセスしたいと考えます。
この理由から、既存のドキュメントマークダウンをコンポーネント自体の中で利用できるようにすることは簡単です。
コンポーネント構造に README.md
ファイルを配置します。このマークダウンはコンポーネントコンソールに表示されます。
サポートしているマークダウンは、コンテンツフラグメントの場合と同じです。