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.

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


Defining widget properties

When developing page builder widgets, you can define properties that allow content editors to adjust the widget content or behavior directly in the administration interface. Users interact with widget properties through the widget configuration dialog or inline editors, which you need to implement.

Use the following process to develop properties for a widget:

  1. Create a model class that defines the widget properties.
  2. Allow content editors to modify the widget properties:

    Configuration dialog and inline editors

    You can combine the configuration dialog and inline editors in a single widget.

  3. Handle the properties in the widget's code.

To see a scenario with full code samples which will guide you through the process of developing a simple widget with a property, visit Example - Developing a widget.

MVC Areas

Widgets are designed as global components. Adding related files, such as property model classes, into MVC Areas is not supported and may lead to unexpected behavior.

Creating property models

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

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

public class CustomWidgetProperties : IWidgetProperties
    // Defines a property and sets its default value
    public int Number { get; set; } = 22;

You can use the Newtonsoft.Json.JsonIgnore attribute to exclude dynamically computed widget properties from database serialization.

We recommend storing widget property models in the ~/Models/Widgets/<widget name> folder.

Defining the configuration dialog

The configuration dialog is a simple way to allow content editors to set values for widget properties. In the property model class, you need to define editing form components for widget 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 widget'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.

    Example - Setting an editing component
    [EditingComponent(TextInputComponent.IDENTIFIER, Order = 0, Label = "Text")]
    public string Text { get; set; }

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

Advanced property options

  • You can add dynamic visibility conditions that restrict how and when properties are displayed in the widget configuration dialog.
  • If you need to create advanced property editors, you can implement modal dialogs. This allows users to set the widget property's value in a custom dialog (a new window separate from the configuration dialog).

Handling properties in widget code

For properties to have an effect on a widget's appearance or functionality, you need to retrieve their values and reflect them in the widget's output code or logic. The required steps depend on the development approach used to create the widget (see Developing widgets for more information).

Basic widgets

For basic widgets without a custom controller class, handle the property values in the widget'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 widget 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

@model ComponentViewModel<CustomWidgetProperties>

<p>The value of the widget's 'Number' property is: @Model.Properties.Number</p>

Widgets with a custom controller

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

public class CustomWidgetController : WidgetController<CustomWidgetProperties>

Retrieve the properties as a strongly typed object via the IComponentPropertiesRetriever service (Kentico.PageBuilder.Web.Mvc namespace) and its Retrieve<TWidgetProperties> 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 widget.

// Contains an instance of the IComponentPropertiesRetriever service (e.g., obtained via dependency injection).
private readonly IComponentPropertiesRetriever componentPropertiesRetriever;

// Gets the value of a widget property (e.g. within the widget controller's Index action)
CustomWidgetProperties properties = componentPropertiesRetriever.Retrieve<CustomWidgetProperties>();
int propertyValue = properties.Number;

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

Do not directly pass the property model to your widget views. Passing data to views is the responsibility of the widget's view model, and we strongly recommend keeping the logic separate.

Accessing widget properties in POST actions

Widget properties cannot be automatically retrieved during POST requests. Common POST requests do not contain sufficient information to identify the page and widget instance from which they originate.

To retrieve widget properties in POST actions, you first need to include the properties into the data submitted by the corresponding HTML form in the widget's output. Call the Html.Kentico().ComponentPropertiesData extension method within the given form tag in your widget view.

using System.Web.Mvc.Ajax
using Kentico.Web.Mvc
using Kentico.PageBuilder.Web.Mvc


@using (Ajax.BeginForm("PostAction", "CustomWidget", null, new AjaxOptions
    HttpMethod = "POST",
    UpdateTargetId = "widgetForm"
}, new { id = "widgetForm" }))
    <input type="submit" value="Submit" />

The method renders a hidden field that persists the widget's properties and makes them available via the properties retriever in the targeted controller action.

Was this page helpful?