エクスペリエンスフラグメント experience-fragments

基本知識 the-basics

エクスペリエンスフラグメントは、ページ内で参照できるコンテンツおよびレイアウトを含む 1 つ以上のコンポーネントのグループです。

エクスペリエンスフラグメントのプライマリ、バリアント、またはその両方で、次のものが使用されます。

  • sling:resourceType/libs/cq/experience-fragments/components/xfpage

/libs/cq/experience-fragments/components/xfpage/xfpage.html がないので、次のものに戻ります。

  • sling:resourceSuperTypewcm/foundation/components/page

プレーン HTML レンディション the-plain-html-rendition

URL で .plain. セレクターを使用すると、プレーン HTML レンディションにアクセスできます。

このレンディションはブラウザーで使用できます。ただし、その主な目的は、他のアプリケーション(例えば、サードパーティ web アプリ、カスタムモバイル実装など)が、URL のみを使用して、エクスペリエンスフラグメントのコンテンツに直接アクセスできるようにすることです。

プレーン HTML レンディションは、次のようなパスにプロトコル、ホストおよびコンテキストパスを追加します。

  • タイプが srchrefaction のいずれか

  • または、-src-href で終わる

次に例を示します。

.../brooklyn-coat/master.plain.html

NOTE
リンクは、常にパブリッシュインスタンスを参照します。リンクは、サードパーティによって使用されることを意図しているので、オーサリングインスタンスではなく、常にパブリッシュインスタンスから呼び出されます。
詳しくは、URL の外部化を参照してください。

プレーン HTML レンディション

プレーンレンディションセレクターでは、追加スクリプトとは異なり、トランスフォーマーを使用します。Sling Rewriter がトランスフォーマーとして使用されます。このトランスフォーマーは、次の場所で設定します。

  • /libs/experience-fragments/config/rewriter/experiencefragments

HTML レンディション生成の設定 configuring-html-rendition-generation

HTML レンディションは、Sling Rewriter パイプラインを使用して生成されます。パイプラインは、/libs/experience-fragments/config/rewriter/experiencefragments で定義されます。HTML 変換サービスでは、次のオプションをサポートしています。

  • allowedCssClasses

    • 最終レンディションに残す CSS クラスに一致する正規表現。
    • このオプションは、顧客が特定の CSS クラスを取り除きたい場合に便利です。
  • allowedTags

    • 最終的なレンディションで許可される HTML タグのリスト。
    • デフォルトでは、次のタグが許可されています(設定は不要):html、head、title、body、img、p、span、ul、li、a、b、i、em、strong、h1、h2、h3、h4、h5、h6、br、noscript、div、link、script

オーバーレイを使用してリライターを設定することをお勧めします。詳しくは、AEM as a Cloud Service でのオーバーレイを参照してください。

エクスペリエンスフラグメントのテンプレート templates-for-experience-fragments

CAUTION
エクスペリエンスフラグメントでサポートされているのは、編集可能なテンプレート​ だけ ​です。
エクスペリエンスフラグメントは、編集可能なテンプレートに基づくページでのみ使用できます。

エクスペリエンスフラグメントの新しいテンプレートを作成する際は、編集可能なテンプレートの標準的な手法に従うことができます。

エクスペリエンスフラグメントを作成 ​ウィザードで検出されるエクスペリエンスフラグメントテンプレートを作成するには、次のいずれかのルールセットに従う必要があります。

  1. 次の両方:

    1. テンプレート(初期ノード)のリソースタイプは、次のものから継承する必要があります。
      cq/experience-fragments/components/xfpage

    2. テンプレートの名前は次の文字列で始まる必要があります。
      experience-fragments
      これにより、ユーザーは /content/experience-fragments にエクスペリエンスフラグメントを作成できます。このフォルダーの cq:allowedTemplates プロパティには、experience-fragment で始まる名前の付いたすべてのテンプレートが含まれています。ユーザーは、このプロパティを更新して、独自の命名方式やテンプレート場所を取り入れることができます。

  2. 使用可能なテンプレートはエクスペリエンスフラグメントコンソールで設定できます。

エクスペリエンスフラグメントのコンポーネント components-for-experience-fragments

エクスペリエンスフラグメントで使用するコンポーネントの開発は、標準的な方法に従って行います。

唯一の追加設定は、コンポーネントをテンプレートで確実に使用できるようにするだけです。この許可設定には、コンテンツポリシーを使用します。

AEM では、エクスペリエンスフラグメントを作成できます。エクスペリエンスフラグメントは、

  • コンポーネントグループとレイアウトで構成されます。
  • AEM ページとは独立して存在できます。

このようなグループのユースケースの 1 つは、Adobe Target などのサードパーティのタッチポイントにコンテンツを埋め込む場合です。

「Adobe Target に書き出し」機能を使用すると、次の操作が可能です。

  • エクスペリエンスフラグメントを作成する
  • エクスペリエンスフラグメントにコンポーネントを追加する
  • エクスペリエンスフラグメントを HTML 形式または JSON 形式で Adobe Target オファーとして書き出す

