コンポーネントリファレンスガイド components-reference-guide

コンポーネントは、AEM でエクスペリエンスを構築する際の中心です。コアコンポーネントと AEM プロジェクトアーキタイプを使うと、堅牢な既製のコンポーネントのツールセットを簡単に使い始めることができます。WKND チュートリアルでは、デベロッパーがこれらのツールの使用方法と、AEM サイトを作成するためのカスタムコンポーネントの作成方法を学びます。

WKND チュートリアルでは、ほとんどの使用例をカバーしているので、このドキュメントはこれらのリソースを補完する目的でのみ提供されます。AEM でのコンポーネントの構造化および設定方法に関する詳細な技術的詳細を説明するものであり、入門用ガイドとしての意図されたものではありません。

概要 overview

この節では、独自コンポーネントの開発時に知っておくべき詳細の導入段階として、基本的な概念と注意点について説明します。

計画 planning

実際にコンポーネントの設定やコーディングを開始する前に、次の点について理解する必要があります。

既存コンポーネントの再利用 reusing-components

全く新しいコンポーネントの作成に時間を費やす前に、既存のコンポーネントのカスタマイズや拡張を検討してください。コアコンポーネントは、柔軟で堅牢かつ十分にテストされた実稼働用コンポーネントのセットを提供します。

コアコンポーネントの拡張 extending-core-components

また、コアコンポーネントは、明確なカスタマイズパターンを備えており、独自のプロジェクトのニーズに合わせることもできます。

コンポーネントのオーバーレイ overlying-components

コンポーネントは、検索パスロジックに基づいたオーバーレイを使用して再定義することもできます。ただし、その場合 Sling Resource Merger が呼び出されないので、/apps でオーバーレイ全体を定義する必要があります。

コンポーネントダイアログの拡張 extending-component-dialogs

Sling Resource Merger を使用し、sling:resourceSuperType プロパティを定義して、コンポーネントダイアログをオーバーライドすることもできます。

つまり、ダイアログ全体を再定義するのとは対照的に、再定義する必要があるのは相違点だけです。

コンテンツのロジックとマークアップのレンダリング content-logic-and-rendering-markup

コンポーネントは HTML を使用してレンダリングされます。コンポーネントでは、必要なコンテンツを取得して、オーサー環境とパブリッシュ環境の両方で必要に応じてレンダリングするために必要な HTML を定義しなければなりません。

マークアップおよびレンダリングを行うコードと、コンポーネントのコンテンツ選択に関するロジックを制御するコードは、分離しておくことをお勧めします。

この方法をサポートするテンプレート言語が HTL です。HTL では、基盤となるビジネスロジックを定義するときにのみプログラミング言語を使用します。このメカニズムは、特定のビューに対して呼び出されるコードを強調表示し、必要に応じて、同じコンポーネントの異なるビューに対して特定のロジックを使用できるようにします。

この（オプション）ロジックは様々な方法で実装でき、特定のコマンドを使用して HTL から呼び出します。

コンポーネント構造 structure

AEM コンポーネントの構造は強力で柔軟性があります。以下は主な部分です。

リソースタイプ resource-type

構造の重要な構成要素となるのが、リソースタイプです。

このような抽象化をすることで、時間の経過と共にルックアンドフィールが変化しても、意図が変わることはありません。

コンポーネント定義 component-definition

コンポーネントの定義は次のように分解できます。

重要なプロパティ vital-properties

コンポーネントアイコン component-icon

コンポーネントのアイコンまたは省略形は、デベロッパーがコンポーネントを作成する際にコンポーネントの JCR プロパティで定義します。これらのプロパティは、次の順番で評価され、最初に見つかった有効なプロパティが使用されます。

コンポーネントで上述のプロパティ（cq:icon、abbreviation、cq:icon.png または cq:icon.svg）が見つからない場合：

スーパーコンポーネントからアイコンの継承をキャンセルするために、コンポーネントで空の 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 のノードで、次のプロパティと子ノードがあります。

テキスト ​コンポーネントを見ると、次のいくつかの要素が表示されます。

特に重要なプロパティを次に示します。

特に重要な子ノードを次に示します。

ダイアログ dialogs

ダイアログは、コンポーネントの主要な要素の 1 つです。作成者がコンテントページでコンポーネントを設定し、必要情報を提供するためのインターフェイスをダイアログが備えているからです。コンテンツ作成者がコンポーネントとやり取りする方法の詳細については、オーサリングドキュメントを参照してください。

コンポーネントの複雑さに応じて、ダイアログに 1 つ以上のタブが必要になる場合があります。

