Sitecore Layout Service

Current version: 19.x

The Sitecore Layout Service is a Sitecore Headless Services endpoint that provides JSON formatted Sitecore content. You use the Sitecore Layout Service Client to communicate with the Layout Service, and you use the Sitecore Rendering Engine to render the content.

The Layout Service Client libraries are available as NuGet packages, and their name is prefixed with Sitecore.LayoutService.Client.

The SitecoreLayoutRequest model

The SitecoreLayoutRequest model instantiates to an intermediate Data Transfer Object that supports reading and writing of arbitrary properties. The Layout Service Client sends these properties to the Layout Service using query string keys.

The SitecoreLayoutRequest model includes a set of default properties with associated combined get/set methods. For example, request.ApiKey() gets the API Key value and request.ApiKey("value") sets the API Key value.

The default properties are:

Property

Method

Content

Sample

Query string key

API Key (required)

ApiKey() 

GUID

123e4567-e89b-12d3-a456-426614174000

sc_apikey

Item (required)

Path()

Content tree path

/articles

item

Site name

SiteName()

Human readable name

MySite

sc_site

Language

Language() 

ISO language code

en, en-GB.

sc_lang

The SitecoreLayoutResponse model

The Layout Service returns an object instantiated from the SitecoreLayoutResponse strongly typed model designed to allow navigation down to the field level. A SitecoreLayoutResponse object consists of several parts:

  • Request - the SitecoreLayoutRequest sent to the Layout Service.

  • Metadata - response metadata such as HTTP response headers.

  • Content - the deserialized JSON response.

  • Errors - the list of errors encountered while handling the SitecoreLayoutRequest object and building the SitecoreLayoutResponse object.

  • HasErrors - this is true if the Errors list is not empty.

Types and fields

Content uses the following types:

  • Route - maps to the Route object in the JSON response returned by Layout Service. Its fields are typed as a Dictionary<string, IFieldReader>.

  • Component - maps to objects in the list value of a placeholder. Its fields are typed as a Dictionary<string, IFieldReader>.

  • IFieldReader - maps to the field entries in a Route or Component. The implementation is provided by a serialization library such as Newtonsoft.

  • IField - various implementations of IField are provided by Layout Service Client. The interface is used as a marker to identify the types that can be read through an IFieldReader.

The Layout Service Client provides the following fields:

  • CheckboxField - a checkbox field.

  • ContentListField - a list of item link fields.

  • DateField - a date and time field.

  • FileField - a file field.

  • HyperLinkField - a link field.

  • ImageField - an image field.

  • ItemLinkField - a single item field.

  • NumberFieldc - a number field.

  • RichTextField - a rich text field.

  • TextField - a single line or a multi line text field.

Fields can implement multiple interfaces to expose different field properties, such as:

  • IValueField<T> - exposes a Value property of type T.

  • IEditableField - exposes markup before and after editable fields.

Syntax

The IFieldReader type exposes a Read() method that, when given a type that implements IField, returns an instance of the type populated with the data from the IFieldReader.

Component and Route both inherit the same base implementation that exposes Fields. In addition, they expose:

  • ReadField() - receives a type of IField and a string to read a specified field.

  •  ReadFields() - receives an arbitrary type that is populated with all the fields matching property names to field names.

REST Layout Service Client configuration for ASP.NET

The following example demonstrates the use of the Layout Service Client with the ASP.NET Rendering SDK in the ConfigureServices method of your application Startup class:

RequestResponse
services 
  .AddRouting() 
  .AddMvc() 

  // Configure the required Newtonsoft.Json serialization behavior for use
  // with the Layout Service Client.
  // The Layout Service Client requires Json.NET due to limitations in System.Text.Json.
  .AddNewtonsoftJson(o => o.SerializerSettings.SetDefaults()); 

  // Register the Sitecore Layout Service Client,
  // which is used by the ASP.NET Rendering Engine.
  .AddSitecoreLayoutService() 

  // Configure the default parameters for Layout Service Client requests.
  .WithDefaultRequestOptions(request => 
  { 
    request 

      // Optional language configuration, if the application is not using localized routes.
      // .Language("en")

      // The name of the Sitecore site which this application is rendering.
      .SiteName("website")

      .ApiKey("{00000000-0000-0000-0000-000000000000}");
  }) 

  // Provide the URL to the Layout Service on your Sitecore instance.
  // In production, this is typically a Content Delivery server.
  // In development, it might be a standalone combined Content Management
  // and Content Delivery instance.
  .AddHttpHandler("default", "https://<sitecore instance>/sitecore/api/layout/render/jss") 
  .AsDefaultHandler();

To access the Layout Service, you must provide the ID of the Sitecore Services Client API Key to the ApiKey method.

Do you have some feedback for us?

If you have suggestions for improving this article,