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.

1. Clone the MVC samples repository.
2. Build the ListWidget project.
3. Reference the ListWidget.dll from your Sitefinity CMS web application.

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:

1. Create a new class library and name it ListWidget.
2. Install Telerik.Sitefinity.Feather.Core NuGet package using the following command:
   Install-Package Telerik.Sitefinity.Feather.Core
3. Modify the AssemblyInfo.cs of the ListWidget by adding:
   using Telerik.Sitefinity.Frontend.Mvc.Infrastructure.Controllers.Attributes;
   and [assembly: ControllerContainer]

   GITHUB EXAMPLE: For more information, see AssemblyInfo.cs in the Sitefinity CMS GitHub repository.

4. Create the following folders:
   • MVC
   • MVC\Views
   • MVC\Views\List
   • MVC\Controllers
5. 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.

Perform the following:

1. In folder MVC/Controllers, create a new class that derives from the System.Web.Mvc.Controller class and name it ListController.cs.
2. Add the properties to the ListController class.
3. 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 JavaScriptSerializer class, you must add a reference to System.Web.Extensions assembly.

4. Add the ControllerToolboxItem attribute to the ListController class.
   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.

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 MVC/Views/List folder.

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.

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 DesignerView,
  For example, DesignerView.<ViewName>.cshtml
• The custom view file must be physically located in folder Views that is associated with your widget.
  For example, in Mvc/Views/<ControllerName>
• 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 ng-model attribute.
  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 MVC/Views/List.

GITHUB EXAMPLE: For more information, see DesignerView.ManageItems.cshtml in the Sitefinity CMS GitHub repository.

To create a Settings view for the List widget designer, perform the following:

1. Inside folder Mvc/Views/List, create a new Razor view and name it DesignerView.Settings.cshtml.
2. Set the newly created file as Embedded Resource.
3. 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.

4. Add UI elements through which you can control the value of the ListType property.

GITHUB EXAMPLE: For more information, see DesignerView.Settings.cshtml in the Sitefinity CMS GitHub repository.

When you open the designer of the List widget you can see a new Settings button at the bottom-right corner. By clicking the button, you load a designer for editing the widget properties that is created without using JavaScript.

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:

1. In folder Mvc/Scripts/List, create a new JavaScript file and name it designerview-manageitems.js
2. 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.

3. Name the controller by concatenating the name of the designer view associated with it and the Ctrl suffix.
   In this example, name the controller ManageItemsCtrl.
4. Register the ManageItemsCtrl controller in the designer module.
5. Specify that it depends on the $scope and the propertyService.
   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.
6. 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 $scope.properties.

By default, when you open the designer of a widget, Sitefinity CMS automatically displays a default designer view. You can modify this behavior through a JSON config file. By specifying the default view for a designer, the JSON config file provides a way for configuring the behavior of the MVC designer and also serves as a container for registering the client-side dependencies of the designer, such as the required JavaScript files.

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:

1. In folder Mvc/Views/List, create a DesignerView.ManageItems.json file and set it as Embedded Resource.
2. Specify the default view for the designer.

   GITHUB EXAMPLE: For more information, see DesignerView.ManageItems.json in the Sitefinity CMS GitHub repository.

3. Build the project
4. Test the result by dragging the List widget on a page.