AEM コンポーネント - 基本

新しいコンポーネントの開発にとりかかる際は、その構造と設定の基本を理解する必要があります。

これには、標準的なセオリーを学び、標準 AEM インスタンスでのコンポーネントの実装を幅広く知ることが含まれます。AEM は新しい標準のタッチ操作対応 UI に変更されましたが、引き続きクラシック UI をサポートしているので、この後者のアプローチは少し複雑です。

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

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

• そもそも新しいコンポーネントで何をするか
  • 明確な仕様は、開発、テスト、引継ぎのあらゆる段階で役立ちます。
    詳細は時間と共に変化する可能性がありますが、仕様は更新可能です（ただし、変更箇所を記録しておく必要があります）。
    
• コンポーネントを一から作成する必要があるか、基本部分を既存のコンポーネントから継承できるか
  • 一から作成する必要があるとは限りません。
  • AEM には、別のコンポーネント定義から詳細を継承し、拡張できる仕組みがいくつか用意されています（オーバーライド、オーバーレイ、Sling Resource Merger など）。
• コンポーネントのコンテンツを選択または操作するためのロジックが必要か
  • ロジックは、ユーザーインターフェイス層から分離しておく必要があります。HTL はこれに対応した設計になっています。
    
• コンポーネントを CSS で書式設定する必要があるか
  • CSS による書式設定は、コンポーネント定義から分離しておく必要があります。外部の CSS ファイルを通じて HTML 要素を変更できるように、HTML 要素の命名規約を定義してください。
• 考慮すべきセキュリティ要素は何か
  • 詳しくは、セキュリティチェックリスト - 開発のベストプラクティスを参照してください。
    

コンポーネントの開発について本格的な検討を始める前に、作成者がどちらの UI を使用するかを知っておく必要があります。

• タッチ操作対応 UI
  AEM 5.6.0 でプレビューとして導入され、6.x で拡張された、標準のユーザーインターフェイスです。Adobe Marketing Cloud 向けの統合エクスペリエンスに基づき、Coral UI と Granite UI の基盤テクノロジーを使用しています。
  
• クラシック UI
  CQ 5.1 で導入された、ExtJS テクノロジーに基づくユーザーインターフェイスです。

詳しくは、UI インターフェイスに関するお客様向け推奨事項を参照してください。

タッチ操作対応 UI、クラシック UI または両方をサポートするようにコンポーネントを実装できます。標準インスタンスには、クラシック UI、タッチ操作対応 UI またはその両方に対応するようにあらかじめデザインされた既製のコンポーネントもあります。

このため、このページでは両 UI の基本と識別方法について説明します。

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

この方法をサポートするテンプレート言語が HTL です。HTL では、基盤となるビジネスロジックを定義するときにのみプログラミング言語を使用します。この（オプションの）ロジックは、特定のコマンドで HTL から呼び出されます。この仕組みでは、特定のビュー用に呼び出されるコードに焦点を当てることができるので、必要に応じて、同じコンポーネントの様々なビュー用のロジックを定義できます。

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 に使用される傾向があります。

UI の種類に応じた独自コンポーネントを作成するには、（このページを読んでから）以下を参照してください。

• タッチ操作対応 UI 用の AEM コンポーネント
• クラシック UI 用の AEM コンポーネント

既存のコンポーネントをコピーし、必要な変更をおこなうことが、開発を始めるうえで最も簡単な方法です。独自のコンポーネントを作成し、それを段落システムに追加する方法については、以下を参照してください。

• コンポーネント開発（主にタッチ操作対応 UI）

コンテンツをレンダリングするコンポーネントは、コンテンツと同じ AEM インスタンスにデプロイする必要があります。したがって、オーサーインスタンス上でページをオーサリングおよびレンダリングするために使用するすべてのコンポーネントを、パブリッシュインスタンスにデプロイする必要があります。デプロイすると、コンポーネントを使用して、アクティブ化されたページをレンダリングできるようになります。

コンポーネントをパブリッシュインスタンスに移動するには、次のツールを使用します。

• コンポーネントをパッケージに追加して、別の AEM インスタンスに移動するには、パッケージマネージャーを使用します。
• コンポーネントをレプリケートするには、「ツリーをアクティベート」レプリケーションツールを使用します。

• ページ：
  • AEM にはページコンポーネント（cq:Page）があります。
  • このコンポーネントは、コンテンツ管理にとって重要なリソースです。
  • ページコンポーネントは、Web サイトのコンテンツを保持する Web ページに対応しています。
• 段落システム：
  • 段落システムは、Web サイトの重要な構成要素であり、段落のリストを管理します。実際のコンテンツを格納する個々のコンポーネントを保持し、構造化するために使用されます。
  • 段落システム内で、段落を作成、移動、コピーおよび削除できます。
  • 特定の段落システム内で使用可能にするコンポーネントを選択することもできます。
  • 標準インスタンス内で使用できる段落システムにはさまざまなものがあります（parsys、responsivegrid など）。