AEM コンポーネントのダイアログ：

ダイアログ内で、個々のフィールドは次のように定義されます。

デザインダイアログ design-dialogs

デザインダイアログは、コンテンツの編集と構成に使用されるダイアログに似ていますが、テンプレート作成者がページテンプレート上のそのコンポーネントのデザインの詳細をプロ構成および提供するためのインターフェイスを提供します。次に、コンテンツ作成者がページテンプレートを使用してコンテンツページを作成します。テンプレートの作成方法の詳細については、テンプレートドキュメントを参照してください。

ページテンプレートの編集時にはデザインダイアログが使用されます。ただし、すべてのコンポーネントで必要とされるわけではありません。例えば、タイトル ​と​ 画像コンポーネント ​の両方にデザインのダイアログがありますが、ソーシャルメディア共有コンポーネント ​はありません。

Coral UI と Granite UI coral-and-granite

AEM のルックアンドフィールは Coral UI と Granite UI で定義されています。

Granite UI で提供される幅広い基本ウィジェットは、オーサー環境でダイアログを作成するために使用されます。必要な場合には、選択したウィジェットを拡張し、独自のウィジェットを作成することができます。

以下のリソースについても参照してください。

ダイアログフィールドのカスタマイズ customizing-dialog-fields

コンポーネントダイアログで使用するウィジェットを作成するには、Granite UI フィールドコンポーネントを作成する必要があります。

ダイアログをフォーム要素の単純なコンテナと見なす場合、ダイアログコンテンツの主なコンテンツをフォームフィールドとして表示することもできます。新しいフォームフィールドを作成するには、リソースタイプを作成する必要があります。これは、コンポーネントの作成と同じです。この作業を容易にするために、Granite UI は、sling:resourceSuperType を使用して以下を継承する汎用フィールドコンポーネントを提供しています。

/libs/granite/ui/components/coral/foundation/form/field

より正確に言えば、Granite UI には、ダイアログ（より一般的に言えばフォーム）での使用に適した、幅広いフィールドコンポーネントが用意されています。

リソースタイプを作成したうえで、sling:resourceType プロパティで作成したリソースタイプを参照して、新しいノードをダイアログに追加することによって、フィールドをインスタンス化できます。

ダイアログフィールドへのアクセス access-to-dialog-fields

レンダリング条件（rendercondition）を使用して、ダイアログ内の特定のタブやフィールドへのアクセス権を持つユーザーを制御することもできます。以下に例を示します。

+ mybutton
  - sling:resourceType = granite/ui/components/coral/foundation/button
  + rendercondition
    - sling:resourceType = myapp/components/renderconditions/group
    - groups = ["administrators"]

コンポーネントの使用 using-components

コンポーネントを作成したら、それを使用できるようにする必要があります。コンポーネントを使用すると、コンポーネントの構造とリポジトリの結果として得られるコンテンツの構造との関連がかわります。

コンポーネントをテンプレートに追加する adding-your-component-to-the-template

コンポーネントを定義した上で、使用可能にする必要があります。コンポーネントをテンプレートで使用できるようにするには、テンプレートのレイアウトコンテナのポリシーでそのコンポーネントを有効にする必要があります。

テンプレートの作成方法の詳細については、テンプレートドキュメントを参照してください。

コンポーネントおよびコンポーネントによって作成されるコンテンツ components-and-the-content-they-create

次のページに​ タイトル ​コンポーネントのインスタンスを作成して設定する場合：/content/wknd/language-masters/en/adventures/extreme-ironing.html

ここで、リポジトリー内に作成されたコンテンツの構造を確認できます。

特に、タイトル ​コンポーネントの実際のテキストに着目した場合：

定義されるプロパティは、個々の定義によって異なります。上記よりも複雑になる場合がありますが、同じ基本原則に従っています。

コンポーネントの階層と継承 component-hierarchy-and-inheritance

AEM 内のコンポーネントは、リソースタイプの階層 ​の対象となります。プロパティでコンポーネントを拡張する場合に使用されます。sling:resourceSuperTypeこれにより、コンポーネントは別のコンポーネントから継承できます。

詳しくは、「コンポーネントの再利用」を参照してください。

編集動作 edit-behavior

この節では、コンポーネントの編集動作の設定方法について説明します。これには、コンポーネントに対して使用可能なアクションなどの属性、インプレースエディターの特性、コンポーネントに対するイベントに関連するリスナーも含まれます。

