Create a custom .NET Core widget
Overview
The following article describes the process of creating a simple .NET Core widget. This sample demonstrates how to create a ViewComponent that will be used to display a configurable message.
GITHUB EXAMPLE: You can find the whole sample in Sitefinity GitHub repository » Hello world widget.
You can also use the following video as a guideline to creating custom .NET Core widgets:
Create the ViewComponent
- Open the ASP.NET Core Renderer in Visual Studio.
- Open the context menu of the
Renderer project and click Add » New Folder.
- Name the folder ViewComponents
- Inside the folder, add a class and name it HelloWorldViewComponent.cs
- In the class paste the following code:
View component explained:
- You use the
[SitefinityWidget] attribute to load the widget automatically in the Sitefinity InsertWidget dialogs.
- You inherit the
ViewComponent so that the Renderer detects and renders your functionality inside your pages
- The
InvokeAsync method is required and it is called automatically every time the page is requested.
- The
InvokeAsync method needs argument of type IViewComponentContext<T>. When the page is rendered, the argument is directly populated in this method. The generic parameter refers to the model of the widget. Beside your business logic, the model contains all properties of the widget that are persisted in Sitefinity CMS.
Define widget properties
After you implement new widgets, you register them with the renderer so they can appear in the widget toolbox dialog. To do this, you decorate the widget view component class with the [SitefinityWidget] attribute. Using this attribute, you define the following optional properties of the widget:
| Property |
Description |
Title |
The display name of the widget, shown in the widget toolbox.
For example, Content block.
|
Category |
This is one of the categories in which you can place the widget.
You can find all available categories in the class Progress.Sitefinity.AspNetCore.ViewComponents.WidgetCategory
You cannot add custom categories. Instead, you can add your custom widgets in custom sections in the existing categories.
|
Section |
The section of the widget in the parent category. You can define a custom value or use one of the predefined values in the class Progress.Sitefinity.AspNetCore.ViewComponents.WidgetSection.
You cannot change the ordering of the widget sections. They always show the built-in widgets first and then the custom ones.
You can add widgets to the existing sections as well.
|
Warning |
A warning message, used to display contextual information for the current state of the widget.
The warning is shown when editing the page through the page editor.
If you want to show the warning dynamically, you can use the example here.
|
EmptyIcon |
The icon shown when the widget does not have any HTML output.
You can see the available icons in Font Awesome.
|
EmptyIconText |
The text shown when the widget does not have any HTML output. |
EmptyIconAction |
The action to perform when the empty text and icon are clicked. Possible values are listed in the class Progress.Sitefinity.AspNetCore.ViewComponents.EmptyLinkAction. |
SeparateWidgetPerTemplate |
When you set this property to true, each widget view appears as a separate widget entry in the toolbox.
The default is false.
|
Order |
The order of the widget in the section. |
Create the Entity
- Open the context menu of the
Renderer project and click Add » New Folder.
- Name the folder Entities
- Inside the folder, add a class and name it HelloWorldEntity.cs
This class contains your business logic and properties.
- In the class paste the following code:
Like in the ASP.NET MVC widgets, the ASP.NET Core widgets persist your public properties and provide user-friendly interface to edit them though the designer when editing your pages.
ASP.NET core widgets support Autogenerated widget property editors. Therefore, based on the attributes, Sitefinity autogenerates user-friendly editing interface for the widgets.
NOTE: Only the public properties from the model are persisted and not the public properties that you may have in the ViewComponent.cs file. This way, the business logic is better separated from the rendering.
Create the View
- Open the context menu of the
Renderer project and create the following folders: Views/Shared/Components/HelloWorld
- Inside the folder
HelloWorld, add a code file and name it Default.cshtml
- In the file paste the following code:
RESULT: After you build the project, the widget will be displayed inside the widget selector when editing a page.