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

Version: 20.x
日本語翻訳に関する免責事項

このページの翻訳は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 にクエリをセットします。

RequestResponse
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 インターフェイスをオーバーライドすることができます。以下に例を示します。

RequestResponse
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.

何かフィードバックはありますか?

この記事を改善するための提案がある場合は、