Layout Service

Abstract

Get JSON-formatted Sitecore layout and content data for decoupled front-end applications.

The Sitecore Layout Service is a Sitecore Headless Services endpoint that exposes Sitecore layout information as structured JavaScript Object Notation (JSON) data.

The service leverages the Sitecore Rendering Engine to produce structured JSON output, decoupling layout and rendering, and allowing you to render Sitecore components with any front-end technology stack capable of consuming JSON data.

Tip

You can fetch data from the Layout Service using a REST or a GraphQL endpoint. For documentation about the GraphQL endpoint, refer to Sitecore Experience Edge for XM.

The following diagram shows the layout data response flow from Sitecore to decoupled front-end applications.

Layout Service request flow

Layout Service actions

The Layout Service exposes two actions:

  • Getting the output of the whole layout for the item.

  • Getting the output of a particular placeholder.

To resolve to the desired Site Context, invoke the layout service using the sc_site query string parameter or using a hostname because Layout Service paths are relative to the Home item of the site.

Getting the output of the whole layout for the item

To get the full layout output for an item, you must invoke the render endpoint of the Layout Service:

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

The available parameters are:

Parameter

Description

config

The name of the Layout Service configuration to use. For JSS, this is usually jss.

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 want to retrieve.

sc_apikey

An SSC API Key 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 sent through the sc_apikey HTTP Header.

sc_site

The name of the site to fetch data for. Needed for the analytics tracking included in Layout Service calls.

tracking

(Optional, only with Sitecore XP.) Enables/disables analytics tracking for the Layout Service invocation. Default is true.

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.

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

This action accepts the same parameters as the /render action described previously, as well as the following:

Parameter

Description

placeholderName

The name of the placeholder to render. You can retrieve the value of this parameter from the layout details in the Content Editor. Due to the dynamic placeholders used out of the box for the jss configuration, you must use the dynamic placeholder format here.

Caution

Add tracking=false when using this action to prevent invocations of the placeholder action from corrupting page visit data in xDB.

Anatomy of a Layout Service request

When the Layout Service receives a request, for example, /sitecore/api/layout/render/jss?item=/about , the following process occurs on the server:

Note

The jss represents a named configuration of the Layout Service. You can register your own named configurations to create application-specific Layout Service extensions. See Using a custom Layout Service configuration with JSS.

  1. An MVC controller responds and parses the ?item=/about parameter.

  2. The Layout Service performs an item lookup based on the item parameter, which takes into account the start item of the context site. The logic matches standard Sitecore URL handling. Item GUIDs are also allowed.

  3. After resolving the item, 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.renderPlaceholder pipeline. By using Sitecore MVC pipelines, the Layout Service output accounts for any personalization rules and/or content testing in the item's layout definition.

  4. Instead of rendering MVC views, a custom JavaScript serializer takes the component's data source item(s) and serializes them into a JavaScript object.

    Note

    You can customize a rendering's serialized output by creating an implementation of Sitecore.LayoutService.ItemRendering.IRenderingContentsResolver and specifying the type in the rendering's Rendering Contents Resolver field.

  5. The output is then assembled and returned as JSON.

Layout Service data

The Layout Service provides the following JSON-formatted structured data about the requested Sitecore item:

  • Field values and metadata, including the item's ID and template.

  • Placeholders and their renderings in a nested tree structure that illustrates the parent/child relationships in the layout. This simplifies the rendering logic in the client significantly.

  • Serialized 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).

  • Customizable context data, useful for rendering. For example, data from Sitecore.Context such as the current site, user, and editing mode.

When invoked in editing mode, the Layout Service includes data that supports inline editing, such as:

  • Rendered fields with editor markup for inline editing.

  • Additional markup for renderings and placeholders that enable the inline editor to insert editing controls.

Sitecore fields and Layout Service field serializers

The Layout Service can serialize the following types of Sitecore fields:

  • Rich Text

  • Image

  • General Link

  • Date / Datetime

  • Checkbox

  • Links (Droplink, Droptree, Grouped Droplink)

  • Multi-links (Multlist, Checklist, Treelist, Exten and their variants)

  • Number

  • File

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

Layout Service and Sitecore Placeholders

To return an item's full structured layout data, the Layout Service must know the placeholders on a rendering.

To make these exposed placeholders discoverable, the Layout Service Placeholders field must be populated.

LayoutService-ExposedPlaceholders10_.png

Warning

Do not confuse this with the Allowed Controls on Placeholder Settings, defining the renderings that can be added to a placeholder. The Layout Service Placeholders field defines the placeholders to use within the frontend rendering host.

Dynamic Placeholder Keys

By default, 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 which placeholder keys to render.

Layout Service and Sitecore Experience Platform Analytics

The Layout Service executes within the Sitecore MVC rendering engine, retaining all Sitecore analytics tracking and functionality.

If you do not want analytics tracking your front-end application or particular Layout Service calls, set the tracking parameter to false.