--- title: Defining page template properties related: - https://docs.kentico.com/13/developing-websites/page-builder-development.md - https://docs.kentico.com/13/developing-websites/page-builder-development/developing-page-templates.md - https://docs.kentico.com/13/multilingual-websites/setting-up-a-multilingual-user-interface/localizing-builder-components.md - https://docs.kentico.com/13/managing-website-content/using-page-templates.md --- > Agent instructions: > **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown. > > - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version. > - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt). When developing [page templates](https://docs.kentico.com/13/developing-websites/page-builder-development/developing-page-templates.md), you can define properties that allow content editors to adjust the template appearance or behavior directly through the 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](#creating-property-models) 2. [Define the configuration dialog to allow content editors to modify the properties](#defining-the-configuration-dialog) 3. [Handle the properties in the page template's code](#handling-properties-in-page-template-code) See the [Example](#example---developing-a-page-template-with-a-configurable-property) 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. ```csharp title="Example - Defining a property" public class LandingPageProperties : IPageTemplateProperties { // Defines a property and sets its default value public bool ShowTitle{ get; set; } = true; } ``` > **Tip:** You can use the _Newtonsoft.Json.JsonIgnore_ attribute to exclude dynamically computed page template properties from database serialization. **MVC 5 development model.** Applies only when building with ASP.NET MVC 5. If this page also covers ASP.NET Core, that version is in its own block. We recommend storing page template property models in the _\~/Models/PageTemplates/_ folder. **ASP.NET Core development model.** Applies only when building with ASP.NET Core. If this page also covers MVC 5, that version is in its own block. We recommend storing page template property models in the _\~/PageTemplates/_ 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](https://docs.kentico.com/13/developing-websites/form-builder-development/reference-system-form-components.md) or develop [custom form components](https://docs.kentico.com/13/developing-websites/form-builder-development/developing-form-components.md). 1. Edit the page template's property model class in your live site 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](https://docs.kentico.com/13/developing-websites/form-builder-development/reference-system-form-components.md), which is used as the input element for the given property in the configuration dialog. > **Note:** **Note**: To learn about the available options when using and configuring editing components for properties, see [Assigning editing components to properties](https://docs.kentico.com/13/developing-websites/form-builder-development/assigning-editing-components-to-properties.md). ```csharp title="Example - Setting an editing component" [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 administration interface](https://docs.kentico.com/13/managing-website-content/using-page-templates.md). 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. > **Tip:** **Advanced property options** > > - You can add dynamic [visibility conditions](https://docs.kentico.com/13/developing-websites/form-builder-development/adding-visibility-conditions-for-builder-component-properties.md) that restrict how and when properties are displayed in the template configuration dialog. > - If you need to create advanced property editors, you can implement [modal dialogs](https://docs.kentico.com/13/developing-websites/page-builder-development/developing-modal-dialogs-for-builder-component-properties.md). This allows users to set the template property's value in a custom dialog (a new window separate from the configuration dialog). ## Handling properties in page template code **MVC 5 development model.** Applies only when building with ASP.NET MVC 5. If this page also covers ASP.NET Core, that version is in its own block. 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](https://docs.kentico.com/13/developing-websites/page-builder-development/developing-page-templates.md) 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** 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** base class, with the appropriate property model class as the generic type parameter. ```csharp public class LandingPageTemplateController : PageTemplateController ``` Retrieve the properties as a strongly typed object via the **IPageTemplatePropertiesRetriever** service (_Kentico.PageBuilder.Web.Mvc_ namespace) and its **Retrieve** method. 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 section. ```csharp // Contains an instance of the IPageTemplatePropertiesRetriever service. For example, obtained via dependency injection. private readonly IPageTemplatePropertiesRetriever pageTemplatePropertiesRetriever; // Gets the value of a page template's property (e.g. within the Index action of the template's controller) LandingPageProperties properties = pageTemplatePropertiesRetriever.Retrieve(); 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. > **Info:** 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. #### Accessing template properties in POST actions Page template properties cannot be by default retrieved during POST requests. Such requests lack the context of the current page and template instance. To retrieve template properties in POST actions, you first need to include the properties into the data submitted by the corresponding HTML form in the template's output. Call the **Html.Kentico().ComponentPropertiesData** extension method within the given form tag in your template's view. ```csharp title="Example" using System.Web.Mvc.Ajax using Kentico.Web.Mvc using Kentico.PageBuilder.Web.Mvc ... @using (Ajax.BeginForm("PostAction", "LandingPageTemplate", null, new AjaxOptions { HttpMethod = "POST", UpdateTargetId = "templateForm" }, new { id = "templateForm" })) { @Html.Kentico().AntiForgeryToken() @Html.Kentico().ComponentPropertiesData() ... } ``` The method renders a hidden field that persists the template's properties and makes them available in controller actions via the **IPageTemplatePropertiesRetriever** service. **ASP.NET Core development model.** Applies only when building with ASP.NET Core. If this page also covers MVC 5, that version is in its own block. To access the template's properties, the template's view must use the generic **ComponentViewModel** class as its model, where the generic type parameter needs to match the model class registered for the template. The system ensures the property values configured for the currently processed template. Access the property values via the model's **Properties** member. The member returns an object of the property model class registered for the page template. ```xml @model ComponentViewModel @* Accesses the template's properties (LandingPageProperties in this example) *@ @Model.Properties ``` ### Accessing page template properties in POST actions Basic POST requests do not by default contain page template properties data. To access the properties of a template during POST actions (in the [controller class](https://docs.kentico.com/13/developing-websites/page-builder-development/developing-page-templates.md#handling-post-actions) handling POST requests), you first need to include the properties into the data submitted by the corresponding HTML form in the template's output. Call the **Html.Kentico().ComponentPropertiesData** extension method (or its [Tag Helper](https://docs.kentico.com/13/developing-websites/developing-xperience-applications-using-asp-net-core/reference-xperience-tag-helpers.md) equivalent) within the given form tag in your template's view. ```xml title="Example" using Kentico.Content.Web.Mvc ...
... @Html.Kentico().ComponentPropertiesData()
``` The method renders a hidden field that persists the template's current properties configuration. On the server, access the template's properties in the corresponding controller class via the **IPageTemplatePropertiesRetriever** service and its **Retrieve** method. Specify the template's properties class as the method's generic parameter: ```csharp title="Controller class handling the request" // Contains an instance of the IPageTemplatePropertiesRetriever service (e.g., obtained via dependency injection) private readonly IPageTemplatePropertiesRetriever pageTemplatePropertiesRetriever; // Gets the properties of the widget as a strongly typed object LandingPageProperties properties = pageTemplatePropertiesRetriever.Retrieve(); ``` ## Example - Developing a page template with a configurable property **MVC 5 development model.** Applies only when building with ASP.NET MVC 5. If this page also covers ASP.NET Core, that version is in its own block. The following scenario will guide you through a step-by-step process of developing a simple [page template](https://docs.kentico.com/13/developing-websites/page-builder-development/developing-page-templates.md) 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. > **Note:** **Note**: The following example is based on the [LearningKit project](https://github.com/Kentico/LearningKit-Mvc). To use the code samples in your project, you need to modify the namespaces, identifiers and other occurrences where _LearningKit_ is mentioned to match your project's name. ### Property model Create a property model **LandingPageProperties.cs** in the _\~/Models/PageTemplates/LandingPage_ folder: ```csharp 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 Xperience 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: ```csharp @using Kentico.Activities.Web.Mvc @using Kentico.OnlineMarketing.Web.Mvc @using Kentico.PageBuilder.Web.Mvc @using Kentico.Web.Mvc @{ Layout = null; } @ViewBag.Title - Learning Kit @Html.Kentico().PageBuilderStyles() @* Registers scripts that ensure logging of campaign page visits and page-related activities *@ @Html.Kentico().ActivityLoggingScript() @* Registers scripts that ensure logging of analytics data for A/B tests *@ @Html.Kentico().ABTestLoggerScript() @* Registers scripts that provide logging of web analytics data *@ @Html.Kentico().WebAnayticsLoggingScript() @RenderBody() @Html.Kentico().PageBuilderScripts() ``` Create a view **\_LandingPageTemplate.cshtml** in the _\~/Views/Shared/PageTemplates_ folder: ```csharp @using Kentico.PageBuilder.Web.Mvc @using Kentico.Web.Mvc @using LearningKit.Models.PageTemplates.LandingPage @model ComponentViewModel @{ 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) {