AEM コンポーネントの構造は強力で、柔軟性があります。主な考慮事項は次のとおりです。

• リソースタイプ
  
• コンポーネント定義
  
• コンポーネントのプロパティおよび子ノード
  
• ダイアログ
  
• デザインダイアログ
  
• 使用可能なコンポーネント
  
• コンポーネントおよびコンポーネントによって作成されるコンテンツ

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

• コンテンツの構造は意図を宣言します。
  
• リソースタイプはその意図を実装します。

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

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

• AEM コンポーネントは、Sling に基づいています。
• AEM コンポーネントは、（通常は）次の場所に配置されます。
  • HTL：/libs/wcm/foundation/components 
    
  • JSP：/libs/foundation/components
    
• プロジェクトまたはサイトに固有のコンポーネントは、（通常は）次の場所に配置されます。
  • /apps/<myApp>/components
• AEM の標準コンポーネントは、cq:Component として定義され、次の主要な構成要素を持ちます。
  • jrc プロパティ：
    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） - このコンポーネントのデザイン編集。
      

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

1. cq:icon - コンポーネントブラウザーで表示するための Coral UI ライブラリの標準的なアイコンを指定する String プロパティ
   • Coral アイコンの HTML 属性の値を使用します。
2. abbreviation - コンポーネントブラウザーでのコンポーネント名の省略形をカスタマイズするための String プロパティ
   • 省略形は 最大2 文字までにする必要があります。
   • 空の文字列が指定されると、jcr:title プロパティの最初の 2 文字を使用して省略形が作成されます。
     • 例えば、「Image」の場合は「Im」になります。
     • ローカライズされたタイトルが省略形の作成に使用されます。
   • 省略形は、コンポーネントに abbreviation_commentI18n プロパティがある場合にのみ翻訳されます。これは、翻訳ヒントとして使用されます。
3. cq:icon.png または cq:icon.svg - コンポーネントブラウザーに表示される、このコンポーネントのアイコン
   • 20 x 20 pixel は、標準的なコンポーネントのアイコンのサイズです。
     • 大きいアイコンはクライアント側で縮小されます。
   • お勧めの色は、RGB（112、112、112）、つまり #707070 です。
   • 標準的なコンポーネントアイコンの背景は、透明です。
   • .png および .svg ファイルのみがサポートされます。
   • Eclipse プラグインを使用してファイルシステムから読み込む場合、例えば _cq_icon.png や _cq_icon.svg のように、ファイル名をエスケープする必要があります。
   • 両方が存在する場合は、.png が .svg よりも優先されます。

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

• システムは、sling:resourceSuperType プロパティに続くスーパーコンポーネント上の同じプロパティを検索します。
• スーパーコンポーネントレベルで見つからないか空の省略形が見つかった場合、システムは現在のコンポーネントの jcr:title プロパティの最初の文字から省略形を作成します。

スーパーコンポーネントからアイコンの継承をキャンセルするために、コンポーネントで空の abbreviation プロパティを設定すると、デフォルトの動作に戻ります。

コンポーネントコンソールには、特定のコンポーネントのアイコンの定義方法が表示されます。

コンポーネントの定義に必要なノードまたはプロパティの多くは、両方の UI に共通です。コンポーネントがどちらの環境でも機能できるよう、相違点の独立性は確保されています。

コンポーネントはタイプ cq:Component のノードで、以下のプロパティと子ノードがあります。

テキストコンポーネント（どちらかのバージョン）を見ると、次の要素が表示されます。

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

• 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 - サイドキックからコンポーネントをドラッグしている間、そのサムネールとして使用されるグラフィックファイル

ダイアログは、コンポーネントの主要な要素の一つです。作成者がコンポーネントを設定し、必要情報を提供するためのインターフェイスをダイアログが備えているからです。

コンポーネントの複雑さに応じて、ダイアログには 1 つ以上のタブが必要です。これは、ダイアログを簡潔にし、必要情報フィールドを分類するためです。

ダイアログの定義は UI に固有です。

デザインダイアログは、コンテンツの編集や設定に使用されるダイアログによく似ていますが、そのコンポーネントのデザインの詳細を作成者が設定できるようにするインターフェイスを提供します。

デザインダイアログはデザインモードで使用可能ですが、必ずしもすべてのコンポーネントに必要なわけではありません。例えば、タイトルコンポーネントと画像コンポーネントにはどちらもデザインダイアログがありますが、テキストコンポーネントにはありません。

段落システム（parsys など）用のデザインダイアログは特殊なケースで、ユーザーはこのデザインダイアログを使用して、特定の他のコンポーネントをページ上で（コンポーネントブラウザーまたはサイドキックから）選択することができます。

コンポーネントを定義した上で、使用可能にする必要があります。コンポーネントを段落システムで使用可能にするには、次のどちらかの方法を実行します。

ページ <content-path>/Prototype.html 上にタイトルコンポーネントのインスタンスを作成して設定する場合：

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

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

