Defining form section properties

When developing form sections, you can define properties that allow editors to adjust the content or behavior of the sections directly in the form builder interface. Users 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 form editors to modify the properties
3. Handle the properties in the section’s code
4. Specify the property model class in the section’s registration attribute

Creating property models

The properties of a form section must be defined within a model class that implements the IFormSectionProperties interface (available in the Kentico.Forms.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 TitledSectionProperties : IFormSectionProperties
{
    // Defines a title property and sets its default value 
    public string Title { get; set; } = "General";
}

Defining the configuration dialog

The configuration dialog provides a simple way for form editors to set the values of 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 live site project.

2. Define the visual interface of the configuration dialog:

   • Decorate the appropriate properties using the EditingComponent attribute.

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

   Example - Setting an editing component

   Copy

   
   
   
    // Defines a title property whose value is edited via a text input in the section configuration dialog
    [EditingComponent(TextInputComponent.IDENTIFIER, Order = 0, Label = "Title")]
    public string Title { get; set; } = "General";
   
   
    

Users can now click the Configure () icon when working with sections in the form builder interface. This opens the section properties dialog, and the configured property values affect the section’s content and functionality.

Handling properties in section code

In order for properties to have an effect on a section’s content 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 custom form layouts for more information).

Basic sections

@using Kentico.Forms.Web.Mvc
@using Kentico.Web.Mvc

@model FormSectionViewModel<TitledSectionProperties>

@if (!string.IsNullOrEmpty(Model?.Properties?.Title))
{
    <h2>@Model.Properties.Title</h2>
}

<div>
    @Html.Kentico().FormZone()
</div>

public class TitledSectionController : Controller
{
    // Action used to retrieve the section markup
    public ActionResult Index(TitledSectionProperties sectionProperties)
    {
        // Prepares a view model object containing the section's Title property
        var viewModel = new TitledSectionViewModel
        {
            Title = sectionProperties.Title
        };

        return PartialView("FormSections/_TitledSection", viewModel);
    }
}

@using Kentico.Forms.Web.Mvc
@using Kentico.Web.Mvc

@model FormSectionViewModel<TitledSectionProperties>

@if (!string.IsNullOrEmpty(Model?.Properties?.Title))
{
    <h2>@Model.Properties.Title</h2>
}

<div>
    @await Html.Kentico().FormZoneAsync()
</div>

using Microsoft.AspNetCore.Mvc;
using System.Threading.Tasks;

using Kentico.Forms.Web.Mvc;

public class TitledSectionViewComponent : ViewComponent
{  
    public async Task<IViewComponentResult> InvokeAsync(FormSectionViewModel<TitledSectionProperties> sectionProperties)
    {
        // Prepares a view model object containing the section's Title property
        var viewModel = new TitledSectionViewModel
        {
            Title = sectionProperties.Properties.Title
        };

        return View("~/Components/FormSections/TitledSection/_TitledSection.cshtml", viewModel);       
    }
}

Registering sections with properties

When registering form sections with properties, you additionally need to set the PropertiesType property of the RegisterFormSection attribute to the System.Type of the section’s property model class.

using Kentico.Forms.Web.Mvc;

[assembly: RegisterFormSection("MySections.TitledSection",  
                               "Titled section",
                               customViewName: "~/Components/FormSections/TitledSection/_TitledSection.cshtml",
                               PropertiesType = typeof(TitledSectionProperties),
                               Description = "Organizes fields into a section with a configurable title.",
                               IconClass = "icon-square")]

using Kentico.Forms.Web.Mvc;

[assembly: RegisterFormSection("MySections.TitledSection",
                                typeof(TitledSectionController),
                                "Titled section",
                                PropertiesType = typeof(TitledSectionProperties),
                                Description = "Organizes fields into a section with a configurable title.",
                                IconClass = "icon-square")]

using Kentico.Forms.Web.Mvc;

[assembly: RegisterFormSection("MySections.TitledSection",
                                typeof(TitledSectionViewComponent),
                                "Titled section",
                                PropertiesType = typeof(TitledSectionProperties),
                                Description = "Organizes fields into a section with a configurable title.",
                                IconClass = "icon-square")]