レイアウト サービスのレンダリング出力のカスタマイズ
このページの翻訳はAIによって自動的に行われました。可能な限り正確な翻訳を心掛けていますが、原文と異なる表現や解釈が含まれる場合があります。正確で公式な情報については、必ず英語の原文をご参照ください。
レンダリングを JSON にシリアル化する際、レイアウト サービスは、レンダリングのデータソース アイテムのフィールドを使用してレンダリング コンテンツに入力します。
場合によっては、次のような他のタイプのデータを出力に含めることがあります。
-
コンテキスト アイテムからのデータ。
-
データソースまたはコンテキスト アイテムの子からのデータ。
-
他のアイテムからのデータをまとめたもの。
-
不要なデータのオーバーフェッチを防ぐための、前述したデータ タイプの制限されたビュー。
-
計算された値またはより複雑な値。
-
xDB からの情報などの非アイテム データ。
-
外部システムからの非 Sitecore データ。
次のセクションでは、レイアウト サービスによって返されるレンダリング出力をカスタマイズするためのいくつかのオプションについて説明します。
GraphQL API の使用
レンダリングの GraphQL クエリを設定することで、Sitecore レンダリング用のレイアウト サービス出力をカスタマイズできます。JSS では、この方法は Integrated GraphQL と呼ばれています。このクエリは、レイアウト サービス要求中にサーバーサイドで実行されるか、Experience Edge を使用している場合はパブリッシュ時に実行されます。
Sitecore レイアウト サービスは、ページをレンダリングすると、ページのレイアウトと各レンダリング/コンポーネントのデータを JSON 形式で返します。通常、レンダリング/コンポーネント データは、Sitecore データソース アイテムのフィールドのセットです。Integrated GraphQL を使用すると、これを GraphQL クエリの結果に再形成できます。
この手法を使用するには、以下を行う必要があります。
-
クエリするスキーマを持つ Sitecore GraphQL エンドポイントを定義する。
-
次の例のように、エンドポイントを使用するようにアプリケーションを設定します。
RequestResponse<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/"> <sitecore> <javaScriptServices> <apps> <!-- you may override other attributes from 'defaults' in the app definition below --> <app name="JssBasicAppGraphQL" graphQLEndpoint="/sitecore/api/jssbasicappgraphql" inherits="defaults" /> </apps> </javaScriptServices> </sitecore> </configuration>
Integrated GraphQL は、コンポーネントのレンダリング アイテムの コンポーネント GraphQL クエリ フィールドに GraphQL クエリを保存することで機能します。たとえば、GraphQL サンプル アプリは、/sitecore/layout/Renderings/JssBasicAppGraphQL/IntegratedPage
にクエリをセットします。
query IntegratedPageQuery(
$datasource: String!
$language: String!
$contextItem: String!
) {
datasource: item(path: $datasource, langauge: $language) {
... on IntegratedPage {
title {
jsonValue
}
text {
jsonValue
}
logoImage {
jsonValue
}
}
}
contextItem: item(path: $contextItem, language: $language) {
id
children(hasLayout: true) {
results {
displayName
url {
url
}
}
}
}
}
[en] For the default
and jss
layout service configurations, values for $datasource
, $contextItem
, and $language
are automatically injected.
Sitecore がレイアウト要求を受け取る際、コンポーネントが空でない GraphQL クエリを定義する場合、クエリはアプリに設定された GraphQL エンドポイントに対して実行されます。結果は、返された通常のレンダリング フィールド値を置き換えます。
組み込みのレンダリング コンテンツ リゾルバーの選択または構成
ヘッドレス サービスを使用すると、各レンダリングにレンダリング コンテンツ リゾルバーを設定して、レンダリングとその関連データがどのようにシリアル化されるかを決定することができます。レンダリング コンテンツ リゾルバーは、/sitecore/system/Modules/Layout Service/Rendering Contents Resolvers で設定します。既定では、ヘッドレス サービスは次のリゾルバーを提供します。
-
データソース リゾルバー - 既定の動作。レンダリングのデータソース アイテムをシリアル化します。
-
データソース 子アイテム リゾルバー - データソース アイテムの子をシリアル化します。
-
コンテキスト アイテム リゾルバー - データソース アイテムの代わりにコンテキスト アイテムをシリアル化します。
-
コンテキスト 子アイテム リゾルバー - コンテキスト アイテムの子をシリアル化します。
-
フォルダー フィルター リゾルバー - フォルダーを除く、データソース アイテムの子孫をシリアル化します。
次の使用可能なパラメーターを使用して、レンダリング コンテンツ リゾルバー フォルダーに独自の設定を作成できます。
-
タイプ - 独自の実装を作成している場合を除き、これは
Sitecore.LayoutService.ItemRendering.ContentsResolvers.RenderingContentsResolver, Sitecore.LayoutService
になります。 -
メディア URL にサーバー URL を含める - 統合モードで JSS を使ったフロントエンド アプリを実行する場合を除き、このフィールドを常に選択します。
-
コンテキスト アイテムを使用する - データソース アイテムの代わりにコンテキスト アイテムを使用します。
-
アイテム セレクター クエリ - Sitecore クエリをカスタマイズされたシリアル化アイテムに提供します。これは、上記の選択に応じて、データソースまたはコンテキスト アイテムに対して相対的である必要があります。
重要なお、このパラメーターを使用すると、Sitecore のパフォーマンスに深刻な悪影響を与えるクエリを簡単に作成できるようになりますので注意してください。
-
パラメーター - 任意のパラメーターを提供します。これらのパラメーターは既定では使用されませんが、独自の実装を作成する際に役立つ可能性があります。
[en] To use the Rendering Contexts Resolver, you must set it in the Rendering Contents Resolver
field, on the rendering item that references the component it applies to. For an example, refer to this walkthrough that sets resolvers for Form rendering when integrating Sitecore Forms with JSS.
IRenderingContentsResolver インターフェイスの作成
レイアウト サービスを使用すると、IRenderingContentsResolver
インターフェイスを介して、シリアル化されたレンダリングのコンテンツをカスタマイズできます。
将来の互換性のために、可能な限り、前述のノーコード オプションのいずれかを使用することをお勧めします。
独自の実装を作成し、カスタム タイプを指定するレンダリング コンテンツ リゾルバーを作成することで、レンダリングの既定 IRenderingContentsResolver
インターフェイスをオーバーライドすることができます。以下に例を示します。
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 の上級編集者向けにレンダリング アイテム フィールドを有効化することができます。
個別の REST エンドポイントを作成しない理由
上で説明した一部のシナリオでは、必要なデータにアクセスするための個別の REST エンドポイントを作成することもできます。ただし、前述の手法には、次のようないくつかの利点があります。
-
HTTP ラウンドトリップの増加を防ぐ。
-
コンポーネントにデータを自動的にバインドする。
-
サーバー/ユニバーサル レンダリングでデータが利用できるようになる。
-
現在のアプリケーション、コンテキスト アイテム (ルート)、またはデータソース アイテムに関連する追加データのクエリを容易にする。
[en] There is some overlap in potential use cases between using an integrated GraphQL query and extending the context data returned by the Layout Service.
[en] Integrated GraphQL queries ensure the data is made available when, and only when a content author utilizes that rendering within a route.
[en] Extending the context data returned by the Layout Service is generally intended for information that might be used in multiple components, or for providing data for statically placed components not managed within a Placeholder
.