Defining widget properties in MVC

When developing widgets for MVC sites, you can define properties that allow content editors to adjust the widget content or behavior directly in the Kentico 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:
   • Define the configuration dialog
   • Implement inline editors

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 in MVC .

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

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

     Copy

     
     
     
       [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 Kentico 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.

Handling properties in widget code

In order for properties to have an effect on a widget’s appearance or functionality, you need to retrieve the property values and adjust the widget’s output code or logic correspondingly. The required steps depend on the development approach used to create the widget (see Developing widgets in MVC 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 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 widget.

// Gets the value of a widget property (e.g. within the widget controller's Index action)
CustomWidgetProperties properties = GetProperties();
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 models separate.