Create a custom ASP.NET Core widget

ASP.NET Core

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:

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:
   C#

   using System;
   using Microsoft.AspNetCore.Mvc;
   using Renderer.Entities.HelloWorld;
   using Progress.Sitefinity.AspNetCore.ViewComponents;
   
   namespace Renderer.ViewComponents
   {
       [SitefinityWidget]
       public class HelloWorldViewComponent : ViewComponent
       {
           // Invokes the view.
           public IViewComponentResult Invoke(IViewComponentContext<HelloWorldEntity> context)
           {
               if (context == null)
               {
                   throw new ArgumentNullException(nameof(context));
               }
   
               return this.View(context.Entity);
           }
       }
   }
   

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:

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:
   C#

   namespace Renderer.Entities.HelloWorld
   {
       public class HelloWorldEntity
       {
           // Gets or sets a value indicating whether a boolean property is true or false.
           public string Message { get; set; }
       }
   }
   

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:
   HTML+Razor

   @using Renderer.Entities.HelloWorld;
   
   @model HelloWorldEntity
   
   <h1>@Model.Message</h1>
   

RESULT: After you build the project, the widget will be displayed inside the widget selector when editing a page.