Selecting template based on tag

Introduction

This document describes how to control which template that is used to render a referenced content using tags.

Example

Given that there is a block registered as follows:

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

It is possible to have several templates defined for the same model. The example below registers two different templates for the same model. One is DefaultTeaserTemplate that has property Default set to true in TemplateDescriptor attribute which states that this is the default template to use when rendering instances of the model. The other template is another template that is more suitable when rendering in a Sidebar area and is therefore marked with Tag Sidebar.

[TemplateDescriptor(Default = true)]
public partial class DefaultTeaserTemplate : BlockControlBase<Teaser>
{ }

[TemplateDescriptor(Tags = new string[] { RenderingTags.Sidebar })]
public partial class SidebarTeaserTemplate : BlockControlBase<Teaser>
{ }

If you use Property web control to render a ContentArea you can specify the tag by using RenderSettings attribute as follows:

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

If you use ContentControl web control to render a ContentData instance you can specify the tag by using Tag attribute as follows:

<EPiServer:ContentRenderer Tag="<%#EPiServer.Framework.Web.RenderingTags.Sidebar%>" CurrentData=<%#ContentData%> runat="server" />

If you use MVC to render a ContentArea property you can specify the tag by using Tag attribute as follows:

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

By default when a template renderer is associated with a Tag then that renderer will only be available when the calling context (given by for example Property, ContentControl, PropertyFor) has a matching tag. By setting the attribute AvailableWithoutTag to true on your template the template will be available also when calling context has no tag specified. Se example below:

[TemplateDescriptor(AvailableWithoutTag = true, Tags = new string[] { RenderingTags.Sidebar })]
public partial class SidebarTeaserTemplate : BlockControlBase<Teaser>
{ }