Topics

All topics

Create a custom ASP.NET Core widget

Overview

The following article describes the process of creating a simple ASP.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 ASP.NET Core widgets:

Create the ViewComponent
  1. Open the ASP.NET Core Renderer in Visual Studio.
  2. Open the context menu of the Renderer project and click Add » New Folder.
  3. Name the folder ViewComponents
  4. Inside the folder, add a class and name it HelloWorldViewComponent.cs
  5. 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.
Order The order of the widget in the section.

Create the Entity
  1. Open the context menu of the Renderer project and click Add » New Folder.
  2. Name the folder Entities
  3. Inside the folder, add a class and name it HelloWorldEntity.cs
    This class contains your business logic and properties. 
  4. 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
  1. Open the context menu of the Renderer project and create the following folders: Views/Shared/Components/HelloWorld
  2. Inside the folder HelloWorld, add a code file and name it Default.cshtml
  3. 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.

Increase your Sitefinity skills by signing up for our free trainings. Get Sitefinity-certified at Progress Education Community to boost your credentials.

Get started with Integration Hub | Sitefinity Cloud | Sitefinity SaaS

This free lesson teaches administrators, marketers, and other business professionals how to use the Integration hub service to create automated workflows between Sitefinity and other business systems.

Web Security for Sitefinity Administrators

This free lesson teaches administrators the basics about protecting yor Sitefinity instance and its sites from external threats. Configure HTTPS, SSL, allow lists for trusted sites, and cookie security, among others.

Foundations of Sitefinity ASP.NET Core Development

The free on-demand video course teaches developers how to use Sitefinity .NET Core and leverage its decoupled architecture and new way of coding against the platform.

Was this article helpful?

Next article

Sample: Hello World widget