Dev GuideAPI ReferenceUser Guide
HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunityDoc feedbackLog In
GitHubNuGetDev CommunityDoc feedback

The resulting rendering template for a requested content instance is selected based on page or partial renderers, tags and active display channels.

Note

The examples are based on MVC.

A page or a block can have multiple associated templates; for example, one for a web channel and one for a mobile device. Pages can also have a **partial template** used when the page is displayed inside the content area of another page. See [Rendering](🔗) and [TemplateDescriptor and tags](🔗).

If you register multiple templates, the `TemplateResolver` service selects the resulting rendering template using an algorithm based on content model, template types, rendering mode (page or partial rendering), tags, and inheritance. If needed, you can use _events_ to override the `TemplateResolver` selection.



A default `TemplateResolver` implementation selects templates based on the procedure below.

  1. The `EPiServer.Web.TemplateResolver.TemplateResolving` **event** is raised. If an event handler selects a template, that template is used with no further handling.

  2. All templates matching the desired **content type** are filtered according to the rendering mode**:** If t is a _page_, a suitable _controller_ is selected; if it is _partial rendering_, a suitable _partial controller_ or _partial view_ is selected. For partial templates, the list is filtered according to main template.

  3. If the template is requested with a specific **tag**, the list is filtered on that tag. If no template matching the tag exists, all templates from 2 are taken into account.

  4. If any **display channel** is active, and there are template tags matching that channel, templates are filtered for `DisplayChannel`. 

  5. From remaining templates, the **shortest inheritance chain** to the `TemplateModel` marked as **Default** and **not inherited,** is selected.

  6. If no match from 5, the **shortest inheritance chain** to `TemplateModel` that is marked as **Default,** is selected.

  7. If no match from 6, the **shortest inheritance chain** to `TemplateModel`, is selected.

  8. The `EPiServer.Web.TemplateResolver.TemplateResolved` **event** is raised, providing a chance to replace the selected template.

Note

The shortest inheritance chain means that a template that is registered **directly for the content model type** is preferred before a template registered for a base class or interface. For interfaces, the length of the inheritance chain is defined by following the inheritance chain upwards to see where the interface is implemented.

## Examples

The following examples assume that you have a content model and are using multiple rendering templates for different display channels. See [Content](🔗), [Rendering](🔗), and [Display channels](🔗) for more information.

### Select page rendering

The template selected to render a content instance depends on the specific context such as channel and tagging. For a template to be automatically registered for rendering, it has to implement `EPiServer.Web.IRenderTemplate<T>` (where T states which model it can render). If you use a **base class** like `PageController<T>` or `BlockComponent<T>` for your templates, you do not need to explicitly implement the interface. In addition, you can use the `TemplateDescriptorAttribute` to specify more details about the template such as tags and inheritance. See [TemplateDescriptor and tags](🔗).

**Example:** A content type model is defined as shown below.


Given that there are templates defined as follows:

All of the above templates are registered as templates for **MyPage**. You can register a template for both a base type and an interface (`MyFallbackController` and `PageTeaser` in the code sample), which are registered for `PageData`, not the specific type). If you want the template to be available for **all** subtypes, for example if you want to have a **fallback **template for content types without a specific template, set Inherited=true for the `TemplateDescriptor` attribute.
For the example above, a browser request for a page of the type _MyPage_ will result in the following:
  • If **no** `DisplayChannel` is active, the _MyPageTemplate_ template is selected because no tag is active (disqualifies `MyPageMobileTemplate`), and `MyPageTemplate` has shorter inheritance chain than `MyFallbackTemplate`. `MyPageTeaser` and `PageTeaser` are partial renderers and are filtered away.
  • If a `DisplayChannel` named _Mobile_ is active, the _MyPageMobileTemplate_ template is selected, since templates that have a tag matching active channels are preferred.
### Select block rendering
Blocks can be either a property on a page, or a shared block instance in a content area. The selection of a template for a block is similar to the selection of a page template, except that blocks can only be rendered in the context of a page template. Rendering of blocks is done using partial views or view components. When rendering a block in a page template, you can use tags to define how the block should be rendered.
**Example:** Templates defined for a _MyBlock_ block type.

You can also use a **tag **to define rendering in a specific area such as a _Sidebar_ in a page template:

See [TemplateDescriptor and tags](🔗) for more information on how to apply tags.
### Block layout in a content area
If you specify a tag for a content area, then content added to that area will use a template matching that tag. You can use **display options** to let editors define the layout of a block in a content area, from edit view. See [Display options](🔗).