Adobe Experience Manager(AEM)コンポーネント - 基本 aem-components-the-basics
新しいコンポーネントの開発にとりかかる際は、その構造と設定の基本を理解する必要があります。
これには、標準的なセオリーを学び、標準 AEM インスタンスでのコンポーネントの実装を幅広く知ることが含まれます。AEM は新しい標準のタッチ操作対応 UI に変更されましたが、引き続きクラシック UI をサポートしているので、この後者のアプローチは少し複雑です。
概要 overview
この節では、独自コンポーネントの開発時に知っておくべき詳細の導入段階として、基本的な概念と注意点について説明します。
計画 planning
実際にコンポーネントの設定やコーディングを開始する前に、次の点について理解する必要があります。
-
そもそも新しいコンポーネントで何をするか
- 明確な仕様は、開発、テスト、引継ぎのあらゆる段階で役立ちます。詳細は時間と共に変化する可能性がありますが、仕様は更新可能です(ただし、変更箇所を記録しておく必要があります)。
-
コンポーネントを一から作成する必要があるか、基本部分を既存のコンポーネントから継承できるか
- 一から作成する必要があるとは限りません。
- AEM には、別のコンポーネント定義から詳細を継承し、拡張できる仕組みがいくつか用意されています(オーバーライド、オーバーレイ、Sling Resource Merger など)。
-
コンポーネントのコンテンツを選択または操作するためのロジックが必要か
- ロジックは、ユーザーインターフェイスレイヤーから分離しておく必要があります。HTL はこれに対応した設計になっています。
-
コンポーネントを CSS で書式設定する必要があるか
- CSS による書式設定は、コンポーネント定義から分離しておく必要があります。外部 CSS ファイルを使用して HTML 要素を変更できるように、HTML 要素の命名規則を定義します。
-
考慮すべきセキュリティ要素は何か
- 詳しくは、セキュリティチェックリスト - 開発のベストプラクティスを参照してください。
タッチ操作対応 UI とクラシック UI の違い touch-enabled-vs-classic-ui
コンポーネントの開発について本格的な検討を始める前に、作成者がどちらの UI を使用するかを知っておく必要があります。
- タッチ操作対応 UI
標準のユーザーインターフェイスは、Adobe Experience Cloud の統一されたユーザーエクスペリエンスに基づいており、Coral UI および Granite UI の基盤となるテクノロジーを使用しています。 - クラシック UI
AEM 6.4 で廃止された ExtJS テクノロジーに基づくユーザーインターフェイス。
詳しくは、UI インターフェイスに関するお客様向け推奨事項を参照してください。
タッチ操作対応 UI、クラシック UI または両方をサポートするようにコンポーネントを実装できます。標準インスタンスには、クラシック UI、タッチ対応 UI またはその両方に対応するようにあらかじめデザインされた既製のコンポーネントもあります。
このページでは、両方の基本と識別方法について説明します。
コンテンツのロジックとマークアップのレンダリング content-logic-and-rendering-markup
アドビでは、マークアップおよびレンダリングを行うコードと、コンポーネントのコンテンツ選択に関するロジックを制御するコードは、分離しておくことをお勧めします。
この方法をサポートするテンプレート言語が HTL です。HTL では、基盤となるビジネスロジックを定義するときにのみプログラミング言語を使用します。この(オプションの)ロジックは、特定のコマンドで HTL から呼び出されます。この仕組みでは、特定のビュー用に呼び出されるコードに焦点を当てることができるので、必要に応じて、同じコンポーネントの様々なビュー用のロジックを定義できます。
HTL と JSP htl-vs-jsp
HTL は、AEM 6.0 で導入された HTML テンプレート言語です。
独自コンポーネントの開発時に HTL と JSP(Java™ Server Pages)のどちらを使用すべきかという質問への回答は明快です。現在では、HTL が AEM の推奨スクリプティング言語とされています。
HTL と JSP はどちらも、クラシック UI とタッチ操作対応 UI の両方のコンポーネントの開発に使用できます。HTL はタッチ操作対応 UI 専用で JSP はクラシック UI 用だと想定する傾向があるかもしれませんが、これは時期に起因する誤解です。タッチ操作対応 UI と HTL は、ほぼ同時期に AEM に組み込まれました。HTL は現在推奨される言語なので、新しいコンポーネントに使用されており、このため、タッチ操作対応 UI に使用される傾向があります。
独自コンポーネントの開発 developing-your-own-components
UI の種類に応じた独自コンポーネントを作成するには、(このページを読んでから)以下を参照してください。
既存のコンポーネントをコピーし、必要な変更を行うことが、開発を始めるうえで最も簡単な方法です。独自のコンポーネントを作成し、それを段落システムに追加する方法については、以下を参照してください。
- コンポーネント開発(主にタッチ操作対応 UI)
パブリッシュインスタンスへのコンポーネントの移動 moving-components-to-the-publish-instance
コンテンツをレンダリングするコンポーネントは、コンテンツと同じ AEM インスタンスにデプロイする必要があります。したがって、オーサーインスタンス上でページをオーサリングおよびレンダリングするために使用するすべてのコンポーネントを、パブリッシュインスタンスにデプロイする必要があります。デプロイすると、コンポーネントを使用して、アクティブ化されたページをレンダリングできるようになります。
コンポーネントをパブリッシュインスタンスに移動するには、次のツールを使用します。
- コンポーネントをパッケージに追加して、別の AEM インスタンスに移動するには、パッケージマネージャーを使用します。
- コンポーネントをレプリケートするには、ツリーをアクティベートのレプリケーションツールを使用します。
最初から認識するコンポーネント components-to-be-aware-of-from-the-start
-
ページ:
- AEM には ページ コンポーネント(
cq:Page
)があります。 - このコンポーネントは、コンテンツ管理にとって重要なリソースです。
- ページコンポーネントは、web サイトのコンテンツを保持する web ページに対応しています。
- AEM には ページ コンポーネント(
-
段落システム:
- 段落システムは、web サイトの重要な構成要素であり、段落のリストを管理します。実際のコンテンツを格納する個々のコンポーネントを保持し、構造化するために使用されます。
- 段落システム内で、段落を作成、移動、コピーおよび削除できます。
- 特定の段落システム内で使用可能にするコンポーネントを選択することもできます。
- 標準インスタンス内で使用できる段落システムには様々なものがあります(例:
parsys
、[responsivegrid](/docs/experience-manager-65/sites-authoring/responsive-layout.md)
)。
構造 structure
AEM コンポーネントの構造は強力で、柔軟性があります。主な考慮事項は次のとおりです。
- リソースタイプ
- コンポーネント定義
- コンポーネントのプロパティおよび子ノード
- ダイアログ
- デザインダイアログ
- 使用可能なコンポーネント
- コンポーネントおよびコンポーネントによって作成されるコンテンツ
リソースタイプ resource-type
構造の重要な構成要素となるのが、リソースタイプです。
- コンテンツの構造は意図を宣言します。
- リソースタイプはその意図を実装します。
このような抽象化をすることで、時間の経過と共にルックアンドフィールが変化しても、意図が変わることはありません。
コンポーネント定義 component-definition
コンポーネントの基本 component-basics
コンポーネントの定義は次のように分解できます。
-
AEM コンポーネントは、Sling に基づいています。
-
AEM コンポーネントは、(通常は)次の場所に配置されます。
- HTL:
/libs/wcm/foundation/components
- JSP:
/libs/foundation/components
- HTL:
-
プロジェクトまたはサイトに固有のコンポーネントは、(通常は)次の場所に配置されます。
/apps/<myApp>/components
-
AEM の標準コンポーネントは、
cq:Component
として定義され、次の主要な構成要素を持ちます。-
jcr プロパティ:
jcr プロパティのリスト:これらのプロパティは変数です。
cq:Component
の定義では、コンポーネントノード、コンポーネントノードのプロパティおよびサブノードの基本構造が規定されていますが、プロパティによっては、オプションとして使用できるものもあります。 -
リソース:
コンポーネントが使用する静的要素を定義します。
-
スクリプト:
コンポーネントの結果インスタンスの動作を実装するために使用されます。
-
-
ルートノード:
<mycomponent> (cq:Component)
- コンポーネントの階層ノード
-
重要なプロパティ:
-
jcr:title
- コンポーネントのタイトル。例えば、コンポーネントブラウザーまたはサイドキック内のコンポーネントリストに示す際のラベルとして使用されます。 -
jcr:description
- コンポーネントの説明。コンポーネントブラウザーまたはサイドキック内でマウスを上に置くと表示されるヒントとして使用できます。 -
クラシック UI:
icon.png
- このコンポーネントのアイコン。thumbnail.png
- このコンポーネントを段落システム内にリストする場合に表示される画像。
-
タッチ UI
- 詳しくは、タッチ UI のコンポーネントアイコンの節を参照してください。
-
-
重要な子ノード:
-
cq:editConfig (cq:EditConfig)
- コンポーネントの編集プロパティを定義し、コンポーネントをコンポーネントブラウザーに表示できるようにします。メモ:コンポーネントにダイアログがある場合は、cq:editConfig が存在しなくても、コンポーネントは自動的にコンポーネントブラウザーまたはサイドキックに表示されます。
-
cq:childEditConfig (cq:EditConfig)
- 独自のcq:editConfig
を定義しない子コンポーネントの作成者 UI の側面を制御します。 -
タッチ操作対応 UI:
cq:dialog
(nt:unstructured
) - このコンポーネントのダイアログ。ユーザーがコンポーネントを設定したり、コンテンツを編集したりできるインターフェイスを定義します。cq:design_dialog
(nt:unstructured
) - このコンポーネントのデザイン編集
-
クラシック UI:
dialog
(cq:Dialog
) - このコンポーネントのダイアログ。ユーザーがコンポーネントを設定したり、コンテンツを編集したりできるインターフェイスを定義します。design_dialog
(cq:Dialog
) - このコンポーネントのデザイン編集。
-
タッチ UI のコンポーネントアイコン component-icon-in-touch-ui
コンポーネントのアイコンまたは省略形は、デベロッパーがコンポーネントを作成する際にコンポーネントの JCR プロパティで定義します。これらのプロパティは、次の順番で評価され、最初に見つかった有効なプロパティが使用されます。
-
cq:icon
- コンポーネントブラウザーで表示するための Coral UI ライブラリの標準的なアイコンを指定する String プロパティ- Coral アイコンの HTML 属性の値を使用します。
-
abbreviation
- コンポーネントブラウザーでのコンポーネント名の省略形をカスタマイズするための String プロパティ-
省略形は最大 2 文字までにする必要があります。
-
空の文字列が指定されると、
jcr:title
プロパティの最初の 2 文字を使用して省略形が作成されます。- 例えば、「Image」の場合は「Im」になります。
- ローカライズされたタイトルが省略形の作成に使用されます。
-
省略形は、コンポーネントに
abbreviation_commentI18n
プロパティがある場合にのみ翻訳されます。これは、翻訳ヒントとして使用されます。
-
-
cq:icon.png
またはcq:icon.svg
- コンポーネントブラウザーに表示される、このコンポーネントのアイコン- 20 x 20 ピクセルは、標準的なコンポーネントのアイコンのサイズです。
- 大きいアイコンはクライアントサイドで縮小されます。
- お勧めの色は、RGB(112、112、112)、つまり #707070 です。
- 標準的なコンポーネントアイコンの背景は、透明です。
.png
および.svg
ファイルのみがサポートされます。- Eclipse プラグインを使用してファイルシステムから読み込む場合、例えば
_cq_icon.png
や_cq_icon.svg
のように、ファイル名をエスケープする必要があります。 - 両方が存在する場合は、
.png
が.svg
よりも優先されます
- 20 x 20 ピクセルは、標準的なコンポーネントのアイコンのサイズです。
コンポーネントで上述のプロパティ(cq:icon
、abbreviation
、cq:icon.png
または cq:icon.svg
)が見つからない場合:
- システムは、
sling:resourceSuperType
プロパティに続くスーパーコンポーネント上の同じプロパティを検索します。 - スーパーコンポーネントレベルで見つからないか空の省略形が見つかった場合、システムは現在のコンポーネントの
jcr:title
プロパティの最初の文字から省略形を作成します。
スーパーコンポーネントからアイコンの継承をキャンセルするために、コンポーネントで空の abbreviation
プロパティを設定すると、デフォルトの動作に戻ります。
コンポーネントコンソールには、特定のコンポーネントのアイコンの定義方法が表示されます。
SVG アイコンの例 svg-icon-example
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "https://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg version="1.1" id="Layer_1" xmlns="https://www.w3.org/2000/svg" xmlns:xlink="https://www.w3.org/1999/xlink" x="0px" y="0px"
width="20px" height="20px" viewBox="0 0 20 20" enable-background="new 0 0 20 20" xml:space="preserve">
<ellipse cx="5" cy="5" rx="3" ry="3" fill="#707070"/>
<ellipse cx="15" cy="5" rx="4" ry="4" fill="#707070"/>
<ellipse cx="5" cy="15" rx="5" ry="5" fill="#707070"/>
<ellipse cx="15" cy="15" rx="4" ry="4" fill="#707070"/>
</svg>
コンポーネントのプロパティおよび子ノード properties-and-child-nodes-of-a-component
コンポーネントの定義に必要なノードまたはプロパティの多くは、両方の UI に共通です。コンポーネントがどちらの環境でも機能できるよう、相違点の独立性は確保されています。
コンポーネントはタイプ cq:Component
のノードで、次のプロパティと子ノードがあります。
テキスト コンポーネント(どちらかのバージョン)を見ると、次の要素が表示されます。
-
HTL(
/libs/wcm/foundation/components/text
) -
JSP(
/libs/foundation/components/text
)
特に重要なプロパティを次に示します。
jcr:title
- コンポーネントのタイトル。コンポーネントブラウザーまたはサイドキック内のコンポーネントリストに表示されたりするコンポーネントの識別に使用できます。jcr:description
- コンポーネントの説明。サイドキック内のコンポーネントリストでマウスオーバーヒントとして使用できます。sling:resourceSuperType
- (定義のオーバーライドによる)コンポーネントの拡張時に、継承パスを示します。
特に重要な子ノードを次に示します。
-
cq:editConfig
(cq:EditConfig
) - 視覚的な側面を制御します。例えば、バーやウィジェットの外観を定義したり、カスタマイズしたコントロールを追加したりできます。 -
cq:childEditConfig
(cq:EditConfig
) - 独自の定義を持たない子コンポーネントの視覚的な側面を制御します。 -
タッチ操作対応 UI:
cq:dialog
(nt:unstructured
)- このコンポーネントのコンテンツ編集に使用するダイアログを定義します。cq:design_dialog
(nt:unstructured
)- このコンポーネントのデザイン編集オプションを指定します。
-
クラシック UI:
dialog
(cq:Dialog
)- このコンポーネントのコンテンツを編集するためのダイアログを定義します(クラシック UI に固有)。design_dialog
(cq:Dialog
) - このコンポーネントのデザイン編集オプションを指定します。icon.png
- サイドキック内のコンポーネントのアイコンとして使用されるグラフィックファイルthumbnail.png
- サイドキックからコンポーネントをドラッグしている間、そのサムネールとして使用されるグラフィックファイル
ダイアログ dialogs
ダイアログは、コンポーネントの主要な要素の一つです。作成者がコンポーネントを設定し、必要情報を提供するためのインターフェイスをダイアログが備えているからです。
コンポーネントの複雑さに応じて、ダイアログには 1 つ以上のタブが必要です。これは、ダイアログを簡潔にし、必要情報フィールドを分類するためです。
ダイアログの定義は UI に固有です。
- 互換性を保つために、タッチ操作対応 UI 用のダイアログが定義されていない場合、タッチ操作対応 UI でクラシック UI ダイアログの定義を使用できます。
- クラシック UI 用のダイアログのみが定義されているコンポーネントを拡張または変換するために、AEM 最新化ツール も用意されています。
-
タッチ操作対応 UI
-
cq:dialog
(nt:unstructured
)ノード:-
このコンポーネントのコンテンツ編集に使用するダイアログを定義します。
-
タッチ操作対応 UI 専用です。
-
Granite UI コンポーネントを使用して定義されます。
-
標準の Sling コンテンツ構造として
sling:resourceType
プロパティを持ちます。 -
helpPath
プロパティを指定できます。このプロパティでは、「ヘルプ」アイコン(「?
」アイコン)が選択された場合に表示される状況依存型ヘルプリソースを定義します(絶対パスまたは相対パス)。- 既成のコンポーネントでは多くの場合、ドキュメントのページが参照されます。
helpPath
が指定されていない場合、デフォルトのURL(ドキュメントの概要ページ)が表示されます。
-
ダイアログ内で、個々のフィールドは次のように定義されます。
-
-
クラシック UI
-
dialog
(cq:Dialog
)ノード-
このコンポーネントのコンテンツ編集に使用するダイアログを定義します。
-
クラシック UI 専用です。
-
ExtJS ウィジェットを使用して定義されます。
-
ExtJS を参照する
xtype
プロパティを持ちます。 -
helpPath
プロパティを指定できます。このプロパティでは、「ヘルプ」ボタンが選択された場合に表示される状況依存型ヘルプリソースを定義します(絶対パスまたは相対パス)。- 既成のコンポーネントでは多くの場合、ドキュメントのページが参照されます。
helpPath
が指定されていない場合、デフォルトのURL(ドキュメントの概要ページ)が表示されます。
-
ダイアログ内で、個々のフィールドは次のように定義されます。
クラシックダイアログボックス内では、次のことが可能です。
- ダイアログを
cq:Dialog
として作成できます。これはテキストコンポーネント内のダイアログと同様に、タブを 1 つだけ含みます。複数のタブが必要な場合は、textimage コンポーネントと同様に、ダイアログをcq:TabPanel
として定義できます。 cq:WidgetCollection
(items
)を入力フィールド(cq:Widget
)や追加タブ(cq:Widget
)のベースとして使用します。この階層は、拡張することが可能です。
-
デザインダイアログ design-dialogs
デザインダイアログは、コンテンツの編集や設定に使用されるダイアログに似ていますが、そのコンポーネントのデザインの詳細を作成者が設定できるようにするインターフェイスを提供します。
デザインダイアログはデザインモードで使用可能ですが、必ずしもすべてのコンポーネントに必要なわけではありません。例えば、タイトル コンポーネントと 画像 コンポーネントにはどちらもデザインダイアログがありますが、テキスト コンポーネントにはありません。
段落システム(parsys など)用のデザインダイアログは特殊なケースで、ユーザーはこのデザインダイアログを使用して、特定の他のコンポーネントをページ上で(コンポーネントブラウザーまたはサイドキックから)選択することができます。
コンポーネントを段落システムに追加 adding-your-component-to-the-paragraph-system
コンポーネントを定義した上で、使用可能にする必要があります。コンポーネントを段落システムで使用可能にするには、次のどちらかの方法を実行します。
-
ページに対してデザインモードを開き、必要なコンポーネントを有効にします。
-
必要なコンポーネントを次の場所にあるテンプレート定義の
components
プロパティに追加します。/etc/designs/<*yourProject*>/jcr:content/<*yourTemplate*>/par
例:
/etc/designs/geometrixx/jcr:content/contentpage/par
コンポーネントおよびコンポーネントによって作成されるコンテンツ components-and-the-content-they-create
次のページに タイトル コンポーネントのインスタンスを作成して設定する場合:<content-path>/Prototype.html
-
タッチ操作対応 UI
-
クラシック UI
ここで、リポジトリ内に作成されたコンテンツの構造を確認できます。
特に、タイトル コンポーネントの実際のテキストに着目した場合:
-
(両方の UI の)定義でプロパティ
name
=./jcr:title
となっている/libs/foundation/components/title/cq:dialog/content/items/column/items/title
/libs/foundation/components/title/dialog/items/title
-
この定義によって、コンテンツ内に作成者のコンテンツを保持する
jcr:title
というプロパティが生成されます。
定義されるプロパティは、個々の定義によって異なります。上記よりも複雑になる場合がありますが、同じ基本原則に従っています。
コンポーネントの階層と継承 component-hierarchy-and-inheritance
AEM 内のコンポーネントは、次の 3 つの異なる階層の影響を受けます。
-
リソースタイプ階層
プロパティ
sling:resourceSuperType
でコンポーネントを拡張する場合に使用されます。これにより、コンポーネントの継承ができるようになります。例えば、テキストコンポーネントは標準コンポーネントから様々な属性を継承します。- スクリプト(Sling によって解決)
- ダイアログ
- 説明(サムネール画像、アイコンなどを含む)
-
コンテナ階層
子コンポーネントに設定を適用するために使用されます。parsys シナリオで最もよく使用されています。
例えば、編集バーのボタン、コントロールセットのレイアウト(編集バー、ロールオーバー)、ダイアログのレイアウト(インライン、浮動)の設定を親コンポーネントで定義して、子コンポーネントに適用できます。
cq:editConfig
およびcq:childEditConfig
の(編集機能に関する)設定が適用されます。 -
階層を含める
インクルード階層実行時にインクルードのシーケンスによって適用されます。
この階層は、デザイナーによって使用され、レンダリングの様々なデザイン側面、特にレイアウト情報、CSS 情報、parsys で使用可能なコンポーネントの基礎として機能します。
編集動作 edit-behavior
この節では、コンポーネントの編集動作の設定方法について説明します。コンポーネントで使用可能なアクション、インプレースエディターの特性、コンポーネント上のイベントに関連するリスナーなどの属性が含まれます。
固有の相違点は多少ありますが、設定はタッチ対応 UI とクラシック UI の両方に共通です。
コンポーネントの編集動作を設定するには、タイプ cq:editConfig
の cq:EditConfig
ノードをコンポーネントノード(タイプ cq:Component
)の下に追加し、特定のプロパティと子ノードを追加します。使用可能なプロパティと子ノードを次に示します。
-
-
cq:actions
(String array
):コンポーネントで実行できるアクションを定義します。 -
cq:layout
(String
):クラシック UI でのコンポーネントの編集方法を定義します。 -
cq:dialogMode
(String
):クラシック UI でのコンポーネントダイアログの開き方を定義します。- タッチ操作対応 UI のダイアログは、デスクトップモードでは常に浮動し、モバイルでは自動的に全画面表示として開きます。
-
cq:emptyText
(String
):視覚的なコンテンツが存在しない場合に表示するテキストを定義します。 -
cq:inherit
(Boolean
):欠落している値をその継承元のコンポーネントから継承するかどうかを定義します。 -
dialogLayout
(String):ダイアログの開き方を定義します。
-
-
-
cq:dropTargets
(ノードタイプnt:unstructured
):コンテンツファインダーのアセットからのドロップを受け入れ可能なドロップターゲットのリストを定義します。- 複数のドロップターゲットはクラシック UI でのみ使用できます。
- タッチ操作対応 UI では、単一のドロップターゲットが許可されます。
-
cq:actionConfigs
(ノードタイプnt:unstructured
):cq:actions リストに追加する新しいアクションのリストを定義します。 -
cq:formParameters
(ノードタイプnt:unstructured
):ダイアログフォームに追加するその他のパラメーターを定義します。 -
cq:inplaceEditing
(ノードタイプcq:InplaceEditingConfig
):コンポーネントのインプレース編集設定を定義します。 -
cq:listeners
(ノードタイプcq:EditListenersConfig
):コンポーネントでアクションを実行する前後の処理を定義します
-
<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
cq:actions="[edit]"
cq:dialogMode="floating"
cq:layout="editbar"
jcr:primaryType="cq:EditConfig">
<cq:listeners
jcr:primaryType="cq:EditListenersConfig"
afteredit="REFRESH_PAGE"/>
</jcr:root>
リポジトリには、既存の設定が多数あります。ユーザーは、特定のプロパティや子ノードを簡単に検索できます。
-
cq:editConfig
ノードのプロパティ、例えばcq:actions
を探すには、CRXDE Lite のクエリツールで、次の XPath クエリ文字列を指定して、検索を実行します。//element(cq:editConfig, cq:EditConfig)[@cq:actions]
-
cq:editConfig
の子ノード、例えばタイプcq:DropTargetConfig
のcq:dropTargets
を探すには、CRXDE Lite のクエリツールで、次の XPath クエリ文字列を指定して、検索を実行します。//element(cq:dropTargets, cq:DropTargetConfig)
コンポーネントプレースホルダー component-placeholders
コンポーネントは、コンテンツがない場合でも必ず、作成者に表示される一部の HTML をレンダリングする必要があります。そうしないと、エディターのインターフェイスから視覚的に消えてしまい、技術的には存在しても、ページやエディターには表示されなくなります。このような場合、作成者は空のコンポーネントを選択して操作することができません。
このため、ページがページエディターでレンダリングされる(WCM モードが edit
または preview
の場合)際に、コンポーネントは、表示された出力をレンダリングしない限り、プレースホルダーをレンダリングする必要があります。
プレースホルダーの一般的な HTML マークアップは次のとおりです。
<div class="cq-placeholder" data-emptytext="Component Name"></div>
上記のプレースホルダー HTML をレンダリングする一般的な HTL スクリプトは次のとおりです。
<div class="cq-placeholder" data-emptytext="${component.properties.jcr:title}"
data-sly-test="${(wcmmode.edit || wcmmode.preview) && isEmpty}"></div>
前の例では、isEmpty
は、コンポーネントにコンテンツがなくて作成者には見えない場合にのみ true になる変数です。
繰り返しを避けるために、アドビは、これらのプレースホルダーに、コアコンポーネントが提供するような HTL テンプレートを使用することをコンポーネントの実装者に推奨します。
その後、前のリンクでのテンプレートの使用は、次の HTL 行で行います。
<sly data-sly-use.template="core/wcm/components/commons/v1/templates.html"
data-sly-call="${template.placeholder @ isEmpty=!model.text}"></sly>
前の例では、model.text
はコンテンツが含まれていて表示されている場合にのみ true になる変数です。
このテンプレートの使用例は、コアコンポーネント(タイトルコンポーネントなど)で確認できます。
cq:EditConfig プロパティを使用した設定 configuring-with-cq-editconfig-properties
cq:actions cq-actions
cq:actions
プロパティ(String array
)では、コンポーネントで実行できるアクションを 1 個から数個定義します。設定に使用できる値を以下に示します。
次の設定では、編集ボタン、スペーサー、削除ボタンおよび挿入ボタンがコンポーネントの編集バーに追加されます。
<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
cq:actions="[edit,-,delete,insert]"
cq:layout="editbar"
jcr:primaryType="cq:EditConfig"/>
次の設定では、「Inherited Configurations from Base Framework」というテキストがコンポーネントの編集バーに追加されます。
<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
cq:actions="[text:Inherited Configurations from Base Framework]"
cq:layout="editbar"
jcr:primaryType="cq:EditConfig"/>
cq:layout(クラシック UI のみ) cq-layout-classic-ui-only
cq:layout
プロパティ(String
)では、クラシック UI でコンポーネントを編集可能にする方法を定義します。使用可能な値を次に示します。
次の設定では、編集ボタンがコンポーネントの編集バーに追加されます。
<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
cq:actions="[edit]"
cq:layout="editbar"
jcr:primaryType="cq:EditConfig">
</jcr:root>
cq:dialogMode(クラシック UI のみ) cq-dialogmode-classic-ui-only
コンポーネントを編集ダイアログにリンクできます。cq:dialogMode
プロパティ(String
)では、クラシック UI でコンポーネントダイアログを開く方法を定義します。使用可能な値を次に示します。
次の設定では、編集ボタンを含む編集バーと浮動ダイアログが定義されます。
<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
cq:actions="[edit]"
cq:dialogMode="floating"
cq:layout="editbar"
jcr:primaryType="cq:EditConfig">
</jcr:root>
cq:emptyText cq-emptytext
cq:emptyText
プロパティ(String
)では、視覚的なコンテンツが存在しない場合に表示するテキストを定義します。デフォルト値は Drag components or assets here
です。
cq:inherit cq-inherit
cq:inherit
プロパティ(boolean
)では、欠落している値をその継承元のコンポーネントから継承するかどうかを定義します。デフォルト値は false
です。
dialogLayout dialoglayout
dialogLayout
プロパティは、デフォルトのダイアログの開き方を定義します。
- 値が
fullscreen
の場合、ダイアログは全画面で開きます。 - 値が空かプロパティがない場合、デフォルトでは通常どおりにダイアログが開きます。
- ユーザーは、ダイアログ内で全画面モードを常に切り替えることができます。
- クラシック UI には適用されません。
cq:EditConfig の子ノードを使用した設定 configuring-with-cq-editconfig-child-nodes
cq:dropTargets cq-droptargets
cq:dropTargets
ノード(ノードタイプ nt:unstructured
)では、コンテンツファインダーからドラッグしたアセットからのドロップを受け入れ可能なドロップターゲットのリストを定義します。これは、タイプ cq:DropTargetConfig
のノードのコレクションとして機能します。
タイプ cq:DropTargetConfig
のそれぞれの子ノードでは、コンポーネントのドロップターゲットを定義します。ノード名は重要です。ノード名は、JSP で次のように使用して、有効なドロップターゲットである DOM 要素に割り当てられる CSS クラス名を生成する必要があるからです。
<drop target css class> = <drag and drop prefix> +
<node name of the drop target in the edit configuration>
この <drag and drop prefix>
は、Java™ プロパティで定義されます。
com.day.cq.wcm.api.components.DropTarget.CSS_CLASS_PREFIX
。
例えば、JSP では、ダウンロードコンポーネント
(/libs/foundation/components/download/download.jsp
)のクラス名は次のように定義されます。file
は、ダウンロードコンポーネントの編集設定内のドロップターゲットのノード名です。
String ddClassName = DropTarget.CSS_CLASS_PREFIX + "file";
タイプ cq:DropTargetConfig
のノードには、次のプロパティが必要です。
次の設定は、ダウンロードコンポーネントから取得したものです。この設定では、media
グループの任意のアセット(MIME タイプが任意の文字列でよい)をコンテンツファインダーからコンポーネントにドロップすることが可能です。ドロップを行うと、コンポーネントのプロパティ fileReference
が更新されます。
<cq:dropTargets jcr:primaryType="nt:unstructured">
<file
jcr:primaryType="cq:DropTargetConfig"
accept="[.*]"
groups="[media]"
propertyName="./fileReference"/>
</cq:dropTargets>
cq:actionConfigs(クラシック UI のみ) cq-actionconfigs-classic-ui-only
cq:actionConfigs
ノード(ノードタイプ nt:unstructured
)では、cq:actions
プロパティで定義されたリストに追加する新しいアクションのリストを定義します。cq:actionConfigs
のそれぞれの子ノードでは、ウィジェットを定義することにより新しいアクションを定義します。
次の設定例では、(クラシック UI 用の区切り文字を持つ)新しいボタンを定義しています。
-
xtype
tbseparator
で定義される区切り文字。- クラシック UI でのみ使用されます。
- タッチ操作対応 UI では xtype が無視されるので、この定義は無視されます(また、タッチ操作対応 UI ではアクションツールバーの構造が異なるので、区切り文字は不要です)。
-
ハンドラー関数
CQ_collab_forum_openCollabAdmin()
を実行する「コメントを管理」という名前のボタン。
<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0" xmlns:nt="https://www.jcp.org/jcr/nt/1.0"
cq:actions="[EDIT,COPYMOVE,DELETE,INSERT]"
jcr:primaryType="cq:EditConfig">
<cq:actionConfigs jcr:primaryType="nt:unstructured">
<separator0
jcr:primaryType="nt:unstructured"
xtype="tbseparator"/>
<manage
jcr:primaryType="nt:unstructured"
handler="function(){CQ_collab_forum_openCollabAdmin();}"
text="Manage comments"/>
</cq:actionConfigs>
</jcr:root>
cq:formParameters cq-formparameters
cq:formParameters
ノード(ノードタイプ nt:unstructured
)では、ダイアログフォームに追加するその他のパラメーターを定義します。各プロパティは、Form パラメーターにマップされます。
次の設定では、値 photos/primary
が設定された name
という名前のパラメーターがダイアログフォームに追加されます。
<cq:formParameters
jcr:primaryType="nt:unstructured"
name="photos/primary"/>
cq:inplaceEditing cq-inplaceediting
cq:inplaceEditing
ノード(ノードタイプ cq:InplaceEditingConfig
)では、コンポーネントのインプレース編集設定を定義します。このノードは、次のプロパティを持つことができます。
次の設定では、コンポーネントのインプレース編集が可能になり、テキストエディターとして plaintext
が定義されます。
<cq:inplaceEditing
jcr:primaryType="cq:InplaceEditingConfig"
active="{Boolean}true"
editorType="plaintext"/>
cq:listeners cq-listeners
cq:listeners
ノード(ノードタイプ cq:EditListenersConfig
)では、コンポーネントでアクションを実行する前後の処理を定義します。次の表では、使用する可能性のあるプロパティ値の定義を示します。
REFRESH_INSERTED
および REFRESH_SELFMOVED
ハンドラーは、クラシック UI でのみ使用できます。cq:listeners
ノードでプロパティとして定義されるアクションに一定の制限があります。-
コンポーネントがネストされている場合、次のプロパティの値を
REFRESH_PAGE
にする 必要があります 。>aftermove
aftercopy
イベントハンドラーを実装するときは、カスタム実装を組み込むことができます。次に例を示します(project.customerAction
は静的メソッドです)。
afteredit = "project.customerAction"
次の例は、REFRESH_INSERTED
設定と同等です。
afterinsert="function(path, definition) { this.refreshCreated(path, definition); }"
CQ.wcm.EditBar
および CQ.wcm.EditRollover
ウィジェットのドキュメントに記載されている「before<action>
イベントおよび after<action>
イベント」のセクションを参照してください。次の設定では、コンポーネントを削除、編集、挿入または移動した後にページが更新されます。
<cq:listeners
jcr:primaryType="cq:EditListenersConfig"
afterdelete="REFRESH_PAGE"
afteredit="REFRESH_PAGE"
afterinsert="REFRESH_PAGE"
afterMove="REFRESH_PAGE"/>