コンテンツフラグメントのカスタマイズと拡張

コンテンツフラグメントは、標準アセットを拡張します。

• コンテンツフラグメントについて詳しくは、コンテンツフラグメントの作成と管理およびコンテンツフラグメントを使用したページオーサリングを参照してください。

• 標準アセットについて詳しくは、アセットの管理およびアセットのカスタマイズと拡張を参照してください。

アーキテクチャ

コンテンツフラグメントの基本的な構成要素は次のとおりです。

• コンテンツフラグメント，
• 1つ以上の​コンテンツ要素​から成る、
• とは、1つ以上の​コンテンツのバリエーション​を持つことができます。

フラグメントのタイプによって、モデルまたはテンプレートも使用します。

• コンテンツフラグメントモデル:

  • 構造化コンテンツを含むコンテンツフラグメントの定義に使用します。
  • コンテンツフラグメントモデルでは、コンテンツフラグメントの作成時にその構造を定義します。
  • フラグメントはモデルを参照するので、モデルに対する変更は、そのモデルに関連付けられているフラグメントにも影響します。
  • モデルはデータタイプで構成されています。
  • 新しいバリエーションを追加するときなどは、それに合わせてフラグメントを更新する必要があります。
  注意

  既存のコンテンツフラグメントモデルに変更を加えると、そのモデルに関連付けられているフラグメントに影響が生じる場合があり、対象のフラグメントで孤立プロパティが生まれることもあります。

• コンテンツフラグメントテンプレート：

  • シンプルなコンテンツフラグメントの定義に使用します。
  • テンプレートでは、コンテンツフラグメントの作成時にその構造（基本的なテキストのみ）を定義します。
  • テンプレートは作成時にフラグメントにコピーされるので、それ以降にテンプレートに変更を加えても、既存のフラグメントには反映されません。
  • 新しいバリエーションを追加するときなどは、それに合わせてフラグメントを更新する必要があります。
  • コンテンツフラグメン トテンプレートは、AEMエコシステム内の他のテンプレートメカニズム（ページテンプレートなど）とは異なる方法で存在します。そのため、分けて考える必要があります。
  • テンプレートを基にした場合、コンテンツの MIME タイプは実際のコンテンツに基づいて管理されます。つまり、要素およびバリエーションごとに MIME タイプが異なる場合もあります。

AEM Assets との統合

コンテンツフラグメント管理（CFM）は、次の理由から AEM Assets の一部と考えられます。

• コンテンツフラグメントはアセットである。
• 既存の AEM Assets 機能を使用する。
• AEM Assets に完全に統合されている（Admin Console など）。

構造化コンテンツフラグメントのアセットへのマッピング

コンテンツフラグメントモデルがベースの構造化コンテンツフラグメントは、単一のアセットにマッピングされます。

• すべてのコンテンツはアセットの jcr:content/data ノードに格納されます。

  • 要素データは次のマスターサブノードに格納されます。

    jcr:content/data/master

  • バリエーションは、バリエーションの名前を持つサブノードの下に保存されます。

    例：jcr:content/data/myvariation

  • 各要素のデータは、要素名を持つプロパティとして各サブノードに保存されます。

    例えば、要素textの内容はjcr:content/data/master上のプロパティtextとして保存されます

• メタデータと関連するコンテンツはjcr:content/metadataの下に保存されます

  タイトルと説明を除き、従来のメタデータとはみなされずjcr:contentに保存されます。

シンプルコンテンツフラグメントのアセットへのマッピング

テンプレートがベースのシンプルなコンテンツフラグメントは、メインアセットとサブアセット（オプション）の複合にマッピングされます。

• フラグメントのコンテンツ以外の情報（タイトル、説明、メタデータ、構造など）はすべて、メインアセットでのみ管理されます。

• フラグメントの最初の要素のコンテンツは、メインアセットのオリジナルレンディションにマッピングされます。

  • 最初の要素のバリエーション（存在する場合）は、メインアセットのその他のレンディションにマッピングされます。

• 追加要素（存在する場合）は、メインアセットのサブアセットにマッピングされます。

  • これらの追加要素のメインコンテンツは、それぞれのサブアセットのオリジナルレンディションにマッピングされます。
  • すべての追加要素のその他のバリエーション（該当する場合）は、それぞれのサブアセットのその他のレンディションにマッピングされます。

