Example - Developing a widget in MVC

The following scenario will guide you through the process of developing a simple widget step-by-step with full code samples. To read a more detailed description of each step, visit our general pages about developing MVC widgets and their properties.

Prerequisite

To be able to use the widget in the page builder, you need to enable the page builder feature and set up an editable area.

When finished, the widget displays a simple message with a number of your choice. The number is set via a widget property and can be modified through an inline property editor or the properties dialog. The widget can be added to an editable area and displayed on the live site.

Note: The following example is based on the LearningKit project. To use the code samples in your project, you need to modify the namespaces, identifiers and other occurrences where LearningKit is mentioned to match your project's name.

Widget

Create a sample widget with one modifiable integer property.

Models

Create a properties model NumberWidgetProperties.cs in the ~/Models/Widgets/NumberWidget folder:

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

namespace LearningKit.Models.Widgets.NumberWidget
{
    public class NumberWidgetProperties : IWidgetProperties
    {
        // Defines a property and sets its default value
        // Assigns the default Kentico text input component, which allows users to enter 
        // a numeric value for the property in the widget's configuration dialog
        [EditingComponent(IntInputComponent.IDENTIFIER, Order = 0, Label = "Number")]
        public int Number { get; set; } = 22;
    }
}
Create a view model NumberWidgetViewModel.cs in the ~/Models/Widgets/NumberWidget folder:
namespace LearningKit.Models.Widgets.NumberWidget
{
    public class NumberWidgetViewModel
    {
        public int Number { get; set; }
    }
}

Controller

Create a controller NumberWidgetController.cs in the ~/Controllers/Widgets folder:

using System.Web.Mvc;

using Kentico.PageBuilder.Web.Mvc;

using LearningKit.Controllers.Widgets;
using LearningKit.Models.Widgets.NumberWidget;

// Assembly attribute to register the widget for the connected Kentico instance
[assembly: RegisterWidget("LearningKit.Widgets.NumberWidget", typeof(NumberWidgetController), "Selected number", IconClass = "icon-octothorpe")]
namespace LearningKit.Controllers.Widgets
{
    /// <summary>
    /// A sample widget displaying a message customizable by a widget property.
    /// </summary>
    public class NumberWidgetController : WidgetController<NumberWidgetProperties>
    {
        // Default GET action used to retrieve the widget markup
        public ActionResult Index()
        {
            // Retrieves the properties as a strongly typed object
            NumberWidgetProperties properties = GetProperties();

            // Creates a new model and sets its value
            var model = new NumberWidgetViewModel
            {
                Number = properties.Number
            };

            return PartialView("Widgets/_NumberWidget", model);
        }
    }
}

Partial view

Create a partial view _NumberWidget.cshtml in the ~/Views/Shared/Widgets folder:

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

@using LearningKit.Models.InlineEditors.NumberEditor
@using LearningKit.Models.Widgets.NumberWidget

@model NumberWidgetViewModel

<h3 style="background-color: #dddddd;">The number you chose for today is @Model.Number.</h3>

@* Shows an inline editor when rendered in the edit mode of the Pages application in Kentico *@
@if (Context.Kentico().PageBuilder().EditMode)
{
    Html.RenderPartial("InlineEditors/_NumberEditor", new NumberEditorModel
    {
        @* Use the nameof() operator to get the name of the widget property from the widget properties model *@
        PropertyName = nameof(NumberWidgetProperties.Number),
        Number = Model.Number
    });
}

Inline editor

Implement a simple inline editor able to modify the Number integer property.

Model

Create an editor model NumberEditorModel.cs in the ~/Models/InlineEditors/NumberEditor folder:

namespace LearningKit.Models.InlineEditors.NumberEditor
{
    public class NumberEditorModel
    {
        public string PropertyName { get; set; }

        public int Number { get; set; }
    }
}

Partial view

Create a partial view _NumberEditor.cshtml in the ~/Views/Shared/InlineEditors folder:

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

@model LearningKit.Models.InlineEditors.NumberEditor.NumberEditorModel

@using (Html.Kentico().BeginInlineEditor("number-editor", Model.PropertyName))
{
    <div style="position: absolute; top: 0px; right: 0px;">
        <button id="plus-btn" type="button">+</button>
        <button id="minus-btn" type="button">-</button>
    </div>
}

JavaScript

Create a JavaScript file number-editor.js in the ~/Content/InlineEditors/NumberEditor folder:

(function () {
    // Registers the 'number-editor' inline property editor within the page builder scripts
    window.kentico.pageBuilder.registerInlineEditor("number-editor", {
        init: function (options) {
            var editor = options.editor;
            
            // Click action for the 'Plus' button
            editor.querySelector("#plus-btn").addEventListener("click", function () {
                // Creates a custom event that notifies the widget about a change in the value of a property
                var event = new CustomEvent("updateProperty", {
                    detail: {
                        value: options.propertyValue + 1,
                        name: options.propertyName
                    }
                });
                editor.dispatchEvent(event);
            });

            // Click action for the 'Minus' button
            editor.querySelector("#minus-btn").addEventListener("click", function () {
                var event = new CustomEvent("updateProperty", {
                    detail: {
                        value: options.propertyValue - 1,
                        name: options.propertyName
                    }
                });
                editor.dispatchEvent(event);
            });
        }
    });
})();

The location of the script file under ~/Content/InlineEditors ensures that the script is automatically linked in the Kentico administration interface on pages containing editable areas (within a bundle of inline editor scripts).


Was this page helpful?