@Model.Page.DocumentName

}
@Html.Kentico().EditableArea("top")
@Html.Kentico().EditableArea("bottom")
``` ### 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**. ```csharp 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")] ``` **ASP.NET Core development model.** Applies only when building with ASP.NET Core. If this page also covers MVC 5, that version is in its own block. The following scenario will guide you through a step-by-step process of developing a simple default [page template](https://docs.kentico.com/13/developing-websites/page-builder-development/developing-page-templates.md) 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 checkbox in the property configuration dialog. > **Note:** **Note**: The following example is based on the [LearningKit project](https://github.com/Kentico/LearningKit-Core). To use the code samples in your project, you need to modify the namespaces, identifiers and other occurrences where _LearningKit_ is mentioned to match your project's name. ### Property model Create a property model **LandingPageProperties.cs** in the _\~/PageTemplates/LandingPage_ folder: ```csharp using Kentico.Forms.Web.Mvc; using Kentico.PageBuilder.Web.Mvc.PageTemplates; public class LandingPageProperties : IPageTemplateProperties { // Defines a property and sets its default value // Assigns the default Xperience 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 **\_TemplateLayout.cshtml** layout for page template views in the _\~/PageTemplates_folder. The layout calls extension methods that provide links to scripts and stylesheet files required for page builder editable areas: ```csharp @addTagHelper *, Kentico.Content.Web.Mvc @* This is a sample layout for use with page templates. This layout is not used anywhere on this site and is included only for demonstration purposes. *@ @ViewBag.Title - My site @RenderBody() ``` Create a view **\_LandingPageTemplate.cshtml** in the _\~/PageTemplates/LandingPage_ folder: ```csharp @addTagHelper *, Kentico.Content.Web.Mvc @using Kentico.PageBuilder.Web.Mvc @model ComponentViewModel @{ Layout = "~/PageTemplates/_TemplateLayout.cshtml"; } @section Styles { } @{ // Sets the page title to the name of the current page ViewBag.Title = Model.Page.DocumentName; } @if (Model.Properties.ShowTitle) {

@Model.Page.DocumentName

}
@* Renders editable areas using the editable-area Tag Helper *@
@section Scripts { } ``` ### Template registration Register the template in the system using the **RegisterPageTemplate** assembly attribute. We recommend adding a dedicated code file to your project's _\~/PageTemplates_ folder, for example named **PageTemplateRegister.cs**. ```csharp using Kentico.PageBuilder.Web.Mvc.PageTemplates; [assembly: RegisterPageTemplate("Company.LandingPageTemplate", "Landing page template", typeof(LandingPageProperties), customViewName: "~/PageTemplates/LandingPage/_LandingPageTemplate.cshtml", IconClass = "icon-l-rows-2")] ```