HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Render content

Introduces the concept for rendering content in Optimizely.

Using MVC, rendering is based on controllers and views or Razor pages, which can be associated with templates for displaying content in certain contexts, for example, inside other content such as a page or through different devices and channels.

A template in Optimizely Content Management System (CMS) is a component that represents something that can render a piece of content. A template can reference, for example, an MVC controller, a Razor page, or a custom routing endpoint.



The examples are based on ASP.NET Core.

You can control the rendering of any content in Optimizely. Using templates, you can apply multiple templates for any content and have the system decide when to use which template.

These are the main components when working with templates:

  • TemplateDescriptor – Adds metadata in a template.
  • Tags and TemplateResolver – Selects the template to apply in the current context.
  • Display channels – Previews and renders content in different devices and resolutions.
  • Display options – Controls the content layout, such as in a content area.

A content type can have several templates; for example, one for a web channel and one for a mobile channel. A page can have a partial template to be used when you add the page to a content area. The Optimizely content model and templates are explained in Content types and Content templates.

Register and select templates

Templates must be registered to be evaluated for usage by the system. Registration is automatic if the template implements EPiServer.Web.IRenderTemplate<T>, where T states which model it can render. If you base your template on a base class in CMS, then you do not have to implement the interface because the base class does this explicitly. Base classes are  PageController<T>, PartialContentController<T>, PartialContentComponent<T>, AsyncPartialContentComponent<T>, BlockComponent<T> or AsyncBlockComponent<T>.


Optimizely uses TemplateDescriptor and IRenderTemplate<T> to resolve templates, where T is IContentData. Partial views following the standard ASP.NET MVC conventions are automatically registered (given that TemplateOptions.ScanViewsForTemplateRegistration is enabled). However, if you have partial views without controllers, you cannot use the TemplateDescriptor to register multiple templates against the content type. Instead, you can use EPiServer.Web.Mvc.IViewTemplateModelRegistrator, as shown in the example below. This interface registers your template models to the template model collection.

Example: Assume you have this block type inheriting from an Optimizely base class.

public class TeaserBlock: BlockData {
  public virtual string Heading {
  public virtual XhtmlString MainIntro {

If there is a partial view in /View/Shared/TeaserBlock.cshtml that has a model set to TeaserBlock, that partial view is automatically registered (given that TemplateOptions.ScanViewsForTemplateRegistration is enabled). To register multiple templates for the partial view, add a class, for example, in the Business folder of your project, inheriting from IViewTemplateModelRegistrator:

using EPiServer.Framework.Web;
using EPiServer.Web.Mvc;
using MyOptimizelySite.Models.Blocks;
using System;
using System.Collections.Generic;
using System.Linq;

namespace MyOptimizelySite.Business {
  public class ViewTemplateModelRegistrator: IViewTemplateModelRegistrator {
    public void Register(TemplateModelCollection viewTemplateModelRegistrator) {
      viewTemplateModelRegistrator.Add(typeof (TeaserBlock),
        new EPiServer.DataAbstraction.TemplateModel() {
          Name = "SidebarTeaser",
            Description = "Displays a teaser of a page.",
            Path = "~/Views/Shared/SidebarTeaserBlock.cshtml",
            Tags = new string[] {

Template selection

A page or a block can have multiple associated templates, and pages can have partial templates used when the page is added to a content area. The final template for rendering a content instance depends on the context. The TemplateResolver selects the most appropriate template for rendering in the current context based on the information in the TemplateDescriptor attribute, any defined display channels, and tags applied to a template. See Select templates.

Display channels and display options

Based on templates, these features let you control how content should render using different devices and how content should be laid out. See Display channels and Display options.

Navigation menus

See Lists and navigation for examples of how to build navigation menus using different methods.