Defining page template properties in MVC

When developing page templates, you can define properties that allow content editors to adjust the template appearance or behavior directly through the Kentico administration interface. Content editors can set the page template properties via a configuration dialog and the changes are then reflected on the website.

The page template can be shared by any number of pages, but each page has its own separate configuration of the available template properties.

Follow these steps to develop properties for a page template:

1. Create a model class that defines the page template properties
2. Define the configuration dialog to allow content editors to modify the properties
3. Handle the properties in the page template’s code

See the Example on this page for a scenario with full code samples.

Creating property models

The properties of a page template must be defined within a model class that implements the IPageTemplateProperties interface (available in the Kentico.PageBuilder.Web.Mvc.PageTemplates namespace).

Specify each page template property by creating a corresponding property in the model class. You can also set default values for the properties.

public class LandingPageProperties : IPageTemplateProperties
{
    // Defines a property and sets its default value
    public bool ShowTitle{ get; set; } = true;
}

We recommend storing page template property models in the ~/Models/PageTemplates/<page template name> folder.

Defining the configuration dialog

The configuration dialog provides a simple way for content editors to set values for page template properties. In the properties model class, you need to define editing form components for page template properties which you want to make editable in the configuration dialog. You can use the system’s default form components or develop custom form components.

1. Edit the page template’s property model class in your MVC project.

2. Define the visual interface of the configuration dialog:

   • Decorate the appropriate properties using the EditingComponent attribute (available in the Kentico.Forms.Web.Mvc namespace).

   • The attribute assigns and configures a form component, which is used as the input element for the given property in the configuration dialog.

     Note: To learn about the available options when using and configuring editing components for properties, see Assigning editing components to properties.

[EditingComponent(CheckBoxComponent.IDENTIFIER, Order = 0, Label = "Show title")]
public bool ShowTitle{ get; set; } = true;

Users can now click the Configure () icon when working with the given page template in the Kentico administration interface. This opens the page template properties dialog, and the configured property values affect the appearance and functionality of the edited page on the website. Every page using the template has its own separate configuration of the template’s properties.

Handling properties in page template code

In order for properties to have an effect on a template’s appearance or functionality, you need to retrieve the property values and adjust the template’s output code or logic correspondingly. The required steps depend on the development approach used to create the template (see Developing page templates in MVC for more information).

Basic page templates

For templates without a custom controller class, handle the property values in the template’s view.

The view must use the generic ComponentViewModel<TPropertyModel> class as its model, with the appropriate property model class as the generic type parameter. The system’s default controller ensures that the property values configured for the currently processed template are passed to the view. Retrieve the property values from the model’s Properties member, which returns an object of the specified property model class.

Page templates with a custom controller

To work with the properties in your page template controllers, the controller class must inherit from the generic PageTemplateController<TPropertyModel> base class, with the appropriate property model class as the generic type parameter.

public class LandingPageTemplateController : PageTemplateController<LandingPageProperties>

Retrieve the properties as a strongly typed object by calling the GetProperties method (provided by the base class). The method returns an object of the specified property model class. The object’s property values are loaded from the current configuration of the processed page template.

// Gets the value of a page template property
LandingPageProperties templateProperties = GetProperties();
bool propertyValue = templateProperties.ShowTitle;

You can then adjust the code of your controller based on the values of individual page template properties, or pass them to the page template’s view using an appropriate view model.

Do not directly pass the property model to your page template views. We strongly recommend creating a separate view model class, which you can then use to pass data to the page template view.

Example - Developing a page template with a configurable property

The following scenario will guide you through a step-by-step process of developing a simple default page template with a configurable property.

When finished, the template can be selected when creating a new landing page of the appropriate page type. The template contains two editable areas with default sections differentiated by a background color (the bottom section has a gray background) and displays a page title by default. Visibility of the page title can be adjusted in the administration interface using a check box in the property configuration dialog.

Property model

Create a property model LandingPageProperties.cs in the ~/Models/PageTemplates/LandingPage folder:

using Kentico.Forms.Web.Mvc;
using Kentico.PageBuilder.Web.Mvc.PageTemplates;

namespace LearningKit.Models.PageTemplates.LandingPage
{
    public class LandingPageProperties : IPageTemplateProperties
    {
       // Defines a property and sets its default value
       // Assigns the default Kentico checkbox component, which saves a boolean value 
       // depending on the state of the checkbox in the page template's configuration dialog
       [EditingComponent(CheckBoxComponent.IDENTIFIER, Order = 0, Label = "Show title")]
       public bool ShowTitle { get; set; } = true;
    }
}

View

Start by creating a _PageTemplateLayout.cshtml layout for page template views in the ~/Views/Shared folder. The layout calls extension methods that provide links to scripts and stylesheet files required for page builder editable areas:

@using Kentico.Activities.Web.Mvc
@using Kentico.OnlineMarketing.Web.Mvc
@using Kentico.PageBuilder.Web.Mvc
@using Kentico.Web.Mvc

@{
    Layout = null;
}
<!DOCTYPE html>

<html>
<head>
    <meta name="viewport" content="width=device-width" />
    <meta charset="UTF-8" />
    <title>@ViewBag.Title - Learning Kit</title>
    @Html.Kentico().PageBuilderStyles()
    @* Registers scripts that ensure logging of analytics data for A/B tests *@
    @Html.Kentico().ABTestLoggerScript()
</head>
<body>
    @RenderBody()
    @Html.Kentico().PageBuilderScripts()

    @* Registers scripts that ensure logging of campaign page visits and page-related activities *@
    @Html.Kentico().ActivityLoggingScript()
</body>
</html>

Create a view _LandingPageTemplate.cshtml in the ~/Views/Shared/PageTemplates folder:

@using Kentico.PageBuilder.Web.Mvc
@using Kentico.Web.Mvc

@using LearningKit.Models.PageTemplates.LandingPage

@model ComponentViewModel<LandingPageProperties>

@{
    Layout = "~/Views/Shared/_PageTemplateLayout.cshtml";
}

@{
    // Sets the page title to the name of the current page
    ViewBag.Title = Model.Page.DocumentName;
}

@if (Model.Properties.ShowTitle)
{
    <h1>@Model.Page.DocumentName</h1>
}

<div>
    <div>
        @Html.Kentico().EditableArea("top")
    </div>
    <div style="background-color: #eeeeee">
        @Html.Kentico().EditableArea("bottom")
    </div>
</div>

Template registration

Register the template into the system using the RegisterPageTemplate assembly attribute. We recommend adding a dedicated code file to your project’s ~/App_Start folder for the purposes of component registration, for example named PageBuilderComponentRegister.cs.

using LearningKit.Models.PageTemplates.LandingPage;

using Kentico.PageBuilder.Web.Mvc.PageTemplates;

[assembly: RegisterPageTemplate("LearningKit.LandingPageTemplate",
                               "Default Landing page template",
                               typeof(LandingPageProperties),
                               customViewName: "PageTemplates/_LandingPageTemplate",
                               IconClass = "icon-l-rows-2")]