コンポーネントの編集動作を設定するには、タイプ cq:editConfig の cq:EditConfig ノードをコンポーネントノード（タイプ cq:Component）の下に追加し、特定のプロパティと子ノードを追加します。使用可能なプロパティと子ノードを次に示します。

AEM には、既存の設定が多数あります。CRXDE Lite のクエリツールを使用すると、特定のプロパティまたは子ノードを簡単に検索できます。

コンポーネントプレースホルダー 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-child-nodes

アセットをダイアログにドロップする - cq:dropTargets cq-droptargets

cq:dropTargets ノード（ノードタイプ nt:unstructured）では、コンテンツファインダーからドラッグしたアセットからのドロップを受け入れ可能なドロップターゲットを定義します。cq:DropTargetConfig 型のノードです。

タイプ cq:DropTargetConfig の子ノードでは、コンポーネントのドロップターゲットを定義します。

インプレース編集 - cq:inplaceEditing cq-inplaceediting

インプレースエディターを使用すると、ダイアログを開くことなく、コンテンツフロー内で直接コンテンツを編集できます。例えば、標準の​ テキスト ​と​ タイトル ​のコンポーネントには、どちらもインプレースエディターがあります。

インプレースエディターは、すべてのコンポーネントタイプで必要なものではありません。

cq:inplaceEditing ノード（ノードタイプ cq:InplaceEditingConfig）では、コンポーネントのインプレース編集設定を定義します。このノードは、次のプロパティを持つことができます。

次の設定では、コンポーネントのインプレース編集が可能になり、エディタータイプとして plaintext が定義されます。

    <cq:inplaceEditing
        jcr:primaryType="cq:InplaceEditingConfig"
        active="{Boolean}true"
        editorType="plaintext"/>

フィールドイベントの処理 - cq:listeners cq-listeners

ダイアログフィールドのイベントの処理は、カスタムクライアントライブラリのリスナーで行われます。

フィールドにロジックを挿入するには、以下を実行する必要があります。

これを実現するには、やり取りする、基になるウィジェットライブラリについて理解する必要があります。反応するイベントの識別については、Coral UI ドキュメントを参照してください

cq:listeners ノード（ノードタイプ cq:EditListenersConfig）では、コンポーネントでアクションを実行する前後の処理を定義します。次の表では、使用する可能性のあるプロパティ値の定義を示します。

イベントハンドラーを実装するときは、カスタム実装を組み込むことができます。次に例を示します（project.customerAction は静的メソッドです）。

afteredit = "project.customerAction"

次の例は、REFRESH_INSERTED 設定と同等です。

afterinsert="function(path, definition) { this.refreshCreated(path, definition); }"

次の設定では、コンポーネントを削除、編集、挿入または移動した後にページが更新されます。

    <cq:listeners
        jcr:primaryType="cq:EditListenersConfig"
        afterdelete="REFRESH_PAGE"
        afteredit="REFRESH_PAGE"
        afterinsert="REFRESH_PAGE"
        afterMove="REFRESH_PAGE"/>

フィールドの検証 field-validation

Granite UI および Granite UI ウィジェットでのフィールド検証は、foundation-validation API を使用して実行します。詳しくは、foundation-valdiationGranite のドキュメントを参照してください。

ダイアログの可用性の検出 dialog-ready

ダイアログが使用可能で準備が整っている場合にのみ実行する必要があるカスタム JavaScript がある場合は、dialog-ready イベントをリッスンする必要があります。

このイベントは、ダイアログが読み込まれて（または再度読み込まれて）、使用の準備ができたときにトリガーされます。つまり、ダイアログの DOM に変更（作成／更新）がある場合に必ずトリガーされます。

dialog-ready は、ダイアログ内のフィールドや類似のタスクをカスタマイズする JavaScript カスタムコードをフックするために使用できます。

プレビュー動作 preview-behavior

プレビューモードに切り替えると、ページが更新されなくても WCM モード Cookie が設定されます。

レンダリングが WCM モードの影響を受けるコンポーネントの場合は、明確にそのコンポーネントを更新し、この Cookie の値を使用するように定義する必要があります。

コンポーネントのドキュメント化 documenting-components

デベロッパーは、以下をすばやく把握できるようにコンポーネントドキュメントに簡単にアクセスしたいと考えます。

このため、コンポーネント内で既存のドキュメントマークダウンを利用できるようにするのは非常に簡単です。

これには、コンポーネント構造に README.md ファイルを配置するだけです。

その後、このマークダウンはコンポーネントコンソールに表示されるようになります。

サポートされているマークダウンは、コンテンツフラグメントの場合と同じです。