Create a List widget
The following tutorial demonstrates how to create a simple List widget based on the MVC framework. The List widget displays a list of items on the frontend and provides functionality for configurations via a customized designer. Using this tutorial, you learn how to create an MVC widget in a separate assembly that uses a custom designer.
Install the List widget
- Clone the MVC samples repository.
- Build the
- Reference the
ListWidget.dll from your Sitefinity CMS web application.
Create the List widget
You can have MVC widgets that are stored in separate assemblies. The following sample creates the List widget in a separate assembly.
Perform the following:
- Create a new class library and name it ListWidget.
Telerik.Sitefinity.Feather.Core NuGet package using the following command:
- Modify the
AssemblyInfo.cs of the
ListWidget by adding:
and [assembly: ControllerContainer]
GITHUB EXAMPLE: For more information, see AssemblyInfo.cs in the Sitefinity CMS GitHub repository.
- Create the following folders:
- In the context menu of
ListWidget code library, add a new
enum, name it ListMode, and add its declaration.
GITHUB EXAMPLE: For more information, see ListMode.csin the Sitefinity CMS GitHub repository.
Create the controller
Perform the following:
- In folder
MVC/Controllers, create a new class that derives from the
System.Web.Mvc.Controller class and name it ListController.cs
- Add the properties to the
- Create an
Index action that passes the title of the list, the type of the list, and the list items to the
Index view of the List widget.
To pass the required information to the view, you can use the
ViewBag property of the controller class.
NOTE: To resolve the
- Add the
ControllerToolboxItem attribute to the
This way Sitefinity CMS automatically adds the List widget in the toolbox.
GITHUB EXAMPLE: For more information, see ListController.cs in the Sitefinity CMS GitHub repository.
Create the Index view
You need to create an
Index view because this is the only view that is used by the
ListController. To do this, you must create a new Razor view named Index.cshtml and to place it in the
GITHUB EXAMPLE: For more information, see Index.cshtml in the Sitefinity CMS GitHub repository.
NOTE: You can create a Razor view in a class library project by selecting HTML Page in the Add New Item dialog, and then renaming the file extension to
.cshtml. In the file properties, set the view as Embedded Resource.
Create a custom view
Sitefinity CMS provides a widget designer created using ASP.NET MVC, AngularJS, and Bootstrap framework. When an MVC widget is registered in the toolbox, Sitefinity CMS will automatically open for you the new MVC designer. This way you can edit the public properties of the widget though the designer without any additional configuration.
In addition to the default property editor view, you can add your custom views inside the widget designer. This way, you can show different editing options or more complex UI.
This tutorial demonstrates how to modify the MVC designer by adding two views to it – the Settings view and the Manage items view. The Settings view provides options for customizing the visual appearance of the items on your page, while the Manage items view provides simple UI for adding and deleting items from the list.
Add a custom view
Customizing the outlook of the MVC designer that is associated with your custom widget does not require any specific configuration. You do it by following a naming convention. To add a custom view to the MVC designer, you must use the following rules:
- The name of the custom view file must start with
- The custom view file must be physically located in folder
Views that is associated with your widget.
For example, in
- You must mark the custom view file as an embedded resource.
This way Sitefinity CMS will automatically recognize the custom designer view and will generate a button for this view in the widget designer. Sitefinity CMS creates an Angular controller for your custom designer view and populates its scope with all the properties of the widget. Inside your custom designer view, you can bind
html elements to the properties of the widget by using the
For example, to bind an input
html element to a property of your widget, you add the
ng-model attribute to the input
html element and set the value of the
ng-model attribute to be equal to
properties.<Your property name>.PropertyValue. This way, you are taking advantage of the two-way binding functionality that AngularJS provides.
To create your custom view, add a
DesignerView.ManageItems.cshtml file in folder
GITHUB EXAMPLE: For more information, see DesignerView.ManageItems.cshtml in the Sitefinity CMS GitHub repository.
Create the Settings view
To create a
Settings view for the List widget designer, perform the following:
- Inside folder
Mvc/Views/List, create a new Razor view and name it DesignerView.Settings.cshtml.
- Set the newly created file as Embedded Resource.
- Add the ability to specify the title of the List widget via the Settings view.
NOTE: You can also easily modify properties of custom types.
- Add UI elements through which you can control the value of the
GITHUB EXAMPLE: For more information, see DesignerView.Settings.cshtml in the Sitefinity CMS GitHub repository.
Create the ManageItems controller
To meet specific business requirements, you may need to implement a complex UI logic in the widget designer. Sitefinity CMS provides a way for building custom views that contain heavy client-side logic.
This tutorial creates a custom view that will contain a more complex client-side logic for manipulating the value of the
ListItems property of the List widget.
Perform the following:
- In folder
- In the created file, define a custom Angular controller.
By using Angular controllers you have a single place where you can define the client-side business logic that is associated with your custom designer view.
NOTE: If you do not provide a custom Angular controller, the default one will be used.
- Name the controller by concatenating the name of the designer view associated with it and the
In this example, name the controller ManageItemsCtrl.
- Register the
ManageItemsCtrl controller in the designer module.
- Specify that it depends on the
$scope and the
$scope is an object that refers to the application model and is part of the Angular API. The
propertyService is a custom Angular service created in Sitefinity CMS that provides functionality for working with the properties of the widget.
- In the custom
ManageItemsCtrl controller, retrieve the values of the widget properties and populate them into the scope.
GITHUB EXAMPLE: For more information, see designerview-manageitems.js in the Sitefinity CMS GitHub repository.
In this code, you update the
$scope.properties.ListItems depending on the action that the user takes. This way, when the user clicks Save, Sitefinity CMS automatically saves the updated values of the widget properties. If the user clicks Cancel, Sitefinity CMS discards the changes applied on
Change the default view of the designer
In this tutorial, you specify the Manage Items view as the view that is displayed when you open the designer of the List widget.
To do this, perform the following:
- In folder
Mvc/Views/List, create a DesignerView.ManageItems.json file and set it as Embedded Resource.
- Specify the default view for the designer.
GITHUB EXAMPLE: For more information, see DesignerView.ManageItems.json in the Sitefinity CMS GitHub repository.
- Build the project
- Test the result by dragging the List widget on a page.