Example - Widget development

✖
Copy to clipboard

The following scenario will guide you through the process of developing a simple Page Builder widget step-by-step with full code samples. For more detailed information about the underlying development principles, see our general pages about developing widgets, widget properties and inline editors.

Prerequisite

To be able to use the widget in 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.

Widget

Create a widget with one modifiable integer property.

Property model

Create a property model NumberWidgetProperties.cs in the ~/Component/Widgets/NumberWidget folder:

C#

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

namespace LearningKitCore.Components.PageBuilder.Widgets.NumberWidget
{
    public class NumberWidgetProperties : IWidgetProperties
    {
        // Defines a property and sets its default value
        // Assigns the default Xperience number input component, which allows users to enter
        // a numeric value for the property in the widget's configuration dialog
        [NumberInputComponent(Order = 0, Label = "Number")]
        public int Number { get; set; } = 22;
    }
}

Partial view

Create a partial view _NumberWidget.cshtml in the ~/Components/Widgets/NumberWidget folder:

cshtml

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

@using Kentico.PageBuilder.Web.Mvc

@using LearningKitCore.Components.PageBuilder.InlineEditors.NumberEditor
@using LearningKitCore.Components.PageBuilder.Widgets.NumberWidget

@inject IPageBuilderDataContextRetriever pageBuilderContext

@model ComponentViewModel<NumberWidgetProperties>

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

@* Shows an inline editor when rendered in the edit mode of the Pages application in Xperience *@
@if (pageBuilderContext.Retrieve().GetMode() == PageBuilderMode.Edit)
{
    var inlineEditorModel = new NumberEditorModel
    {
        @* Use the nameof() operator to get the name of the edited property from the widget property model *@
        PropertyName = nameof(NumberWidgetProperties.Number),
        Number = @Model.Properties.Number
    };

    <partial name="~/Components/InlineEditors/NumberEditor/_NumberEditor.cshtml" model="inlineEditorModel" />
}

Widget registration

Register the widget into the system using the RegisterWidget assembly attribute:

C#

[assembly: RegisterWidget("LearningKit.Widgets.NumberWidget",
                         "Number selector",
                         typeof(NumberWidgetProperties),
                         customViewName: "~/Components/Widgets/NumberWidget/_NumberWidget.cshtml")]

Inline editor

Implement an inline editor able to modify the Number integer property.

Model

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

C#

namespace LearningKitCore.Components.PageBuilder.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 ~/Components/InlineEditors/NumberEditor folder:

cshtml

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

@model LearningKitCore.Components.PageBuilder.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 ~/wwwroot/PageBuilder/Admin/InlineEditors/NumberEditor folder (this example assumes the default configuration of the system’s bundling support, see Bundle static assets of builder components):

JS

(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 ~/wwwroot/PageBuilder/Admin/InlineEditors/NumberEditor ensures that the script is automatically linked in the administration interface on pages containing editable areas (within a bundle of inline editor scripts).

Dancing Goat sample site

If you implement this example on the Dancing Goat sample site, you need to manually trigger the bundling process to include component scripts in the administration interface. You need to do the following:

  1. Run the pageBuilder Grunt task available in the sample site to manually trigger the bundling process.
  2. Clear cached web content in your browser.

Result

The number editor widget in the Page Builder UI