アセットの場所

標準アセットの場合、コンテンツフラグメントは次の場所に保持されます。

• /content/dam

アセットの権限

詳しくは、コンテンツフラグメント - 削除に関する考慮事項を参照してください。

機能の統合

• コンテンツフラグメント管理（CFM）機能は、Assets のコアを基盤として構築されていますが、できる限り独立させる必要があります。
• CFM は、カード／列／リスト表示の項目に独自の実装を提供します。つまり、それらの項目が、既存のアセットコンテンツのレンダリング実装に挿入されます。
• コンテンツフラグメントに対応するために、いくつかのアセットコンポーネントが拡張されています。

ページでのコンテンツフラグメントの使用

コンテンツフラグメントは、その他のアセットタイプと同様に、AEM ページから参照できます。AEM では、​​コンテンツフラグメントコアコンポーネントを利用できます。これは、コンテンツフラグメントをページ上に含めることができるコンポーネントです。また、この​コンテンツフラグメント​コアコンポーネントを拡張することもできます。

• このコンポーネントは、fragmentPath プロパティを使用して、実際のコンテンツフラグメントを参照します。fragmentPath プロパティは、その他のアセットタイプの類似プロパティと同じ方法で処理されます。例えば、コンテンツフラグメントが別の場所に移動された場合などです。

• このコンポーネントを使用して、表示するバリエーションを選択できます。

• さらに、一定範囲の段落を選択して、出力を制限できます。例えば、複数列の出力に利用できます。

• このコンポーネントは、中間コンテンツを許可します。

  • ここで、このコンポーネントを使用して、他のアセット（画像など）を参照されているフラグメントの段落の中間に配置できます。

    • 中間コンテンツの場合は、次のことを実行する必要があります。

      • 参照が不安定になる可能性に注意します。中間コンテンツ（ページのオーサリング時に追加）とその横にある段落の関係は、固定されていません。（コンテンツフラグメントエディター内で）中間コンテンツの位置の前に新しい段落を挿入すると、相対的な位置が失われることがあります。
        • 検索結果における偽陽性を回避するために、パラメーター（類似バリエーションや段落フィルターなど）の追加を検討します。

OSGi コンソールを使用した設定

コンテンツフラグメントのバックエンド実装は、ページ上で使用されるフラグメントのインスタンスを検索可能にしたり、複合メディアコンテンツを管理したりする役割を担います。この実装では、フラグメントのレンダリングに使用されるコンポーネントと、レンダリングがパラメーター化される方法を把握する必要があります。

このパラメーターは、Web コンソールで設定できます（OSGi バンドルの DAM コンテンツフラグメント設定）。

• リソースタイプ

  sling:resourceTypes のリストを使用して、コンテンツフラグメントのレンダリングに使用するコンポーネントと、バックグラウンド処理を適用する場所を定義できます。

• 参照プロパティ

  プロパティのリストを設定し、それぞれのコンポーネントに対応するフラグメントの参照を格納する場所を指定できます。

次のガイドラインに沿って、コンポーネントがコンテンツフラグメントのバックグラウンド処理に対応できるようにする必要があります。

• レンダリングする要素を定義するプロパティの名前は、elementまたはelementNamesにする必要があります。

• レンダリングされるバリエーションが定義するプロパティの名前は、variation または variationName にする必要があります。

• 複数の要素の出力がサポートされている場合（elementNamesを使用して複数の要素を指定）、実際の表示モードはプロパティdisplayModeによって定義されます。

  • 値がsingleText（1つの要素しか設定されていない）の場合、要素はコンテンツ内、レイアウトのサポートなどを含むテキストとしてレンダリングされます。 レンダリングされる要素が 1 つのみのフラグメントでは、これがデフォルトです。
  • それ以外の場合は、よりシンプルな「フォーム表示」と呼ばれる方法が使用されます。この方法では中間コンテンツがサポートされず、フラグメントコンテンツが「そのまま」表示されます。

• フラグメントがdisplayMode == singleText用にレンダリングされる場合（暗黙的または明示的に）、次の追加のプロパティが再生されます。

  • paragraphScope すべての段落をレンダリングするか、段落の範囲のみをレンダリングするかを定義します(値： all vs. range)
  • paragraphScope == rangeの場合、paragraphRangeプロパティはレンダリングする段落の範囲を定義します

