Sitecore Layout Service
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 the 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) |
|
|
| |
Item (required) |
|
Content tree path |
|
|
Site name |
|
Human readable name |
|
|
Language |
|
|
|
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
- theSitecoreLayoutRequest
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 theSitecoreLayoutRequest
object and building theSitecoreLayoutResponse
object. -
HasErrors
- this is true if theErrors
list is not empty.
Types and fields
Content
uses the following types:
-
Route
- maps to theRoute
object in the JSON response returned by the Layout Service. Its fields are typed as aDictionary<string, IFieldReader>
. -
Component
- maps to objects in the list value of a placeholder. Its fields are typed as aDictionary<string, IFieldReader>
. -
IFieldReader
- maps to the field entries in aRoute
orComponent
. The implementation is provided by a serialization library such as Newtonsoft. -
IField
- various implementations ofIField
are provided by the Layout Service Client. The interface is used as a marker to identify the types that can be read through anIFieldReader
.
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. -
NumberField
- a number field. -
RichTextField
- a rich text field. -
TextField
- a single line or a multiline text field.
Fields can implement multiple interfaces to expose different field properties, such as:
-
IValueField<T>
- exposes aValue
property of typeT
. -
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 ofIField
and astring
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:
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 that 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.
GraphQL Layout Service Client configuration for ASP.NET
The following example demonstrates how to configure a Layout Service client using a GraphQL endpoint:
services
.AddRouting()
.AddMvc()
// Register the Sitecore Layout Service Client used by the ASP.NET Rendering Engine.
.AddSitecoreLayoutService()
// The name of the Sitecore site the application is rendering.
var siteName = "website";
// The ID of the Sitecore Services Client API Key to access the GraphQl endpoint and Layout Service.
var apiKey = "{00000000-0000-0000-0000-000000000000}";
// The URL to the GraphQl Edge Scheme Endpoint on your Sitecore instance.
// In production, this is typically an Experience Edge environment.
// In development, it might be a standalone combined Content Management.
var uri = "https://<sitecore or edge instance>/<graphql schema url>";
// Configure GraphQl Handler for interacting with Layout Service
.AddGraphQlHandler("default" ,siteName , apiKey, uri)
.AsDefaultHandler();