Layout Service Extensibility
You have a number of options for customizing the output of the Layout Service.
Looking for Layout Service basics?
Anatomy of a Layout Service Request
When Layout Service receives a request, this is what happens on the server:
- When the
/sitecore/api/layout/render/jss?item=/aboutservice is invoked, an MVC controller responds and parses the
jssportion of this route refers to a particular named configuration of the Layout Service. These can be used to create app-specific layout service extensions by registering your own.
An item lookup is performed based on the
itemparameter which takes the context site's start item into account. The logic should match standard Sitecore URL handling. Item GUIDs are also allowed.
After the item is resolved, the Layout Service utilizes placeholder data in Layout and Rendering definition items to render the item to an object structure, making use of the
mvc.renderPlaceholderpipeline. By using Sitecore MVC pipelines, the Layout Service output will account for any personalization rules and/or content testing in the item's layout definition.
Instead of rendering MVC views, a custom JS serializer will take component's data source item(s) and will serialize them into a JS object.
A rendering's serialized output can be customized by creating an implementation of
Sitecore.LayoutService.ItemRendering.IRenderingContentsResolverand specifying the type in the rendering's
Rendering Contents Resolverfield.
- The output then assembled and returned as JSON.
Layout Service Context
getLayoutServiceContext pipeline allows you to add context data which is returned with particular Layout Service configurations and/or JSS apps. Context data appears under the
context object in the LS output.
See the Extending Route Context Data Recipe for more information.
JSS and the Layout Service provide several options for customizing the serialized data provided with a rendering, if you need something other than the serialized datasource item.
See the Customizing Layout Service Rendering Output Recipe for more information.
Out of the box, the Layout Service can serialize the following types of Sitecore fields:
- Rich Text
- General Link
- Date / Datetime
- Links (Droplink, Droptree, Grouped Droplink)
- Multi-links (Multlist, Checklist, Treelist and their variants)
- Plain text (Single-line text, Multi-line text)
All other field types are treated as plain text as well, and are output with their raw value. If you wish to customize the serialization of a particular field type, the basic steps are:
- Create an implementation of
- Override the
WriteValuemethod and utilize the
JsonTextWriterto create your custom JSON structure for the
- Create an implementation of
rgs.Resultto an instance of your
- Patch the
getFieldSerializerpipeline within the
layoutServicepipeline group with your
BaseFieldSerializerimplementation. Be sure to
GetDefaultFieldSerializerprocessor, and populate the
FieldTypeslist with the desired Sitecore field type(s).
Layout Service Configuration
The Layout Service JSON rendering process is highly configurable, and allows you to customize specific aspects of the Layout Service. Configurations are found in the Sitecore configuration at the path
name attribute of the
config node corresponds to the
config parameter in the Layout Service URL.
JSS Layout Service Configuration
In terms of modifying serialization configuration, keep in mind that you can change the whole JSON beside field names. Field names can be changed in Sitecore, if you need to e.g.: have them camel-cased, you need do it in Sitecore. So basically serialization configuration is responsible for changing JSON on which user don't have influence.
Using a custom Layout Service configuration with JSS
Changing the Layout Service configuration used by JSS should be done with care. Changes to object shape, serialization, placeholder processing, etc. may break the JSS SDKs and/or may conflict with assumptions made by the JSS import process.
If you wish to customize any elements of the
jss Layout Service configuration, we recommend using the
to "copy" in the existing configuration, and then customize within that element. This will help reduce needed
changes to your configuration, should the
jss configuration change during an upgrade.
After defining your custom configuration, you may also want / need to add the configuration name to the list of
<AllowedConfigurations> for the
renderJsonRendering pipeline. Doing so will ensure that the
PlaceholderTransformer code that executes for the default
jss configuration will execute for your custom configuration as well.
Note: This is only relevant if your custom configuration will be delivering output that is similar in shape to the default JSS configuration. If your custom configuration is not related to JSS or doesn't depend on anything from the default
jssconfiguration, this step is not necessary.
A Sitecore config patch for a custom layout service named config that is based on the default
jss named config is below:
After patching in your custom configuration, you can utilize it in your JSS App via the
You'll need to ensure that you provide this configuration name in your client code as well when invoking Layout Service via the
dataApi (see examples above).