Defining section properties

When developing page builder sections, you can define properties that allow content editors to adjust the appearance or behavior of the sections in the Kentico administration interface. Users then interact with the section properties through section configuration dialogs.

Use the following process to develop properties for a section:

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

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

Creating property models

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

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

public class CustomSectionProperties : ISectionProperties
{
    // Defines a property and sets its default value
    public string Color{ get; set; } = "#FFF";
}

We recommend storing section property models in the ~/Models/Sections/<section name> folder.

Defining the configuration dialog

The configuration dialog is a simple way to allow content editors to set values for section properties. In the property model class, you need to define editing form components for section 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 section’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(TextInputComponent.IDENTIFIER, Order = 0, Label = "Color")]
public string Color { get; set; } = "#FFF";

Users can now click the Configure () icon when working with sections in the Kentico administration interface. This opens the section properties dialog, and the configured property values affect the appearance and functionality of the section on the live site.

Handling properties in section code

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

Basic sections

For sections without a custom controller class, handle the property values in the section’s partial 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 section 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.

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

@model ComponentViewModel<CustomSectionProperties>

<div style="background-color: @Model.Properties.Color;">
    @Html.Kentico().WidgetZone()
</div>

Sections with a custom controller

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

public class CustomSectionController : SectionController<CustomSectionProperties>

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 section.

// Gets the value of a section property
CustomSectionProperties sectionProperties = GetProperties();
string propertyValue = sectionProperties.Color;

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

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

Example - Developing a section with a configurable property

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

When finished, the section is displayed with a color background of your choice. The color is set via a section property and can be modified through a section configuration dialog. The color can be specified in any text format that is accepted by the CSS background-color property (e.g. a HEX or RGB value).

Property model

Create a properties model CustomSectionProperties.cs in the ~/Models/Sections/CustomSection folder:

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

namespace LearningKit.Models.Sections.CustomSection
{
    public class CustomSectionProperties : ISectionProperties
    {
        // Defines a property and sets its default value
        // Assigns the default Kentico text input component, which allows users to enter
        // a string value for the property in the section's configuration dialog
        [EditingComponent(TextInputComponent.IDENTIFIER, Order = 0, Label = "Color")]
        public string Color { get; set; } = "#FFF";

    }
}

Partial view

Create a partial view _CustomSection.cshtml in the ~/Views/Shared/Sections folder:

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

@using LearningKit.Models.Sections.CustomSection

@model ComponentViewModel<CustomSectionProperties>

@* Shows a sample section with a background color specified in the section's configuration dialog *@
<div style="background-color: @Model.Properties.Color;">
    @Html.Kentico().WidgetZone()
</div>

Section registration

Register the section into the system using the RegisterSection 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.Sections.CustomSection;

using Kentico.PageBuilder.Web.Mvc;

// Registers the 'Custom section' section (it uses the system's default controller and ComponentViewModel)
[assembly: RegisterSection("LearningKit.Sections.CustomSection",
                          "Custom section",
                          typeof(CustomSectionProperties),
                          customViewName: "Sections/_CustomSection",
                          IconClass = "icon-square")]