その他のフレームワークとの統合

コンテンツフラグメントは、次のフレームワークと統合できます。

• 翻訳

  コンテンツフラグメントは、AEM翻訳ワークフローと完全に統合されています。 つまり、アーキテクチャレベルでは以下を意味します。

  • コンテンツフラグメントの個々の翻訳は、実際には別々のフラグメントです。例えば、以下のようになります。

    • 言語のルートが異なります。

      /content/dam/<path>/en/<to>/<fragment>

      上記に対して次のようになります。

      /content/dam/<path>/de/<to>/<fragment>

    • しかし、言語ルートの下では、まったく同じ相対パスを共有しています。

      /content/dam/<path>/en/<to>/<fragment>

      上記に対して次のようになります。

      /content/dam/<path>/de/<to>/<fragment>

  • ルールベースのパスを除き、コンテンツフラグメントの様々な言語バージョンの間にそれ以上のつながりはありません。UI には言語バリアント間を移動する手段が用意されていますが、それらは 2 つの別々のフラグメントとして扱われます。

  メモ

  AEM 翻訳ワークフローでは、/content が使用されます。

  • コンテンツフラグメントモデルは /conf 内に配置されるので、これらの翻訳には含まれません。UI 文字列を国際化できます。
  • テンプレートをコピーしてフラグメントを作成するので、これは暗黙的になります。

• メタデータスキーマ

  • コンテンツフラグメントは、メタデータのスキーマを（再）利用します。メタデータのスキーマは、標準アセットを使用して定義できます。

• CFM には、次のような独自の固有のスキーマがあります。

  /libs/dam/content/schemaeditors/forms/contentfragment

  必要に応じて拡張できます。

• 各スキーマフォームは、フラグメントエディターと統合されています。

コンテンツフラグメント管理 API - サーバー側

サーバー側 API を使用して、コンテンツフラグメントにアクセスできます。以下を参照してください。

com.adobe.cq.dam.cfm

主要インターフェイス

次の 3 つのインターフェイスが、入口の役割を果たします。

• フラグメントのテンプレート

  FragmentTemplate

  新しいフラグメントを作成するには、FragmentTemplate.createFragment()を使用します。

  Resource templateOrModelRsc = resourceResolver.getResource("...");
  FragmentTemplate tpl = templateOrModelRsc.adaptTo(FragmentTemplate.class);
  ContentFragment newFragment = tpl.createFragment(parentRsc, "A fragment name", "A fragment description.");
  

  このインターフェイスは次を表します。

  • コンテンツフラグメントの作成元がコンテンツフラグメントモデルなのか、コンテンツフラグメントテンプレートなのか。
  • そして（作成後）そのフラグメントの構造情報

  この情報の例は次のとおりです。

  • 基本データ（タイトル、説明）にアクセスする

  • フラグメントの要素のテンプレート／モデルにアクセスする

    • 要素テンプレートを一覧表示する
    • 特定の要素の構造に関する情報を取得する
    • 要素テンプレートにアクセスする（ElementTemplate を参照）

  • フラグメントのバリエーションのテンプレートにアクセスする

    • バリエーションテンプレートを一覧表示する
    • 特定のバリエーションの構造情報を取得する
    • バリエーションテンプレートにアクセスする（VariationTemplate を参照）

  • 初期関連コンテンツを取得する

  重要な情報を表すインターフェイスには、次のものがあります。

  • ElementTemplate

    • 基本データ（名前、タイトル）を取得する
    • 初期要素コンテンツを取得する

  • VariationTemplate

    • 基本データ（名前、タイトル、説明）を取得する

