Template Conventions

In Optimizely CMS 13 (PaaS), the rendering system is designed to be predictable and discoverable. By following a set of strict naming and metadata conventions, developers can ensure that the correct view is resolved for every content item without writing manual route-mapping code.

This module details the technical mechanism of the Template Resolver and the attributes used to govern rendering behavior in an enterprise solution.

1. The Template Resolver Lifecycle

When the CMS middleware resolves a URL into a ContentLink, it passes that ID to the Template Resolver. The resolver’s job is to find the most compatible template, whether that is a view, ViewComponent, or controller, for that specific IContent type.

1.1 How Resolution Happens

1. Direct Match: Checks whether there is a controller or template specifically named after the content type.
2. Tag Inspection: If the render request includes a tag, such as Teaser or FullBody, the resolver filters for templates decorated with that tag.
3. Inheritance Fallback: If no specific template is found for a type, it falls back through base classes such as StandardPageData.

2. Governance through [TemplateDescriptor]

The [TemplateDescriptor] attribute is the developer’s primary tool for overriding default resolution logic. It allows you to define the metadata of your rendering head directly in code.

2.1 Key Parameters

• Default: If true, this becomes the primary template used when no tag is requested.
• Inherited: If true, the template is also valid for any class inheriting from the target type.
• TemplateTypeCategory: Defines whether the handler is a controller, a ViewComponent, or an external endpoint.

3. Implementing Display Options (Logical Tags)

One of the most powerful conventions in CMS 13 is the use of Display Options. This allows editors to choose how a block should look, such as full width versus sidebar, through a dropdown in the UI.

3.1 Step 1: Register the Options

These are defined in Startup.cs using the DisplayOptions API.

3.2 Step 2: Decorate the Views

Then, you create multiple templates for the same block type, each carrying a different tag in its descriptor.

4. Predictable View Locations

To keep a PaaS project maintainable for large teams, CMS 13 relies on standard ASP.NET Core view location conventions.

• Pages: /Views/[PageTypeName]/Index.cshtml
• Blocks: /Views/Shared/Components/[BlockTypeName]/Default.cshtml
• Partials: /Views/Shared/Blocks/[BlockTypeName].cshtml

Conclusion

Predictable rendering in CMS 13 comes from a combination of strict naming conventions and attribute-driven metadata. By using TemplateDescriptor to govern inheritance and the DisplayOptions API to give editors structured visual choices, you create a rendering system that is both flexible and technically sound. Mastering these conventions ensures that as your DXP infrastructure scales, the rendering layer remains fast, logical, and consistent across the full content tree.