レイアウトサービスのレンダリング出力のカスタマイズ

GraphQL APIの利用

Sitecoreレンダリングのレイアウトサービスの出力は、レンダリング時にGraphQLクエリを設定することでカスタマイズできます。JSSでは、この技術は 統合型GraphQLと呼ばれます。クエリはLayout Serviceリクエスト中、またはExperience Edgeを使用している場合は公開時にサーバー側で実行されます。

Sitecoreレイアウトサービスがページをレンダリングすると、ページのレイアウトと各レンダリング/コンポーネントのデータを含むJSON表現を返します。通常、レンダリング/コンポーネントデータはSitecoreのデータソース項目のフィールドの集合です。Integrated GraphQLを使えば、これをGraphQLクエリ結果に再構成できます。

このテクニックを使うには、以下が必要です:

• クエリしたいスキーマを持つSitecore GraphQLエンドポイント を定義します。

• アプリケーションをエンドポイントに設定してください。例えば:

統合GraphQLは、コンポーネントのレンダリングアイテムのComponent GraphQL QueryフィールドにGraphQLクエリを保存することで動作します。例えば、GraphQLサンプルアプリは /sitecore/layout/Renderings/JssBasicAppGraphQL/IntegratedPageにクエリを設定します。例えば:

query IntegratedPageQuery( $datasource: String! $language: String! $contextItem: String! ) { datasource: item(path: $datasource, language: $language) { ... on IntegratedPage { title { jsonValue } text { jsonValue } logoImage { jsonValue } } }

contextItem: item(path: $contextItem, language: $language) { id children(hasLayout: true) { results { displayName url { url } } } } }

!注defaultおよびjssレイアウトサービス構成では、$datasource、$contextItem、$languageの値が自動的に注入されます。

Sitecoreがレイアウトリクエストを受け取った場合、コンポーネントが空でないGraphQLクエリを定義した場合、そのクエリはアプリ用に設定されたGraphQLエンドポイントに対して処理中のものに対して実行されます。その結果は、返される通常のレンダリングフィールド値を置き換えます。

組み込みのレンダリングコンテンツリゾルバの選択または設定

Headless Servicesでは、各レンダリングにRendering Contents Resolverを設定し、レンダリングおよび関連データのシリアライズ方法を決定できます。レンダリング内容リゾルバは /sitecore/system/Modules/Layout Service/Rendering Contents Resolversで設定されています。デフォルトでは、Headless Servicesは以下のリソルバーを提供します:

• Datasource Resolver - デフォルトの動作。レンダリングのデータソース項目をシリアライズします。
• Datasource Item Children Resolver - データソース項目の子をシリアライズします。
• Context Item Resolver - データソース項目ではなくコンテキスト項目をシリアライズする。
• Context Item Children Resolver - コンテキスト項目の子をシリアライズします。
• Folder Filter Resolver - フォルダーを除くデータソース項目の子孫をシリアライズします。

以下のパラメータを使って、Rendering Contents Resolversフォルダ内で独自の設定を作成できます:

• Type - これはSitecore.LayoutService.ItemRendering.ContentsResolvers.RenderingContentsResolver, Sitecore.LayoutService、自分で実装を作っている場合を除きます。

• メディアURLにサーバーURLを含めてください 。 IntegratedモードでJSSを使ったフロントエンドアプリを動かさない限り、このフィールドは必ず確認してください。

• Use Context Item - データソース項目の代わりにコンテキスト項目を使用すること。

• Item Selector Query - シリアライズされた項目をカスタマイズするためのSitecoreクエリを提供する。これは上記の選択に応じて、データソースおよび/またはコンテキスト項目に対して相対的である必要があります。

  !重要このパラメータを使う際は、パフォーマンスに大きな悪影響を及ぼすSitecoreクエリを簡単に作成できることに注意してください。

• Parameters - 任意のパラメータを提供する。これらはデフォルトでは使われませんが、自らの実装を作成する際には有用です。

Rendering Contexts Resolverを使うには、適用するコンポーネントを参照するレンダリングアイテムのRendering Contents Resolverフィールドで設定する必要があります。例として、SitecoreフォームをJSSと統合する際のフォームレンダリング用リゾルバを設定する このウォークスルー を参照してください。

IRenderingContentsResolverインターフェースの作成

レイアウトサービスでは、IRenderingContentsResolverインターフェースの助けを借りて、シリアライズされたレンダリングの内容を完全にカスタマイズできます。

!重要可能な限り、今後の互換性のために、以前のノーコードオプションのいずれかを使うことをお勧めします。

レンダリングのデフォルトIRenderingContentsResolverインターフェースを上書きするには、独自の実装を作成し、カスタムTypeを指定するRendering Contents Resolverアイテムを作成できます。例えば:

public class ExampleRenderingContentsResolver : Sitecore.LayoutService.ItemRendering.ContentsResolvers.IRenderingContentsResolver { public bool IncludeServerUrlInMediaUrls { get; set; } public bool UseContextItem { get; set; } public string ItemSelectorQuery { get; set; } public NameValueCollection Parameters { get; set; }

public object ResolveContents(Rendering rendering, IRenderingConfiguration renderingConfig) { //if you want to access the datasource item var datasource = !string.IsNullOrEmpty(rendering.DataSource) ? rendering.RenderingItem?.Database.GetItem(rendering.DataSource) : null;

return new { name = datasource.Name, date = DateTime.Now, hello = "world" }; } }

実装によって返されたオブジェクトのフィールドは、アイテムコンテンツのようにフロントエンドのコンポーネントにバインドできます(例えば、Reactのprops )。

!ヒントSitecore.LayoutService.ItemRendering.ContentsResolvers.RenderingContentsResolverクラスを拡張し、クラスのProcessItemメソッドを使って 、上級Sitecoreエディタ向けにアイテムフィールドのレンダリングを有効にすることができます。

統合型GraphQLクエリを別個のRESTエンドポイントではなく使用する利点

上記のシナリオのいくつかでは、必要なデータにアクセスするために別のRESTエンドポイントを作成するという別のアプローチもあります。しかし、前述の手法はRESTエンドポイントを使うことと比べていくつかの利点があります。例えば:

• 追加のHTTP往復はありません。
• データをコンポーネントに自動バインディングします。
• データはサーバー/ユニバーサルレンダリング用に利用可能です。
• 現在のアプリケーション、コンテキスト項目(ルート)、またはデータソース項目に関連する追加データのクエリが容易になります。

!注統合されたGraphQLクエリの使用と 、レイアウトサービスが返すコンテキストデータの拡張には、いくつかのユースケースが重複しています。

統合されたGraphQLクエリは、コンテンツ作成者がルート内でそのレンダリングを利用したときにのみ、データが利用可能であることを保証します。

レイアウトサービスが戻すコンテキストデータの拡張は、一般的に複数のコンポーネントで使用される情報や、Placeholder内で管理されない静的配置コンポーネントのデータ提供を目的としています。