Kentico Xperience 13 documentation and ASP.NET Core

Most documentation about running Xperience applications under ASP.NET Core can be found in a dedicated section: Developing Xperience applications using ASP.NET Core. The rest of the documentation still applies, but some code samples and scenarios might need slight modifications for Core projects.

Certain pages allow you to switch between Core and MVC 5 content using a selector located under the page heading.

All major differences between the MVC 5 and Core platforms are summarized in Migrating to ASP.NET Core.

×

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.

Example
public class TitledSectionProperties : IFormSectionProperties
{
    // Defines a title property and sets its default value 
	public string Title { get; set; } = "General";
}

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.

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

Advanced property options

You can add dynamic visibility conditions that restrict how and when properties are displayed in the section configuration dialog.

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

For sections without a custom controller class, handle the property values in the section's partial view.

The view must use the generic FormSectionViewModel<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.

Example
@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>

Sections with a custom controller

To work with properties in form section controllers, extend the controller's Index action by declaring the following parameter:

  • Use the section's property model class as the parameter type.
  • The parameter's name must be: sectionProperties

The system injects the parameter when rendering the form, with property values loaded from the current configuration of the displayed section.

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

Example
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);
    }
}

Section properties in other controller actions

If you need to access the section's properties in an action other than Index, you need to manually propagate the values. For example, if your section contains a POST action, you need to send the required property data within the parameters posted from the section's view.

For basic sections implemented only as a partial view (without a view component) and a properties class, handle the property values directly in the section's view.

The view must use the generic FormSectionViewModel<TPropertyModel> class as its model, with the appropriate property model class as the generic type parameter. The system 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.

Example
@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>

Sections based on a view component

To work with properties in your form section view components, the component's Invoke or InvokeAsync method signature must declare the FormSectionViewModel<TPropertiesType> parameter, with the appropriate property model class as the generic type.

The section's properties are accessible via the Properties member of the FormSectionViewModel parameter, which returns an object of the specified property model class. The object's property values are loaded from the current configuration of the processed section.

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

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

Example
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")]

Example - Section with a custom controller
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")]
Example - Section with a custom view component
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")]


Was this page helpful?