Xperience Page Template Utilities

Utilities to help quickly create and register MVC Page Templates in Kentico Xperience

Dependencies

This package is compatible with ASP.NET Core 3.1 -> ASP.NET Core 5 and is designed to be used with .NET Core / .NET 5 applications integrated with Kentico Xperience 13.0.

How to Use?

1. First, install the NuGet package in your ASP.NET Core project

   dotnet add package XperienceCommunity.PageTemplateUtilities

2. Create an implementation of PageTypePageTemplateFilter for a given Page Type and register some Page Templates

   [assembly: RegisterPageTemplate(
       "Sandbox.HomePage_Default",
       "Home Page (Default)",
       typeof(HomePageTemplateProperties),
       "~/Features/Home/Sandbox.HomePage_Default.cshtml")]
   
   public class HomePageTemplateFilter : PageTypePageTemplateFilter
   {
        public override string PageTypeClassName => "Sandbox.HomePage";
   }

3. Register all IPageTemplateFilter implementations with the IServiceCollection

   public class Startup
   {
       public void ConfigureServices(IServiceCollection services)
       {
           services.AddPageTemplateFilters(Assembly.GetExecutingAssembly());
       }
   }

How Does It Work?

The PageTypePageTemplateFilter is simplest if your Page Templates follow some conventions, but allows for full customization.

In the example below, Home Page (Default) will match the filter and be allowed for selection for Sandbox.HomePage Page Types, but Home Page (Featured) does not have an Identifier (Sandbox_PageTemplate_HomePage_Featured) that matches the prefix of Sandbox.HomePage_, so it will not be displayed for selection for Sandbox.HomePage Page Types. It would need to be changed to Sandbox.HomePage_Featured to match the default filter, which follows the pattern of matching Page Templates with a Identifier prefix of $"{PageTypeClassName}_".

[assembly: RegisterPageTemplate(
    "Sandbox.HomePage_Default",
    "Home Page (Default)",
    typeof(HomePageTemplateProperties),
    "~/Features/Home/Sandbox.HomePage_Default.cshtml")]

[assembly: RegisterPageTemplate(
    "Sandbox_PageTemplate_HomePage_Featured",
    "Home Page (Featured)",
    typeof(HomePageTemplateProperties),
    "~/Features/Home/Sandbox_HomePage_Featured.cshtml")]

public class HomePageTemplateFilter : PageTypePageTemplateFilter
{
    public override string PageTypeClassName => HomePage.CLASS_NAME;
}

The filter can be overridden to allow you to match however you would like. It has a signature of:

Func<PageTemplateDefinition, PageTemplateFilterContext, string, bool> PageTemplateFilterBy

The customization below would match an Identifier like _Sandbox.HomePage-Default:

public class HomePageTemplateFilter : PageTypePageTemplateFilter
{
    public override string PageTypeClassName => HomePage.CLASS_NAME;

    public override Func<PageTemplateDefinition, PageTemplateFilterContext, string, bool> PageTemplateFilterBy { get; } =
        (definition, context, className) => definition.Identifier.StartsWith($"_{className}-", StringComparison.OrdinalIgnoreCase);
}

We could even skip using the className entirely and match against the definition or context with some hardcoded values, but at that point it's probably best to implement the IPageTemplateFilter directly.

Troubleshooting

InvalidOperationException: The view on path '~/Views/Shared/PageTypes/<ClassName>.cshtml' could not be found and there is no page template registered for selected page

Live Site

This error is caused by the CMS_Document.DocumentPageTemplateConfiguration column not being populated for the Page you are trying to display.

'~/Views/Shared/PageTypes/<ClassName>.cshtml' is the default path for Basic ("Route-to-View") Content Tree Routing. Xperience uses this View path when no [RegisterPageRoute] attributes are found and the Page has no Page Template configuration.

If this error occurs on the Live Site, you need to update this column with a value that looks like the following:

{
  "identifier": "<PageTemplateIdentifier>",
  "properties": {}
}

You can expose the DocumentPageTemplateConfiguration column in your Page "Content" tab by adding it as a Page field to the Page's Page Type using a Text Area Form Control. After you add the value (and publish the Page if it's under workflow) you can remove the field from the Page Type.

Administration

If this error only appears when trying to view the Page in the Page Builder, it means you have Page versioning enabled and the value of the Page's "Document" fields in the CMS_VersionHistory table do not have a populated DocumentPageTemplateConfiguration. You should follow the steps in the Live Site instructions and Save/Publish the latest version of the Page with the DocumentPageTemplateConfiguration populated.

Contributing

To build this project, you must have v6.0.300 or higher of the .NET SDK installed.

If you've found a bug or have a feature request, please open an issue on GitHub.

If you'd like to make a contribution, you can create a PR on GitHub.

References

Kentico Xperience

• Kentico Xperience Design Patterns: MVC is Dead, Long Live PTVC
• Filtering Page Templates