EPiServer 7 – Rendering of content

In EPiServer 6 a PageType states which page template (a WebForm) that should render a request for the page. This is a one to one relationship between PageType and template.

In EPiServer7 it is possible to have several renderers/templates (both WebForm and MVC are supported) registered for a .NET type (typically pages or blocks even if TemplateRepository and ITemplateResolver handles any type) or having one renderer registered for several .NET types. The way it works is that is that each renderer states which model it can render. That is we have changed the dependency so instead that a PageType states which renderer that should be used each renderer states which model class it can render.

Which renderer that is used to render a content instance depends on the specific context (e.g. is the rendering a partial rendering e.g. inside a ContentArea, is any DisplayChannel active, is the request tagged with a certain tag etc.). In this post I will try to clarify how the render selection is done.

Note: DisplayChannel is a new concept in CMS7 and presented shortly later in this post.

For a renderer to be automatically registered it has to implement EPiServer.Web.IRenderTemplate<T> (where T states which model it can render). If you use base classes for your renderer like PageBase<T>, ContentControlBase<T>, BlockControlBase<T>, PageController<T>, PartialContentController<T> or BlockControllerBase<T> then you do not need to explicitly implement the interface since that is done by the base class. In addition the RenderDescriptorAttribute can be used to specify more details about the renderer, like e.g. tags or if the renderer should be available for subtypes as well (by default renderers are only available for specified type).

As an example say that there is a model that is defined as:

[ContentType]
public class MyPage : PageData
{
    public virtual string Heading { get; set; }
    public virtual string MainIntro { get; set; }
    public virtual XhtmlString MainBody { get; set; }
}

and given that there are renderers defined as below:

public partial class MyPageTemplate : TemplatePage<MyPage>
{}

[RenderDescriptor(Tags = new string[] { RenderingTags.Mobile })]
public partial class MyPageMobileTemplate : TemplatePage<MyPage>
{}

[RenderDescriptor(Inherited = true)]
public partial class MyFallbackTemplate : TemplatePage<PageData>
{}

public partial class MyPageTeaser : ContentControlBase<MyPage>
{}

[RenderDescriptor(Inherited = true)]
public partial class PageTeaser : ContentControlBase<PageData>
{}

All of the above renderers will be registered as possible renderers for instances of MyPage which one that actually gets selected is dependent on the request.

It is possible to register the renderer for a base type or interface (as MyFallbackTemplate and PageTeaser above which are registered for PageData). In the case you want the template to be available for all subtypes as well you need to mark it with Inherited=true on the RenderDescriptor attribute. This can be useful e.g. if you want to have a fallback renderer for instances that still not have a specific renderer.

The algorithm to select a template is handled by ITemplateResolver and the default implementation is something like:

1. First event EPiServer.Web.ITemplateResolver.TemplateResolving is raised, if an event handler selects a template that template is used with no further handling.
2. Else all the templates matching a type is filtered according to if the rendering is a page rendering (in that case suitable templates are WebForm or MVC controller) or a partial rendering (in that case a suitable template is a WebControl, UserControl, MVC partial controller or a MVC partial view). For partial renderers the list is filtered according to main renderer, that is if the main request is a e.g. handled by a WebForm then only partial web form renderers are taken into account for partial renderer and the same applies if main renderer is an MVC renderer then only partial MVC renderers are taken into account.
3. If the template is requested with a specific tag the list is filtered on that tag (e.g. can rendering of a ContentArea be tagged with e.g. “SideBar” and then renderers with matching tag is preferred).
4. If no template matched tag continue with all templates from point 2.
5. If any DisplayChannel is active and there are templates with a Tag matching the active channel the templates are filtered to the ones matching the DisplayChannel.
6. From the remaining templates select the “closest” TemplateModel that is marked as Default (can be set on RenderDescriptor attribute) and not inherited.
7. If no match from 5 select “closest” TemplateModel that is marked as Default.
8. If no match from 6 select “closest” TemplateModel.
9. Event EPiServer.Web.ITemplateResolver.TemplateResolved is raised, giving chance to replace selected template.

With “closest” above means the template model with shortest “inheritance chain”. That means that a template that is registered direct for the model will be preferred before a template registered for a base class. It is possible to register templates for interfaces as well. For interfaces the length of the “inheritance chain” is defined by walking the inheritance chain upwards and see where the interface is implemented.

There is also a possibility in admin mode (on PageType/BlockType) to “override” which renderer that should be used by default. In that case the check for “closest” template will be skipped and instead that template model will be used.

So in the example above a request in a “ordinary web browser” for a page of type MyPage (assuming no DisplayChannel is active) the template MyPageTemplate will be selected since then no tag is active (disqualifies MyPageMobileTemplate)  and MyPageTemplate has shorter inheritance chain than MyFallbackTemplate (MyPageTeaser and PageTeaser is partial renderers and will be filtered away when selecting a page renderer).

