オーバーレイ(および Sling Resource Merger)の使用

AEM(旧称 CQ)は、以前からオーバーレイという原理を利用して、開発者がコンソールおよびその他の機能(ページオーサリングなど)を拡張し、カスタマイズできるようにしてきました。

注意

このページで説明する Sling Resource Merger および関連する手法は、Granite と併用する場合に限り使用できます。つまり、このページの説明は、タッチ操作向け UI にのみ該当します。

他の分野(クラシック UI など)でのオーバーレイには、/libs の該当するノードと構造を /apps にコピーし、/apps 以下で必要な変更を行うことが要求されます。

AEM は、リソースを検索する際に、/apps ブランチを先に検索し、その後 /libs ブランチを検索するように設定されています。このメカニズムにより、開発者のオーバーレイ(およびそこで定義されたカスタマイズ)が使用されるようになっています。オーバーレイを作成するには、次の操作を実行します。

  • /libs 内にあるものと同じように、必要なノードとノード構造を再作成します。
  • /apps 内にオーバーレイ用のノード構造を作成します。
  • /apps 内で変更を行います。

メモ

オーバーレイは様々なコンテキストで使用される用語です。

このコンテキスト(AEM の拡張)では、オーバーレイは、事前定義済みの機能に対して独自の定義を強制的に付加する(標準の機能をオーバーライドする)ことを表します。

オーバーレイは、コンソールの設定サイドパネル内にあるアセットブラウザーへの選択カテゴリの作成(ページのオーサリング時に使用)など、多くの変更において推奨される方法です。オーバーレイは、次の理由で必要になります。

  • /libs ブランチで変更を行うことはできません。
    このブランチは、次の場合に変更される可能性が高く、その際に開発者による変更内容が失われる可能性があります。
    • インスタンス上のアップグレード
    • ホットフィックスの適用
    • 機能パックのインストール
  • オーバーレイにより、変更を 1 箇所に集中させることができます。そのため、必要の際に変更の追跡、移行、バックアップ、デバッグを実行しやすくなります。

AEM 6.0 では、オーバーレイの実装方法と使用方法が次のように変更されました。

  • Granite 以外によるオーバーレイおよび AEM 6.0 より前のバージョンでのオーバーレイ
    • 方法
      • コンテンツを /libs から /apps にコピーします。
        プロパティを含むサブブランチ全体をコピーする必要があります。
      • /apps 以下で変更作業を行います。
    • デメリット
      • /libs 以下で変更が行われても開発者による変更内容は失われませんが、/apps 以下のオーバーレイにおける一部の変更作業をやり直す必要がある場合があります。
  • AEM 6.0 以降の Granite 関連のオーバーレイ
    • 方法
      • 適切な /libs 構造を /apps 以下に再構成します。
        1:1 のコピーは不要で、Sling Resource Merger の使用により、必要な元の定義が相互参照されます。
      • /apps 以下で変更作業を行います。
    • メリット
      • /libs 以下の変更に対する堅牢性が高くなります。
      • 実際に必要な項目のみを再定義できます。

Sling Resource Merger

メモ

詳しくは、Sling Resource Merger Service API を参照してください。

目的

Sling Resource Merger は、リソースのアクセスとマージのためのサービスを提供します。リソースリゾルバーの検索パスと差分メカニズムを使用して、リソースのオーバーレイをマージします。リソースマージャーの使用の際にはカスタマイズされた sling ボキャブラリを使用して、ノードやそのプロパティのオーバーライドを管理できます。

Sling Resource Merger により、オーバーレイリソースおよびプロパティ(/apps 内で定義されたもの)が、元のリソースおよびプロパティ(/libs にあるもの)とマージされます。

  • /apps のコンテンツの方が /libs よりも優先されます(つまり、/apps のコンテンツが /libs のコンテンツを「オーバーレイ」します)。
  • 必要に応じて、/apps 内に定義されたプロパティによって、/libs からマージされたコンテンツの使用方法を指定します。

AEM の目的

AEM で Sling Resource Merger を使用する目的は、すべてのオーバーライドの変更を /apps 内で行うようにして、/libs 以下での変更作業の必要性をなくすことです。

設定

配信されるリソースは、次の項目に基づいて取得されたリソースおよびプロパティを集約したものです。

  • OSGi 設定Apache Sling Resource Resolver Factory 用に定義された、リソースの Resolver Search Path
    検索パスの順序は、上から下の順で、それぞれの優先順位を示します。

プロパティ

リソースマージャーには次のプロパティがあります。

  • sling:hidePropertiesString または String[]
    非表示にするプロパティまたはプロパティのリストを指定します。
    ワイルドカード * を指定した場合はすべて非表示になります。
  • sling:hideResourceBoolean
    リソースを子も含めて完全に非表示にするかを示します。
  • sling:hideChildrenString または String[]
    非表示にする子ノードまたは子ノードのリストが格納されます。ノードのプロパティは維持されます。
    ワイルドカード * を指定した場合はすべて非表示になります。
  • sling:orderBeforeString
    現在のノードの直後に配置する兄弟ノードの名前が格納されます。

