---
title: Page template properties
related:
  - https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder.md
  - https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/page-templates-for-page-builder.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/documentation/developers-and-admins/development/builders/page-builder/page-templates-for-page-builder.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](#create-property-models)
2. [Define the configuration dialog to allow content editors to modify the properties](#define-the-configuration-dialog)
3. [Handle the properties in the page template's code](#handle-properties-in-page-template-code)

> **Tip:** **Advanced page template example**
>
> See the [Create versatile page templates](https://docs.kentico.com/guides/development/page-builder/create-versatile-templates-part-1.md) guide for a detailed step-by-step walkthrough showing how to create a complex page template, including handling of template properties and page fields.

## Create 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"
using Kentico.PageBuilder.Web.Mvc.PageTemplates;

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.

We recommend storing page template property models in the _\~/PageTemplates/_ folder.

## Define the configuration dialog

The configuration dialog provides a simple way for content editors to set values for page template properties via the Xperience administration. In the properties model class, you need to define [editing components](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components/editing-components.md) for page template properties which you want to make editable in the configuration dialog. You can use the system's [default UI form components](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components/reference-admin-ui-form-components.md) or develop [custom UI form components](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-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 using the desired form component attributes:

   ```csharp title="Example - Setting an editing component"
   using Kentico.Xperience.Admin.Base.FormAnnotations;

   // ...

   [CheckBoxComponent(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/documentation/business-users/website-content/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.

> **Warning:** **Custom editing components with links to content items and pages**
>
> If you decorate any page template property with a [custom form component](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components.md) or use an [inline editor](https://docs.kentico.com/documentation/developers-and-admins/development/builders/page-builder/widgets-for-page-builder/inline-editors-for-widget-properties.md) that allows users to add links to content items and pages (other than the default [combined content selector](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components/reference-admin-ui-form-components.md#combined-content-selector), [page selector](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components/reference-admin-ui-form-components.md#page-selector) and [rich text editor](https://docs.kentico.com/documentation/business-users/rich-text-editor.md)), you need to create a [custom reference extractor](https://docs.kentico.com/documentation/developers-and-admins/customization/extend-the-administration-interface/ui-form-components/ui-form-component-reference-extractors.md) in order to enable [usage tracking](https://docs.kentico.com/documentation/business-users/content-hub/content-items.md#track-usage-of-content-items) in the property.

> **Tip:** **Advanced options**
>
> - You can add dynamic visibility conditions that restrict how and when properties are displayed in the template configuration dialog.
> - You can also assign validation rules to help users provide relevant information.
>
> See [Builder component properties visibility and validation](https://docs.kentico.com/documentation/developers-and-admins/development/builders/builder-component-properties-visibility-and-validation.md) for an overview.

## Handle properties in page template code

To access the template's properties, the template's view must use the generic `TemplateViewModel<TPropertiesType>` 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.

```cshtml
@model TemplateViewModel<LandingPageProperties>

@* Accesses the template's properties (LandingPageProperties in this example) *@
@Model.Properties.ShowTitle
```

### Access 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/documentation/developers-and-admins/development/builders/page-builder/page-templates-for-page-builder.md#handle-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/documentation/developers-and-admins/development/reference-tag-helpers.md) equivalent) within the given `form` tag in your template's view.

```cshtml title="Example"
using Kentico.Content.Web.Mvc

...

<form asp-controller="PageTemplatePostController" asp-action="HandlePost" method="post">
    ...

    @Html.Kentico().ComponentPropertiesData()

    <input type="submit" value="Submit" />
</form>
```

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 `IPageBuilderTemplatePropertiesRetriever` service and its `Retrieve<TPropertiesType>` method. Specify the template's properties class as the method's generic parameter:

```csharp title="Controller class handling the request"
using Kentico.PageBuilder.Web.Mvc.PageTemplates;

using Microsoft.AspNetCore.Mvc;

public class PageTemplatePostController(
    IPageBuilderTemplatePropertiesRetriever pageTemplatePropertiesRetriever) : Controller
{
    [HttpPost]
    public async Task<IActionResult> HandlePost()
    {
        // Gets the properties of the template as a strongly typed object 
        LandingPageProperties properties = pageTemplatePropertiesRetriever.Retrieve<LandingPageProperties>();

        // Use the properties to perform some action
        // ...
    }
}
```