And in case there is a DisplayChannel named “Mobile” active for a request, e.g. an implementation that check if request is from a mobile device (see SDK documentation for DisplayChannel) then the template MyPageMobileTemplate will be selected, since when selecting templates we will prefer templates that have a tag matching active channels.

Blocks

The selection of a renderer for a block is similar to the selection for a page renderer with the difference that since a block is rendered in the context of a page (either it is a property on a typed page or a shared block instance rendered in a content area) the selection of the block renderer is done in context of the page renderer. This means you can have both a WebForm renderer for your block (e.g. an user control) and a MVC renderer ( e.g. a partial view or a partial controller) then depending on if the block is rendered in the context of a WebForm page or a MVC page the suitable renderer will be selected. When rendering a ContentArea or a block property on a page it is also possible to specify a tag as example below for WebForms resp. MVC:

<EPiServer:Property runat="server" PropertyName="MyContentArea"  RenderSettings="{'Tag':'Sidebar'}"/>

<EPiServer:Property runat="server" PropertyName="MyBlockProperty" RenderSettings="{'Tag':'Sidebar'}"/> 

<%: Html.PropertyFor(m => m.MyBlockProperty, new { Tag = RenderingTags.Sidebar })%>

<%: Html.PropertyFor(m => m.MyContentArea, new { Tag = RenderingTags.Sidebar })%>

When specifying a tag then renderers with a matching tag will be preferred.

Preview of block during on page editing

Normally a block is displayed in the context of a page (e.g. rendered inside a ContentArea ). Therefore a block renderer is typically a partial renderer like a UserControl or Partial MVC controller/Partial View. However when a shared block instance is edited then we need to render the shared block instance with a page renderer. So for editing purposes it is useful to register a page renderer that can be used when editing shared block instances. Below is a WebForm example on such a renderer:

[RenderDescriptor(Inherited=true, Tags= new string[]{RenderingTags.Preview})]
public partial class PreviewBlock : SimplePage, IRenderTemplate<IContentData>

And in MVC an example of a page controller for editing of shared block could be defined as:

[RenderDescriptor(Inherited = true, Tags = new string[] { RenderingTags.Preview })]
public class PreviewBlockController : ActionControllerBase, IRenderTemplate<IContentData>

Note that the renderers used above are tagged with “Preview”, this is to ensure they only will be used during editing. The way it works is that when selecting a renderer in edit mode first an selection for a page renderer is selected as described above. If no template is found then we try to select a renderer with a tag RenderingTags.Preview.

IViewTemplateModelRegistrator

As mentioned before instances implementing EPiServer.Web.IRenderTemplate<T> will be automatically registered. The same goes for partial views that follows the “standard” ASP.NET MVC conventions. Say for example that there is a block type like:

[ContentType]
public class TeaserBlock : BlockData
{
    public virtual string Heading { get; set; }
    public virtual XhtmlString MainIntro { get; set; }
}

and then if there is a partial view as in /View/Shared/TeaserBlock.cshtml that has a model set to TeaserBlock, that partial view will also be automatically registered. However since it is not possible to set RenderDescriptor attribute on a partial view it is also possible to implement EPiServer.Web.Mvc.IViewTemplateModelRegitrator to register a partial view. An example on a registration of a partial view through that interface is like:

viewTemplateModelRegistrator.Add(typeof(TeaserBlock),
               new DataAbstraction.TemplateModel()
               {
                   Name = "SidebarTeaser",
                   Description = "Displays a teaser of a page.",
                   Path = "~/Views/Shared/SidebarTeaserBlock.cshtml",
                   Tags = new string[]{RenderingTags.Sidebar}               }
           );

Path Resolving

For WebForms and UserControls the virtual path to the aspx or ascx has to be known to be able to load the page/usercontrol. There is a possibility to specify the path on the RenderDescriptor attribute. If the path is not specified then we will try to resolve the path according to the namespace. That means that if your folder structure follows the namespace then it should not be needed to explicitly specify the path.

DisplayChannel

A DisplayChannel is an instance of a class that for each request is matched to see if it is considered active or not (similar to a Visitor Group), see SDK for DisplayChannel information. There is a similar concept called Display Mode introduced in MVC4. For MVC templates we rely on the MVC4 implementation. However the registration should be done against EPiServer and not directly to ASP.NET MVC (this is needed to make it possible for editors to be able to preview the site as if a Display Channel where active).

Whenever a display channel is active templates with a tag that matches the channel will be preferred. So for example say there is a display channel implementation that returns true for mobile devices (named “Mobile”) and then whenever that channel is active templates with tag “Mobile” will be preferred. That means you can choose to have duplicate templates for certain models, and then the one tagged with the name of a channel will be rendered when that channel is active.