Thoughts on templates vs content type based pages

2025/03/18 11:09 PM

The training and other documentation for Xperience by Kentico details the creation of page templates when creating content types. Many projects I have worked with in Kentico 12 & 13 never utilize page templates. I am trying to understand this better and have some questions.

Is it recommended to create a page template for each content type used for pages?

What would the downside be to not using page templates (at all)?

In what case might you want to use the same template for multiple page content types?

Environment

Answers

2025/03/18 11:50 PM

I recommended using Page Templates for all pages back in the K12 MVC/KX13 days (2021 feels like a lifetime ago now). Our current guidance comes from that same perspective with the caveat that Xperience by Kentico supports a much simpler Page Template registration and Controller/View model setup than was possible in K12 MVC and KX13 and View Components (part of the PTVC pattern I was using) are not required because of Xperience's improved architecture.

My perspective is that most teams didn't use Page Templates because they didn't understand them and were struggling to even understand how to model content and create a good content authoring experience using Widgets and Sections. It didn't help that the Page Template APIs weren't well documented, there wasn't any good example code out there, and the setup was complex even if you understood it.

The main benefits of Page Templates over route-to-view or route-to-controller action are the following.

  1. If you only have 1 Page Template, the marketer never knows because it's auto-selected when they create a new page.
  2. If you want to give an alternate page layout or design in the future you only need to add a new Page Template which the marketer can now select - all the rest of your code can stay the same. The idea of evolving an Xperience by Kentico project over time is a very important concept to embrace and Page Templates help a team evolve web experiences in parallel streams without disrupting everything already in-place.
  3. Page Templates give you access to properties where you can store marketer customizable settings that apply to an entire template. You could use these to set any design or content options that are not part of a single Section or Widget, like opt-in page-level navigation. Yes, you could store these properties in Content type fields, but what happens when you have two templates that need different properties? Now you have page fields that only apply for specific templates, which becomes confusing.
  4. Templates are a content authoring feature, not a page rendering/content delivery feature, so they're all about giving the marketer more control and options at little cost with a very simple "grow up" story. Unfortunately there's no easy way to start with non-Page Template pages and convert them to use Page Templates without a database migration, so you might as well start with Page Templates.

If you want a real-world example, the Kentico Community Portal uses Page Templates for every content tree page.

2025/03/19 1:18 PM

What would be the protocol for migrating a K12 MVC site with no templates to an Xperience site with templates? Can you force them to use templates already created in xperience in the migration or does the DB need to be updated manually after?

2025/03/19 2:20 PM
Answer

What would be the protocol for migrating a K12 MVC site with no templates to an Xperience site with templates?

Page template data in Xperience by Kentico is stored in the database in CMS_ContentItemCommonData.ContentItemCommonDataVisualBuilderTemplateConfiguration.

Returning to the Community Portal example, a blog post page would have the following JSON in this column.

{
    "identifier": "KenticoCommunity.BlogPostPage_Default",
    "properties": null,
    "fieldIdentifiers": null
}

This means you could pre-populate this column when using the Kentico Migration Tool to migrate K12 Nodes/Documents to XbyK web page items.

Also, I dont see any examples where multiple content types are using one template.

Correct, that is an approach I haven't needed but it's fully supported.

The Kentico Community Portal uses separate templates for each web page content type so that these can evolve independently of each other, but it does have a general "Landing Page" catch-all content type with templates which is used for basic content pages.

You can see that Page Templates are registered with an attribute and one of the attribute properties is an array of content types that can use the registered template.

[assembly: RegisterPageTemplate(
    identifier: "KenticoCommunity.LandingPage_Default",
    name: "Landing Page - Default",
    propertiesType: typeof(LandingPageDefaultTemplateProperties),
    customViewName: "/Features/LandingPages/LandingPage_Default.cshtml",
    ContentTypeNames = [LandingPage.CONTENT_TYPE_NAME],
    Description = "Default Landing Page template with a heading",
    IconClass = "xp-l-header-text"
)]

If you want the template to be available to more than one content type then populate the ContentTypeNames array with multiple content type names - nothing magic here!

You can also use the older approach of defining and registering an IPageTemplateFilter, but I find ContentTypeNames handles all the filtering I need.

If you don't define any filters and don't provide a value to ContentTypeNames then your page template will be available to all web pages.

You can then use C# pattern matching to determine which view model type your template is being provided for the current request.

@model TemplateViewModel<MyTemplateProperties>

@{
    var templateModel = Model.GetTemplateModel<AViewModelBaseClassOrInterface>();
}

@if (templateModel is HomePageViewModel homeModel)
{
    <h1>...</h1>
}
else if (templateModel is ContactUsViewModel contactModel)
{
    <!-- ... -->
}

@* ... *@
2025/03/19 2:29 PM

Thank you, Sean! Your responses are most excellent and helpful!

To answer this question, you have to login first.