Using a custom Layout Service configuration with JSS

Abstract

How to use a custom Layout Service configuration in JSS apps

The Layout Service JSON rendering process is highly configurable and allows you to customize specific aspects of the Layout Service.

If you want to customize any element of the jss Layout Service configuration, we recommend using the ref attribute to copy in the existing configuration and then customize it within that element. This helps reduce required changes to your configuration if the jss configuration changes during an upgrade.

Important

Modifying the Layout Service configuration used by JSS resulting in changes to object shape, serialization, and placeholder processing, can break the JSS SDKs and can conflict with assumptions made by the JSS import process.

Modifying the serialization configuration allows you to change the JSON data that users can not influence. When modifying the serialization configuration, you can change the whole JSON output or just field names. For example, you can change field names if you want to have them camel-cased.

After defining your custom configuration, you add the configuration name to the list of <AllowedConfigurations> for the renderJsonRendering pipeline. Doing this ensures that the PlaceholderTransformer code that executes for the default jss configuration executes for your custom configuration as well.

Note

This step is only relevant if your custom configuration delivers an output that is similar in shape to the default JSS configuration. If your custom configuration is not related to JSS or does not depend on anything from the default jss configuration, this step is not necessary.

The following is a Sitecore configuration patch for a custom layout service configuration named my-jss-config that is based on the default jss configuration:

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
    <layoutService>
      <configurations>
        <!-- Define your custom named config, using the `ref` attribute to "copy" the existing `jss` configuration -->
        <config name="my-jss-config">
          <rendering ref="/sitecore/layoutService/configurations/config[@name='jss']/rendering">
            <!-- Override placeholdersResolver -->
            <placeholdersResolver type="My.Resolver, My.Assembly">
          </rendering>
          <serialization ref="/sitecore/layoutService/configurations/config[@name='jss']/serialization" />
        </config>
      </configurations>
  </layoutService>
    <pipelines>
        <group groupName="layoutService">
          <pipelines>
            <renderJsonRendering>
              <processor type="Sitecore.JavaScriptServices.ViewEngine.LayoutService.Pipelines.RenderJsonRendering.AddComponentName, Sitecore.JavaScriptServices.ViewEngine" resolve="true">
                <AllowedConfigurations hint="list">
                  <!-- Custom named config is added to this list -->
                  <config id="2">my-jss-config</config>
                </AllowedConfigurations>
              </processor>
            </renderJsonRendering>
          </pipelines>
        </group>
    </pipelines>
  </sitecore>
</configuration>

After patching in your custom configuration, you can utilize it in your JSS App using the layoutServiceConfiguration attribute.

<javaScriptServices>
  <apps>
    <app name="MyApp"
        sitecorePath="/sitecore/content/MyApp"
        layoutServiceConfiguration="my-jss-config"
        inherits="defaults"
    />
  </apps>
</javaScriptServices>

You must provide this configuration name in your client code as well as when invoking the Layout Service using the dataApi (see the previous examples).

Layout Service configuration

You can find Layout Service configurations in the Sitecore configuration at the /sitecore/layoutService/configurations path.

<config name="jss">
    <!--
        An implementation of `Sitecore.LayoutService.Configuration.IRenderingConfiguration`.
        Allows the addition of filtering logic to output renderings and placeholders.
    -->
    <rendering type="Sitecore.LayoutService.Configuration.DefaultRenderingConfiguration, Sitecore.LayoutService">

        <!--
            An implementation of `Sitecore.LayoutService.Placeholders.IPlaceholdersResolver`.
            Extracts the exposed placeholders of a rendering. Also available is
            `Sitecore.LayoutService.Placeholders.SimplePlaceholdersResolver`.
        -->
        <placeholdersResolver type="Sitecore.LayoutService.Placeholders.DynamicPlaceholdersResolver, Sitecore.LayoutService"/>

        <!--
            An implementation of `Sitecore.LayoutService.Serialization.ItemSerializers.IItemSerializer`.
            Determines what fields of an item should be serialized and writes them out as JSON. 
            The default implementation filters standard fields. Also available is
            `Sitecore.LayoutService.Serialization.ItemSerializers.AllFieldsItemSerializer`.
        -->
        <itemSerializer type="Sitecore.LayoutService.Serialization.ItemSerializers.DefaultItemSerializer, Sitecore.LayoutService" resolve="true"/>

        <!--
            An implementation of `Sitecore.LayoutService.ItemRendering.ContentsResolvers.IRenderingContentsResolver`.
            This is the default contents resolver -- it can be overridden on a per-rendering basis, as described above.
        -->
        <renderingContentsResolver type="Sitecore.LayoutService.ItemRendering.ContentsResolvers.RenderingContentsResolver, Sitecore.LayoutService">
            <IncludeServerUrlInMediaUrls>true</IncludeServerUrlInMediaUrls>
        </renderingContentsResolver>
    </rendering>

    <!--
        An implementation of Sitecore.LayoutService.Configuration.ISerializationConfiguration.
        Controls the `JsonSerializerSettings` used by the Layout Service and any transformation of the resulting JSON.
        The JSS `SerializationConfiguration` customizes JSON serialization to preserve the case of dictionary keys.
    -->
    <serialization type="Sitecore.JavaScriptServices.ViewEngine.LayoutService.SerializationConfiguration, Sitecore.JavaScriptServices.ViewEngine">

        <!--
            An implementation of `Sitecore.LayoutService.Serialization.ILayoutTransformer`.
            Provides full control over the shape of the output JSON to optimize it for the use of specific client needs.
            JSS optimizes the output for JavaScript consumption.
        -->
        <transformer type="Sitecore.JavaScriptServices.ViewEngine.LayoutService.Serialization.LayoutTransformer, Sitecore.JavaScriptServices.ViewEngine"/>
    </serialization>
</config>

The name attribute of the config node corresponds to the config parameter in the Layout Service URL:

/sitecore/api/layout/render/[config]?item=[path]&sc_lang=[language]&sc_apikey=[key]&tracking=[true|false]