• （両方の UI の）定義にプロパティ name=./jcr:title があります。
  
  • /libs/foundation/components/title/cq:dialog/content/items/column/items/title
  • /libs/foundation/components/title/dialog/items/title
• この定義によって、コンテンツ内に作成者のコンテンツを保持する jcr:title というプロパティが生成されます。

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

AEM 内のコンポーネントは、次の 3 種類の階層で表現されます。

• リソースタイプ階層
  プロパティ sling:resourceSuperType によるコンポーネントの拡張に使用されます。これにより、コンポーネントの継承ができるようになります。例えば、テキストコンポーネントは標準コンポーネントから様々な属性を継承します。
  
  • スクリプト（Sling によって解決）
  • ダイアログ
  • 説明（サムネール画像、アイコンなどを含む）
• コンテナ階層
  子コンポーネントに設定を適用するために使用されます。parsys シナリオで最もよく使用されています。
  例えば、編集バーのボタン、コントロールセットのレイアウト（編集バー、ロールオーバー）、ダイアログのレイアウト（インライン、浮動）の設定を親コンポーネントで定義して、子コンポーネントに適用できます。
  cq:editConfig および cq:childEditConfig の（編集機能に関する）設定が適用されます。
• インクルード階層実行時にインクルードのシーケンスによって適用されます。
  
  この階層は、デザイナーによって使用され、レンダリングのさまざまなデザイン側面、特にレイアウト情報、CSS 情報、parsys で使用可能なコンポーネントの基礎として機能します。

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

固有の相違点は多少ありますが、設定はタッチ操作対応 UI とクラシック UI の両方に共通です。

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

リポジトリには、既存の設定が多数あります。ユーザーは、特定のプロパティや子ノードを簡単に検索できます。

• 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)

cq:actions プロパティ（String 配列）では、コンポーネントで実行できるアクションを 1 個から数個定義します。設定に使用できる値を以下に示します。

次の設定では、編集ボタン、スペーサー、削除ボタンおよび挿入ボタンがコンポーネントの編集バーに追加されます。

次の設定では、「Inherited Configurations from Base Framework」というテキストがコンポーネントの編集バーに追加されます。

cq:layout プロパティ（String）では、クラシック UI でコンポーネントを編集可能にする方法を定義します。使用可能な値を次に示します。

次の設定では、編集ボタンがコンポーネントの編集バーに追加されます。

コンポーネントを編集ダイアログにリンクできます。cq:dialogMode プロパティ（String）では、クラシック UI でコンポーネントダイアログを開く方法を定義します。使用可能な値を次に示します。

次の設定では、編集ボタンを含む編集バーと浮動ダイアログが定義されます。

cq:emptyText プロパティ（String）では、視覚的なコンテンツが存在しない場合に表示するテキストを定義します。デフォルト値は、「コンポーネントまたはアセットをここにドラッグ」です。

cq:inherit プロパティ（ブール値）では、欠落している値をその継承元のコンポーネントから継承するかどうかを定義します。デフォルト値は false です。

dialogLayout プロパティは、デフォルトのダイアログの開き方を定義します。

• 値が fullscreen の場合、ダイアログは全画面で開きます。
• 値が空かプロパティがない場合、デフォルトでは通常どおりにダイアログが開きます。 
• ユーザーは、ダイアログ内で全画面モードを常に切り替えることができます。 
• クラシック UI には適用されません。

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

タイプ cq:DropTargetConfig のそれぞれの子ノードでは、コンポーネントのドロップターゲットを定義します。ノード名は重要です。ノード名は、JSP で次のように使用して、有効なドロップターゲットである DOM 要素に割り当てられる CSS クラス名を生成する必要があるからです。

<ドロップターゲット CSS クラス> = <ドラッグ＆ドロッププレフィックス> + <編集設定のドロップターゲットのノード名>

<ドラッグ＆ドロッププレフィックス> は、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:actionConfigs ノード（ノードタイプ nt:unstructured）では、cq:actions プロパティで定義されたリストに追加する新しいアクションのリストを定義します。cq:actionConfigs のそれぞれの子ノードでは、ウィジェットを定義することにより新しいアクションを定義します。

次の設定例では、（クラシック UI 用の区切り文字を持つ）新しいボタンを定義しています。

• xtype tbseparator で定義される区切り文字。
  • クラシック UI でのみ使用されます。
    
  • タッチ操作対応 UI では xtype が無視されるので、この定義は無視されます（また、タッチ操作対応 UI ではアクションツールバーの構造が異なるので、区切り文字は不要です）。
• ハンドラー関数 CQ_collab_forum_openCollabAdmin() を実行する「Manage comments」という名前のボタン。

cq:formParameters ノード（ノードタイプ nt:unstructured）では、ダイアログフォームに追加するその他のパラメーターを定義します。各プロパティは、form パラメーターにマップされます。

次の設定では、値 photos/primary が設定された name という名前のパラメーターがダイアログフォームに追加されます。

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

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

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

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

afteredit = "project.customerAction"

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

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

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