The Sitecore Layout Service
The Sitecore Layout Service is the REST endpoint which provides data for Sitecore JSS apps. In order to preserve the full capabilities of Sitecore XP within JSS, it's necessary to expose Sitecore layout as structured data -- "rendering" to JSON rather than HTML markup. Much of the capability of the platform is based in the rendering engine -- Content Personalization, Content Testing, and the Experience Editor. By leveraging the same engine to produce structured JSON output, the Layout Service decouples "layout" and "rendering," enabling you to render Sitecore components in your chosen JavaScript framework.
The Layout Service provides additional data about the requested item as well:
- Includes field values and metadata about the requested item, including its ID and template.
- Outputs placeholders and their renderings in a nested tree structure, representative of the parent/child relationships in the layout. This simplifies the rendering logic in the client significantly.
- Serializes the content associated with the rendering. By default, this is the rendering's datasource item.
- Renders Sitecore fields to structured JSON based on field type, allowing structured use of field values and metadata (e.g. image
alt
text). - Includes customizable "context" data useful for rendering (e.g. data from
Sitecore.Context
such as the current site, user, and editing mode). - When executed in editing mode via the Experience Editor, includes:
- Rendered fields with Experience Editor markup for inline editing.
- Rendering and placeholder "chromes" from the rendering engine, which allows 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.
/sitecore/api/layout/render/[config]?item=[path]&sc_lang=[language]&sc_apikey=[key]&tracking=[true|false]
Parameter Description config
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.item
The path to the item, relative to the context site's home item or item GUID (ID). sc_lang
The language version of the item you wish to retrieve. sc_apikey
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 orsc_apikey
HTTP Header.tracking
(optional) 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, therefore minimizing the amount of data processed and sent over the wire.
/sitecore/api/layout/placeholder/[config]?placeholderName=/main&item=[path]&sc_lang=[language]&sc_apikey=[key]&tracking=[true|false]
This action accept all the same parameters as the
/render
action described above, plus one more below.Parameter Description placeholderName
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.Consider adding
tracking=false
if you use this action to avoid extra page visits registered within visit, which will be reflected in xDB.
Other general Sitecore query string parameters will work with the Layout Service as well, such as
sc_camp
for triggering an analytics campaign.
You should always invoke the Layout Service using a host name 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 -- e.g. @Html.Sitecore().Placeholder("content")
. In order
to make these "exposed" placeholders discoverable, the Layout Service adds a new field to the Sitecore rendering
definition.
This is not to be confused with the
Allowed Controls
on Placeholder Settings, which defines what renderings can be added to a placeholder. TheLayout Service Placeholders
field defines the placeholders that will be used within the rendering in your JavaScript component.
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 for particular Layout Service calls, set the tracking
parameter to false
.
NOTE: As of Sitecore 10.0.1, Sitecore sets the
Secure
flag 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, and 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 make use of the Traefik reverse proxy that is provided in the
docker-compose
environment.- Transform the Sitecore Web.config and set:
requireSSL
tofalse
andsameSite
toUnspecified
in thehttpCookies
configurationcookieSameSite
toUnspecified
in thesessionState
configuration- This is not recommended for production.
Invoking the Layout Service from JSS
The Sitecore JSS SDK provides a simple API to make utilizing the Layout Service easier. Enter your configuration into the fetchOptions
object and pass it into dataApi.fetchRouteData()
. The fetcher
option enables you to implement whichever data access method you wish. JSS ships with axios, which can be imported from src\dataFetcher.js
.
The dataApi
object is found in the @sitecore-jss\sitecore-jss
package but is also exposed via the framework-specific SDKs
import { dataApi } from '@sitecore-jss/sitecore-jss-react';
import { dataFetcher } from './dataFetcher';
const fetchOptions = {
fetcher: dataFetcher,
layoutServiceConfig: {
host: 'http://mysitecore',
configurationName: 'jss',
},
querystringParams: {
sc_lang: 'en',
tracking: false,
sc_apikey: '{00000000-0000-0000-0000-000000000000}',
sc_camp: 'FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF'
},
requestConfig: {
// AxiosRequestConfig -- https://github.com/axios/axios#request-config
// Note: `withCredentials: true` is added automatically
timeout: 3000,
headers: {
'X-JSS': 'Experience is asynchronous'
}
},
}
dataApi.fetchRouteData('/', fetchOptions).then(route => {
console.log(JSON.stringify(route, null, 2));
});