• コンテンツフラグメント

  ContentFragment

  このインターフェイスでは、コンテンツフラグメントを抽象化して使用できます。

  注意

  このインターフェイスを使用してフラグメントにアクセスすることを強く推奨します。コンテンツ構造を直接変更しないでください。

  このインターフェイスでは、次のことを実行できます。

  • 基本データを管理する（名前の取得、タイトルまたは説明の取得／設定など）

  • メタデータにアクセスする

  • 要素にアクセスする

    • 要素を一覧表示する
    • 要素を名前で取得する
    • 新しい要素を作成する（注意事項を参照）
    • 要素データにアクセスする（ContentElement を参照）

  • そのフラグメントに対して定義されているバリエーションを一覧表示する

  • 新しいバリエーションをグローバルに作成する

  • 関連コンテンツを管理する

    • コレクションを一覧表示する
    • コレクションを追加する
    • コレクションを削除する

  • フラグメントのモデルにアクセスする またはテンプレート

  フラグメントの主要要素を表すインターフェイスには、次のものがあります。

  • コンテンツ要素

    ContentElement

    • 基本データ（名前、タイトル、説明）を取得する

    • コンテンツを取得／設定する

    • 要素のバリエーションにアクセスする

      • バリエーションを一覧表示する
      • バリエーションを名前で取得する
      • 新しいバリエーションを作成する（注意事項を参照）
      • バリエーションを削除する（注意事項を参照）
      • バリエーションデータにアクセスする（ContentVariation を参照）

    • バリエーションを解決するためのショートカット（要素に指定されたバリエーションを使用できない場合は実装固有の追加のフォールバックロジックを適用）

  • コンテンツのバリエーション

    ContentVariation

    • 基本データ（名前、タイトル、説明）を取得する
    • コンテンツを取得／設定する
    • 最後に変更された情報に基づくシンプルな同期

  3 つのインターフェイス（ContentVariation、ContentFragment、ContentElement、）すべてによって Versionable インターフェイスを拡張し、コンテンツフラグメントに必要な次のバージョン管理機能を追加します。

  • 要素の新しいバージョンを作成する
  • 要素のバージョンを一覧表示する
  • バージョン管理されている要素の特定のバージョンのコンテンツを取得する

適応 - adaptTo() の使用

次のものを適応させることができます。

• ContentFragment は、次のものに適応させることができます。

  • Resource — 基礎となるスリング資源。基になるオブジェクトを Resource 直接更新する場合は、 ContentFragment オブジェクトを再構築する必要があります。
  • Asset — コンテンツフラグメントを表すDAM Asset 抽象。更新を Asset 直接行うには、 ContentFragment オブジェクトを再構築する必要があります。

• ContentElement は、次のものに適応させることができます。

  • ElementTemplate - 要素の構造に関する情報にアクセスするためのものです。

• FragmentTemplate は、次のものに適応させることができます。

  • Resource - Resource は、参照されているモデルまたはコピーされた元のテンプレートを決定します。

    • Resource を使用した変更は、FragmentTemplate に自動的に反映されません。

• Resource は、次のものに適応させることができます。

  • ContentFragment
  • FragmentTemplate

注意事項

次のことに注意してください。

• API は、UI がサポートする機能を提供するために実装されています。

• API 全体は、（API JavaDoc で特に記載がない限り）変更を自動では保持​しない​ように設計されています。したがって、各リクエストのリソースリゾルバー（または実際に使用しているリゾルバー）を必ずコミットしなければなりません。

• 次のタスクには、追加作業が必要な場合があります。

  • 新しい要素を作成または削除しても、フラグメントテンプレートに基づくシンプルなフラグメントのデータ構造は更新されません。
  • ContentElement から新しいバリエーションを作成してもデータ構造は更新されません（ただし、ContentFragment からグローバルに新しいバリエーションを作成すると更新されます）。
  • 既存のバリエーションを削除してもデータ構造は更新されません。

コンテンツフラグメント管理 API - クライアント側

追加情報

次のファイルを参照してください。

• filter.xml

  コンテンツフラグメント管理のための filter.xml は、アセットのコアコンテンツパッケージと重複しないように設定されています。

編集セッション

編集セッションは、ユーザーがエディターのいずれかのページでコンテンツフラグメントを開くと開始されます。ユーザーが「保存」または「キャンセル」を選択してエディターから移動すると、編集セッションは終了します。

要件

編集セッションの制御には、次の要件があります。

• 複数の表示（= HTMLページ）にまたがるコンテンツフラグメントの編集は、アトミックで行う必要があります。
• さらに、編集はトランザクション単位​**​でおこなう必要があります。すなわち、編集セッションの終了時には、変更をコミット（保存）するか、ロールバック（キャンセル）します。
• エッジケースを適切に処理する必要があります。例としては、ユーザーが手動で URL を入力したりグローバルナビゲーションを使用したりしてページから移動する場合などが考えられます。
• データが失われないよう、定期的な自動保存（x 分ごと）をおこなう必要があります。
• 2 人のユーザーが同時に 1 つのコンテンツフラグメントを編集する場合に、互いの変更を上書きしてはなりません。

