The Sitecore Layout Service
The Sitecore Layout Service exposes Sitecore layout as structured data for Sitecore JSS apps, allowing JSS applications to preserve the full capabilities of Sitecore XP. Instead of rendering HTML markup, the endpoints return JSON.
The Sitecore Layout Service comes with a REST and a GraphQL endpoint.
The Layout Service provides additional data about the requested items, as follows:
It includes field values and metadata about the requested item, including its ID and template.
It outputs placeholders and their renderings in a nested tree structure, representing the parent/child relationships in the layout and simplifying the rendering logic in the client.
It serializes the content associated with the rendering. By default, this is the rendering's datasource item.
It renders Sitecore fields to structured JSON based on field types, allowing for structured use of field values and metadata (for example, image alt text).
It includes customizable "context" data helpful in rendering (for example, data from
Sitecore.Contextsuch as the current site, user, and editing mode).
When executed in editing mode via the Experience Editor, it includes:
- Rendered fields with Experience Editor markup for inline editing.
- Rendering and placeholder markup from the rendering engine, allowing the Experience Editor to insert editing controls.
Using the Layout Service
There are two actions that Layout Service exposes:
Getting the output of the whole layout for the item.
The name of the Layout Service configuration to use. For JSS, this will usually be
jss. More information can be found below on customizing Layout Service configurations.
The path to the item, relative to the context site's home item or item GUID (ID).
The language version of the item you wish to retrieve.
An SSC API Key which has been configured for use with the Layout Service controller (
Sitecore.LayoutService.Mvc.Controllers.LayoutServiceController, Sitecore.LayoutService.Mvc). An API Key is required in the query string or
(optional, for Sitecore XP only) Enables/disables analytics tracking for the Layout Service invocation. Default is
true. See details below on the Layout Service and Analytics.
Getting the output of a particular placeholder.
This action is useful in special circumstances when your app needs to access a portion of the layout, minimizing the amount of data processed and sent over the wire.
This action accepts all the same parameters as the
/renderaction described above, plus one more below.
The name of the placeholder to render. The value of this parameter can be retrieved from the layout details in Content Editor. Due to the dynamic placeholders used out of the box for
jss, configuration, make sure you use the dynamic placeholder format here.
tracking=falseif you use this action to avoid extra page visits registered within the visit, which will be reflected in xDB.
Other general Sitecore query string parameters will also work with the Layout Service, such as
sc_campfor triggering an analytics campaign.
You should always invoke the Layout Service using a hostname which will resolve to the desired Site Context, as Layout Service paths are relative to the site Home item. In addition, the site context is needed for the analytics tracking included in Layout Service calls.
The Layout Service and Sitecore Placeholders
To output the full structured layout of an item, the Layout Service needs to know what
placeholders are present on a rendering. Previously, this was not exposed as data on a rendering,
rather just through the code of the rendering itself -- for example,
@Html.Sitecore().Placeholder("content"). To make these "exposed" placeholders discoverable, the Layout Service adds a new field to the Sitecore rendering
This is not to be confused with the
Allowed Controlson Placeholder Settings, which defines what renderings can be added to a placeholder. The
Dynamic Placeholder Keys
By default, JSS's configuration of the Layout Service assumes that all placeholders other than the root placeholder (usually
main) are dynamic placeholders and will use Sitecore's built-in dynamic placeholder logic to determine the actual placeholder keys to "render."
Layout Service and Analytics
The Layout Service executes within the Sitecore MVC rendering engine and thus retains all Sitecore analytics tracking and functionality. This means that if you use the Layout Service for routing in your JSS app, each route change will reflect as a page view in your analytics data. To avoid confusing URLs in your analytics data, the Layout Service will set the resolved
item and its path as the tracked item and URL, respectively.
If you don't want analytics tracking for your JSS app or particular Layout Service calls, set the
tracking parameter to
NOTE: As of Sitecore 10.0.1, Sitecore sets the
Secureflag on all cookies by default. This can impact JSS local development in Connected and Headless modes, as the proxied Sitecore cookies (including analytics cookies) will be rejected by the browser if your application is not running under HTTPS. Thus visits will not be tracked, and content may not be personalized. To work around this, you can either:
- Enable HTTPS in your local environment by modifying the node server, using a local reverse proxy, or using a service such as ngrok.
- If you are running Sitecore in containers for development, you can use the Traefik reverse proxy provided in the
- Transform the Sitecore
- This is not recommended for production.