この機能は、AEM のオーサーインスタンスで有効にすることができます。有効な Adobe Target 設定と、Link Externalizer の設定が必要です。

Link Externalizer は、Target オファーの HTML バージョンを作成する際に必要な正しい URL を決定するために使用します。オファーは、その後 Adobe Target に送信されます。Adobe Target では、Target HTML オファー内のすべてのリンクに公開でアクセスできる必要があるので、このプロセスは必須です。つまり、リンクが参照するすべてのリソースと、エクスペリエンスフラグメント自体は、使用する前に公開する必要があります。

デフォルトでは、Target HTML オファーを作成すると、AEM のカスタム Sling セレクターにリクエストが送信されます。このセレクターの名前は .nocloudconfigs.html です。これはエクスペリエンスフラグメントのプレーン HTML レンダリングを作成しますが、その名前が示すとおり、クラウド設定を含んでいません(クラウド設定は余分な情報です)。

HTML ページを生成すると、Sling Rewriter パイプラインが次の出力に変更されます。

  1. htmlheadbody の各要素が div 要素に置き換わります。metanoscripttitle の各要素が削除されます(これらは元の head 要素の子要素であり、div 要素に置き換えられた場合には考慮されません)。

    このような処理が行われるのは、HTML Target オファーを Target アクティビティに確実に含めることができるようにするためです。

  2. AEM では、HTML に存在するすべての内部リンクを変更して、公開されたリソースを指すようにします。

    変更するリンクを決定するために、AEM では HTML 要素の次の属性パターンに従います。

    1. src 属性
    2. href 属性
    3. *-src 属性(data-srccustom-src など)
    4. *-href 属性(data-hrefcustom-hrefimg-href など)
    note note
    NOTE
    HTML 内の内部リンクは相対リンクですが、カスタムコンポーネントの HTML で完全な URL が指定されている場合もあります。デフォルトでは、AEM はこれらの完全な URL を無視し、変更しません。

    これらの属性のリンクは AEM Link Externalizer publishLink() を通じて実行され、あたかもパブリッシュインスタンス上にあるかのように URL が再作成され、一般に公開されます。

そのまま使用できる標準実装を使用する場合、エクスペリエンスフラグメントから Target オファーを生成して Adobe Target に書き出すには、上記のプロセスで十分です。ただし、このプロセスでは対応していないユースケースもいくつかあります。考慮されていないケースには、次のようなものがあります。

  • Sling マッピングがパブリッシュインスタンスでのみ使用可能
  • Dispatcher によるリダイレクト

これらのユースケースのために、AEM には Link Rewriter Provider インターフェイスが用意されています。

デフォルトのリンク書き換えでは対応していない)より複雑な場合のために、AEM では Link Rewriter Provider フェイスを提供しています。このインターフェイスは、バンドルにサービスとして実装できる ConsumerType インターフェイスです。このインターフェイスは、エクスペリエンスフラグメントからレンダリングされる HTML オファーの内部リンクに対して AEM で実行される変更をバイパスします。このインターフェイスを使用すると、内部 HTML リンクの書き換えプロセスをビジネスニーズに合わせてカスタマイズできます。

このインターフェイスをサービスとして実装する使用例としては、例えば次のものがあります。

  • Sling マッピングがパブリッシュインスタンスでは有効になっているが、オーサーインスタンスでは有効になっていない
  • Dispatcher または類似の技術を使用して URL を内部的にリダイレクトする
  • リソース用に sling:alias mechanisms が整備されている
NOTE
このインターフェイスでは、生成された Target オファーからの内部 HTML リンクのみ処理します。

Link Rewriter Provider インターフェイス(ExperienceFragmentLinkRewriterProvider)は次のとおりです。

public interface ExperienceFragmentLinkRewriterProvider {

    String rewriteLink(String link, String tag, String attribute);

    boolean shouldRewrite(ExperienceFragmentVariation experienceFragment);

    int getPriority();

}

このインターフェイスを使用するには、まず、Link Rewriter Provider インターフェイスを実装する新しいサービスコンポーネントを含んだバンドルを作成する必要があります。

このサービスは、様々なリンクにアクセスできるように、エクスペリエンスフラグメントの「Target に書き出し」機能でのリンク書き換えにプラグインするために使用します。

例えば、ComponentService の場合は次のようになります。

import com.adobe.cq.xf.ExperienceFragmentLinkRewriterProvider;
import com.adobe.cq.xf.ExperienceFragmentVariation;
import org.osgi.service.component.annotations.Service;
import org.osgi.service.component.annotations.Component;

@Component
@Service
public class GeneralLinkRewriter implements ExperienceFragmentLinkRewriterProvider {

    @Override
    public String rewriteLink(String link, String tag, String attribute) {
        return null;
    }

    @Override
    public boolean shouldRewrite(ExperienceFragmentVariation experienceFragment) {
        return false;
    }

    @Override
    public int getPriority() {
        return 0;
    }

}