これらのプロパティは、対応する(元の)リソースおよびプロパティ(/libs 内)がオーバーレイ(/apps 内)によってどのように使用されるかに影響します。

オーバーレイ構造の作成

オーバーレイを作成するには、/libs ノードを同じ構造で、/apps 以下に再作成する必要があります。次に例を示します。

  • サイトコンソールのナビゲーションエントリの定義(パネルに表示されるもの)は次の場所で定義されています。
    /libs/cq/core/content/nav/sites/jcr:title
  • この定義をオーバーレイするには、次のノードを作成します。
    /apps/cq/core/content/nav/sites
    さらに、必要に応じて jcr:title プロパティを更新します。

このオーバーレイを作成するために必要な作業は、スケルトン構造を再作成することだけです。構造を簡単に再作成できるように、すべての中間ノードは、タイプ nt:unstructured として作成できます(/libs の元のノードタイプを反映する必要はありません)。この例では、次のノードが必要になります。

/apps
  /cq
    /core
      /content
        /nav
          /sites
        

コードサンプルは、例としてのみ使用することを目的としています。

メモ

/libs の構造全体をコピーすることは推奨されません。全体をコピーすると、/apps 内で維持される情報が過多になります。その場合、システムが何らかの理由でアップグレードされたときに問題が発生する可能性があります。

ユースケース

オーバーレイを標準の機能とあわせることで、次の操作が可能になります。

  • プロパティの追加

    プロパティが /libs 定義に存在しないけれども /apps オーバーレイで必要になる場合。

    1. /apps 内に対応するノードを作成します。
    2. このノードで新しいプロパティを作成します。
  • プロパティのオーバーライド(自動作成されたプロパティ以外)

    プロパティが /libs に定義されているけれども、新しい値が /apps オーバーレイで必要になる場合。

    1. /apps 内に対応するノードを作成します。
    2. このノード(apps 以下)で対応するプロパティを作成します。
      • このプロパティには、Sling Resource Resolver 設定に基づいた優先順位が付けられます。
      • プロパティタイプの変更がサポートされています。
        /libs で使用されているものとは異なるプロパティタイプを使用する場合、その定義したプロパティタイプが使用されます。

    メモ

    プロパティタイプの変更がサポートされています。

  • 自動作成されたプロパティのオーバーライド

    デフォルトでは、自動作成されたプロパティ(jcr:primaryType など)は、現在 /libs 以下にあるノードタイプが尊重されるように、オーバーレイの対象にはなりません。オーバーレイを適用するには、/apps でノードを再作成し、プロパティを明示的に非表示にして再定義する必要があります。

    1. /apps 以下に、必要な jcr:primaryType を持つ対応するノードを作成します。
    2. そのノードでプロパティ sling:hideProperties を作成し、その値を自動作成されたプロパティに設定します(例:jcr:primaryType)。
      この /apps 以下で定義されたプロパティが、/libs 以下で定義されたプロパティよりも優先されるようになります。
  • ノードおよびその子のオーバーライド

    ノードとその子が /libs 内に定義されているけれども、/apps オーバーレイで新しい設定が必要な場合。

    1. 次のアクションを両方実行します。
      1. ノードの子を非表示にします(そのノードのプロパティは維持されます)。
      2. プロパティ(複数可)をオーバーライドします。
  • プロパティの非表示

    プロパティが /libs 内に定義されているけれども、/apps オーバーレイでは不要な場合。

    1. /apps 内に対応するノードを作成します。
    2. プロパティ sling:hideProperties(タイプ String または String[])を作成します。これを使用して、非表示にする(無視する)プロパティを指定します。ワイルドカードを使用することもできます。次に例を示します。
      • *
      • ["*"]
      • jcr:title
      • ["jcr:title", "jcr:description"]
  • ノードおよびその子の非表示

    ノードとその子が /libs 内に定義されているけれども、/apps オーバーレイでは不要な場合。

    1. /apps 以下に対応するノードを作成します。
    2. プロパティ sling:hideResource を作成します。
      • タイプ:Boolean
      • 値:true
  • ノードの子の非表示(そのノードのプロパティは維持)

    ノード、そのプロパティおよびその子が /libs に定義されており、ノードとそのプロパティは /apps オーバーレイで必要であるけれども、子ノードの一部またはすべては /apps オーバーレイで不要な場合。

    1. /apps 以下に対応するノードを作成します。
    2. プロパティ sling:hideChildren を作成します。
      • タイプ:String[]
      • 値:非表示にする(無視する)子ノードのリスト(/libs 内に定義されているもの)
      ワイルドカード * を使用してすべての子ノードを非表示にする(無視する)ことができます。
  • ノードの並べ替え

    ノードとその兄弟が /libs 内で定義されており、新しい位置にする必要があるので、ノードを /apps オーバーレイで再作成する場合(その新しい位置は /libs 内の適切な兄弟ノードを参照するものとして定義する)。

    • sling:orderBefore プロパティを使用します。
      1. /apps 以下に対応するノードを作成します。
      2. プロパティ sling:orderBefore を作成します。
        このプロパティで、現在のノードの直後に位置するノード(/libs 内にあるもの)を指定します。
        • タイプ:String
        • 値:<before-SiblingName>

使用例

​