Layout and site requirements for ASP.NET Core rendering

Abstract

Overview of site and layout requirements for site definitions, Experience Editor support, JSON renderings, and dynamic placeholder keys for ASP.NET Core rendering.

When you are building your site and layout structure for the Layout Service and ASP.NET Core rendering, there are some important differences from development with Sitecore MVC. Keep these in mind as you structure your site, or restructure existing content for use with ASP.NET Core.

Note

These differences are familiar to developers who have worked with JSS, especially when using a Sitecore-first workflow.

Configuring your site definition

Even though the rendering host is the front door to your site, you still need a configured site definition for use with the Layout Service. When configuring a site definition for your ASP.NET Core rendered site:

  • Configure the rootPath as you would for any Sitecore site.

  • Configure the hostName or targetHostName URL as the external-facing host name of your Content Delivery (CD) server. This host is used when the Layout Service outputs media library URLs (if you are not using a CDN).

  • The site name should be configured in your Layout Service Client default request values.

Configuring for Experience Editor support

To support the Experience Editor, you must configure your Layout, Site Root, and App Configuration appropriately.

Using JSON renderings

When creating new renderings for use on your ASP.NET Core site, do not use Sitecore MVC rendering types such as Controller rendering or View rendering. Always use a Json Rendering (/sitecore/templates/Foundation/JavaScript Services/Json Rendering).

This rendering type is serialized by the Layout Service with the data needed by your ASP.NET Core components for rendering. Important fields on a Json Rendering include:

Field

Description

Component Name

This populates the componentName property in your Layout Service output. When configuring components in the Rendering Engine, this is the name that you map to.

Datasource Location

Behaves the same as in Sitecore MVC development.

Datasource Template

Behaves the same as in Sitecore MVC development.

Always Display Field Editor Button in Experience Editor

Enables a field editor on the component in the Experience Editor, useful for editing of non-inline field types.

Field Editor Displayed Fields

Configures the fields for the above field editor (default is all fields).

Cacheable (and related)

Configures output caching for the component. See Implementing Output Caching for the Layout Service.

Rendering Contents Resolver

Allows specifying a custom serialization configuration / C# class when outputting data for the rendering. See Creating a rendering with a contents resolver.

Layout Service Placeholders

Important

To output the full structured layout of an item, the Layout Service needs to know what placeholders are present on a rendering.

To make these exposed placeholders discoverable, the Layout Service adds this field to the Sitecore rendering definition.

Select any child placeholders which you wish to use in this rendering (e.g. <sc-placeholder name="child-placeholder"></sc-placeholder>).

Using dynamic placeholder keys

For simplicity, the Layout Service assumes that all placeholders other than root placeholders (usually header, main, footer, etc.) are dynamic placeholders.

This means that in order for components in a page's layout to be output by the Layout Service, they must be addressed using a dynamic placeholder key in the format {placeholder key}-{rendering unique id}-0. For example:

/main/accordion-{3A59ED89-58AB-4B51-8F9C-6100453DDFEC}-0

This means that using the Content Editor to add renderings to a page is usually impractical.

Instead, open the page in the Experience Editor, which calculates the required key for you. It is also possible to open __Standard Values items in the Experience Editor from the Publish ribbon.

Note

The Layout Service does not support indexed dynamic placeholders. The final value in the key is always zero.