このサービスが機能するには、次の 3 つのメソッドをサービス内に実装する必要があります。

  • [shouldRewrite](#shouldrewrite)

  • [rewriteLink](#rewritelink)

    • rewriteLinkExample2
  • [getPriority](#priorities-getpriority)

shouldRewrite shouldrewrite

エクスペリエンスフラグメントの特定のバリエーションに対して「Target に書き出し」機能が呼び出された場合に、リンクを書き換える必要があるかどうかをシステムに指定する必要があります。次のメソッドを実装できます。

shouldRewrite(ExperienceFragmentVariation experienceFragment);

次に例を示します。

@Override
public boolean shouldRewrite(ExperienceFragmentVariation experienceFragment) {
    return experienceFragment.getPath().equals("/content/experience-fragment/master");
}

このメソッドは、Target システムに書き出しによる書き換えの対象となっているエクスペリエンスフラグメントバリエーションをパラメーターとして受け取ります。

上記の例では、次のように書き換えます。

  • src に指定されているリンク

  • href 属性のみ

  • 特定のエクスペリエンスフラグメントの場合:
    /content/experience-fragment/master

「Adobe Target に書き出し」システムに通す他のあらゆるエクスペリエンスフラグメントは無視され、本サービスに実装される変更の影響を受けません。

書き換えプロセスの影響を受けるエクスペリエンスフラグメントバリエーションの場合は、サービスでリンクの書き換えを処理するように作業を進めます。内部 HTML でリンクが検出されるたびに、次のメソッドが呼び出されます。

rewriteLink(String link, String tag, String attribute)

このメソッドは入力として次のパラメーターを受け取ります。

  • link
    処理中のリンクの String 表現です。この表現は通常、オーサーインスタンス上のリソースを指す相対 URL です。

  • tag
    処理中の HTML 要素の名前です。

  • attribute
    正確な属性名です。

例えば、Target システムに書き出しがこの要素を処理している場合は、CSSInclude を次のように定義できます。

<link rel="stylesheet" href="/etc.clientlibs/foundation/clientlibs/main.css" type="text/css">

rewriteLink() メソッドの呼び出しは、次のパラメーターを使用して行います。

rewriteLink(link="/etc.clientlibs/foundation/clientlibs/main.css", tag="link", attribute="href" )

サービスを作成する際は、指定された入力に基づいて判断し、それに応じてリンクを書き換えることができます。

この例では、URL の /etc.clientlibs 部分を削除し、適切な外部ドメインを追加するとしましょう。話を簡単にするために、rewriteLinkExample2 に示すように、サービスのリソースリゾルバーにアクセスできるとします。

NOTE
サービスユーザーを通じてリソースリゾルバーを取得する方法について詳しくは、AEM のサービスユーザーを参照してください。
private ResourceResolver resolver;

private Externalizer externalizer;

@Override
public String rewriteLink(String link, String tag, String attribute) {

    // get the externalizer service
    externalizer = resolver.adaptTo(Externalizer.class);
    if(externalizer == null) {
        // if there was an error, then we do not modify the link
        return null;
    }

    // remove leading /etc.clientlibs from resource link before externalizing
    link = link.replaceAll("/etc.clientlibs", "");

    // considering that we configured our publish domain, we directly apply the publishLink() method
    link = externalizer.publishLink(resolver, link);

    return link;
}
NOTE
上記のメソッドが null を返した場合、Target システムに書き出しは、リンクをそのままの状態(リソースへの相対リンク)にしておきます。

優先度 - getPriority priorities-getpriority

様々な種類のエクスペリエンスフラグメントに対応するためや、すべてのエクスペリエンスフラグメントの外部化とマッピングを処理する汎用サービスを用意するために、いくつかのサービスが必要になることは珍しくありません。このような場合、使用するサービスに関するの競合が発生する可能性があるので、AEM では、様々なサービスの​ 優先度 ​を定義できるようになっています。優先度は、次のメソッドを使用して指定します。

  • getPriority()

このメソッドを使用すると、複数のサービスを使用しても、同じエクスペリエンスフラグメントについては shouldRewrite() メソッドが true を返すようにすることができます。getPriority() メソッドから最高の優先度が返されるサービスが、対象となっているエクスペリエンスフラグメントバリエーションを処理するサービスになります。

例えば、エクスペリエンスフラグメントのすべてのバリエーションについて shouldRewrite() メソッドが true を返す場合にすべてのエクスペリエンスフラグメントの基本マッピングを処理する GenericLinkRewriterProvider を用意することができます。一部の特定のエクスペリエンスフラグメントについては、特別な処理が必要になる場合があります。その場合は、一部のエクスペリエンスフラグメントバリエーションについてのみ shouldRewrite() メソッドが true を返すような SpecificLinkRewriterProvider を用意することができます。それらのエクスペリエンスフラグメントバリエーションを処理するために SpecificLinkRewriterProvider が必ず選択されるようにするには、そのプロバイダーの getPriority() メソッドで返される優先度が GenericLinkRewriterProvider. の場合より高くなるようにする必要があります。

recommendation-more-help
fbcff2a9-b6fe-4574-b04a-21e75df764ab