プロセス

次のプロセスが含まれます。

• セッションの開始

  • コンテンツフラグメントの新しいバージョンが作成されます。
  • 自動保存が開始されます。
  • cookie が設定されます。この cookie により、現在編集しているフラグメントと、編集セッションがオープンしていることが記録されます。

• セッションの終了

  • 自動保存が停止されます。

  • コミット時：

    • 最後に変更した情報が反映されます。
    • cookie が削除されます。

  • ロールバックする場合：

    • 編集セッションの開始時に作成されたコンテンツフラグメントのバージョンが復元されます。
    • cookie が削除されます。

• 編集

  • すべての変更（自動保存を含む）は、分離され、保護された領域ではなく、アクティブなコンテンツフラグメントに対して実行されます。
  • したがって、このような変更は、各コンテンツフラグメントを参照する AEM ページに即座に反映されます。

アクション

使用可能なアクションには次のものがあります。

• ページの入力

  • 対応する cookie を確認して、編集セッションが既に存在するかどうかを確認します。

    • 存在する場合は、編集セッションが現在編集中のコンテンツフラグメント用に開始されたことを確認します。

      • 現在のフラグメント用の場合は、セッションを再確立します。
      • それ以外の場合は、前に編集したコンテンツフラグメント用の編集のキャンセルと、cookie の削除をおこないます（以後、編集セッションは存在しなくなります）。

    • 編集セッションが存在しない場合は、ユーザーが最初の変更をおこなうまで待機します（下記を参照）。

  • コンテンツフラグメントが既にページ上で参照されているかどうかを確認し、参照されている場合は適切な情報を表示します。

• コンテンツ変更

  • ユーザーがコンテンツを変更し、編集セッションが存在しない場合は、常に新しい編集セッションが作成されます（セッションの開始を参照）。

• ページからの移動

  • 編集セッションが存在していて、変更が保持されていない場合は、コンテンツが失われる可能性があることをユーザーに通知し、ページに留まるかどうかを尋ねるモーダル確認ダイアログが表示されます。

例

例：既存のコンテンツフラグメントへのアクセス

既存のコンテンツフラグメントにアクセスするには、API を表すリソースを以下に適応させます。

com.adobe.cq.dam.cfm.ContentFragment

次に例を示します。

// first, get the resource
Resource fragmentResource = resourceResolver.getResource("/content/dam/fragments/my-fragment");
// then adapt it
if (fragmentResource != null) {
    ContentFragment fragment = fragmentResource.adaptTo(ContentFragment.class);
    // the resource is now accessible through the API
} 

例：新しいコンテンツフラグメントの作成

新しいコンテンツフラグメントをプログラムによって作成するには、以下を使用する必要があります。

com.adobe.cq.dam.cfm.ContentFragmentManager#create

次に例を示します。

Resource templateOrModelRsc = resourceResolver.getResource("...");
FragmentTemplate tpl = templateOrModelRsc.adaptTo(FragmentTemplate.class);
ContentFragment newFragment = tpl.createFragment(parentRsc, "A fragment name", "A fragment description.");

例：自動保存間隔の指定

自動保存間隔（秒単位）は、設定マネージャー（ConfMgr）を使用して定義できます。

• ノード：<conf-root>/settings/dam/cfm/jcr:content

• プロパティ名：autoSaveInterval

• 型：Long

• デフォルト：600（10 分）。/libs/settings/dam/cfm/jcr:content で定義されています

自動保存間隔を 5 分に設定する場合は、次のようにノードにプロパティを定義する必要があります。

• ノード：/conf/global/settings/dam/cfm/jcr:content

• プロパティ名：autoSaveInterval

• 型：Long

• 値：300（5 分は 300 秒です）

コンテンツフラグメントテンプレート

詳しくは、コンテンツフラグメントテンプレートを参照してください。

ページオーサリング用コンポーネント

詳しくは、次を参照してください。

• コアコンポーネント - コンテンツフラグメントコンポーネント（推奨）
• コンテンツフラグメントコンポーネント — ページオーサリング用コンポーネント