Develop widgets

In addition to Sitefinity CMS built-in widgets, you can create new widgets from scratch and implement your own logic and customize widgets' built-in functionality. You also have the option of keeping the widgets in separate assemblies and deploy them independently of your project. You can then use your new widgets side by side with the built-in ones. You can also configure localizable resources and enable inline editing for content widgets.

This article provides you with an overview of how to get started with MVC widgets development in Sitefinity CMS. 

Which MVC mode to use

When developing with Sitefinity CMS, you can work in one of the three MVC modes:

• Classic MVC mode
• Hybrid mode
• Pure MVC mode

The mode you use depends on your development process as well as on the functionality you want to implement. For more information about each mode and some key benefits and considerations when working in the different modes, see For developers: MVC modes.

What content does the site display

Use built-in widgets

Each site has specifics in terms of what content visitors see and how they interact with the content. For example, you may need to add a multi-step form for visitors to fill out or display information about events that your company advertises on its website. Thus, Sitefinity CMS out-of-the-box MVC widgets serve your needs best in a such as streamlined scenario. For more information, see:

• Forms
• Events

Sitefinity CMS built-in content types are a fundamental basis to build your site but if they do not fully complement your scenario, you can create new ones, for example, Locations, or Author bio. By using dynamic content, you have full flexibility on what content type to use and how. For example, Sitefinity CMS automatically creates widgets for your new content type, based on the fields that this content requires and uses. Each time you add a new field, Sitefinity CMS prompts you to upgrade the widget as well. Along with the automatically generated widgets for the new content types, you also benefit from the generation of OpenGraph metadata and additional metadata, such as canonical URLs, titles, SEO description, and so on. For more information, see:

• Dynamic modules
• SEO: Automatic generation of metadata for MVC widgets 

Modify built-in widgets

Sometimes you may need to enhance the built-in widgets functionality to have the widget provide additional information about the content displayed. For example, you may need to display the author of each news item on your site. You modify the News widget model to query information about the author's user profile in Sitefinity CMS, such as the user's profile picture. Generally, you also modify the widget view as it is the presentation layer of the widget. This means that the view defines what content (retrieved by the model) is displayed by the widget. For more information, see:

• Create and edit widget templates
• Extend the model of built-in widgets

You basically extend the default functionality of a widget by implementing a custom logic and then map the modified widget in the backend, so that Sitefinity CMS redirects to your modified widget instead of the built-in one. 

Create new custom widgets

You scenario may require a new widget that you create from scratch and implement your own logic and functionality. For example, you want to display on your site a slider with events, services, or current news. To do this, you create a dynamic module that enables the creation of multiple items, say Slides, to be displayed in the home page slider. Such a slide item may hold, for example, fields or properties like a Title or a Name, the slide's URL, and a URL link to another content item in Sitefinity CMS. Such content item can be a blog post or a news item, a picture and a summary, and so on. Once you create a Slides dynamic module and activate it, Sitefinity CMS automatically creates widgets to display this content. However, such widgets do not suit the requirements for a home page slider, so you need to create a new custom widget.

Sitefinity VSIX

With Sitefinity VSIX tool you easily create and scaffold the widget structure in Visual Studio and then add the logic and functionality. For more information about how to install and work with VSIX, see Sitefinity VSIX.

Once the basic structure of the new widget is created, that is, the controller, model, view, and the widget adjacent designer files, you can query the dynamic Slides content items in accordance with the requirements for the widget. 

For information about how to create, register, and configure new widgets, see:

• Create widgets
• Register new widgets in Sitefinity CMS toolbox
• Widget designers

Considerations when creating new widgets

When creating new dynamic modules and working with their content items, based on your scenario, think about the following points:

• Do you need to include the items in the sitemap?
  If items are not included in the sitemap, they are not indexed by search engines and are not listed in the search results. In the example above, Slides need not be included in the sitemap since these items' purpose is to invoke visitors to click on them and do not display content per se. For more information, see Include content in the sitemap.
• Do you need to include the items in the search indexes?
  In case the content items are, say, buttons with plain text, they do not need to be indexed. For more information, see Administration: Create search indexes.
  
• Do the items need Detail view?
  In the example above, a slide may have reference to another content type, such as a news article or a blog post. Therefore, you want visitors to open the Detail view of the relevant content type and not the Detail view of the Slide item itself. For more information, see Implement Master Detail content controllers.
  

RECOMMENDATION: We recommend to carefully examine whether the out-of-the-box widgets fulfill your functionality requirements before you go on and create your own widgets. For a full list, see Built-in widgets. In addition, consider whether modifying the template will do the job for you. For more information, see Create and edit widget templates. 

With Sitefinity CMS, you have the option to develop widgets in both the SitefinityWebApp project or in external assemblies. The underlying development concept is the same but the way you organize and manage your code differs between the two methods.

RECOMMENDATION:We recommend that when developing new custom widgets, you work in external assemblies because maintaining and organizing your code is done in an easier and more straightforward manner. For more information, see Create widgets in external assemblies.

Keep in mind that when developing widgets in external assemblies, when creating the view(s), you need to set the Build Action to Embedded Resource. Therefore, for each and every change you make, you need to build the project. On the other hand, when developing in SitefinityWebApp project, you only need to rebuild the project when modifying the C# files. 

Interfaces

When developing MVC widgets that display content, including dynamic content types, we recommend that you implement/inherit the following three interfaces:

IPersonalizable

Enables you to personalize widgets. For more information, see Implement personalized widgets.

You can personalize any Sitefinity CMS MVC widget, so that you create different versions of the widget for different audience segments. Once you create a personalized version of a widget, you actually duplicate the widget, so both versions have exactly the same properties.

IHasCacheDepedency

MVC widgets have a built-in mechanism for invalidating the output cache - when the content changes, the cached output is invalidated. When developing your own custom widget, to invalidate the cache, you need to implement the appropriate cache dependencies in order. This way, when you create or modify a content item, the widget cache is invalidated in order to reflect the latest changes in the content.

If you do not implement the IHasCacheDependency interface, your content will not be up to date. For example, you have a custom Press release widget on your page that displays several content items. If you update the content of the original content items, the widget will display stale data.
For more information, see Implement cache dependencies.

IContentLocatableView

• Defines on which page or content is displayed. For more information, see Register content location with your custom widgets.
• Defines canonical URLs, SEO descriptions, OpenGraph metadata, and so on. Based on these settings, the sitemap is generated.
• Enables Sitefinity CMS to know the locations of the content items displayed with you custom widget. If you want your custom widget to have a canonical URL and to provide a location for items, you must implement the IContentLocatableView interface. 

IRouteMapper

You use this interface when you need custom logic for resolving the route parameters. Implementing the interface means that the default behavior for MVC routing will not work but will depend only on the custom implementation. Say you have custom Book widget that displays a list of books on a page that is a  book-catalog. You can implement custom routing logic for filtering by specific author that resolves the desired author from the route, for example, http://example.com/book-catalog/Index/J.K.Rowling.

Helper methods

Using CSS styling, JavaScript logic, and jQuery support is a part of the process of developing your MVC views. This way, your custom functionality is styled and presented according to your requirements. When developing your MVC views, you can add JavaScript, CSS, and Sitefinity CMS built-in jQuery resources. You do this by leveraging the MVC Helper methods. For more information, see Refer to resources inside views.

BeginFormSitefinity

When creating and developing Forms in MVC, we recommend that you use the BeginFormSitefinity helper method in place of the classic MVC helper method BeginForm. The reason is that when working in Hybrid mode, Sitefinity CMS wraps the entire page in a <form> element. When another <form> tag is added on the page, ASP.NET causes issues since you cannot have nested forms in ASP.NET Web Forms. As a result, there are issues with editing and displaying the Sitefinity CMS pages and page templates.

When using the BeginFormSitefinity helper method in hybrid pages, the method outputs a <div> tag, instead of a <form> tag and a script that traverses all input form fields and send the data when the form is submitted.

CRUD operations with the Sitefinity CMS API

When developing MVC widgets, you use the Sitefinity CMS content managers with the Native or Fluent API for executing CRUD operations with the content. Every built-in content type has a dedicated manger API. On the other hand, dynamic modules and content types share just one manager API.

RECOMMENDATION: To avoid performance and implementation issues, we recommend that you always use the Native or Fluent managers API.

RECOMMENDATION: We do not recommend making direct queries to the database because the L2 cache is not invalidated and content editors experience stale content in the backend. For more information, see Administration: L2 cache strategies.

Designer framework

Widget designers in MVC define and configure how widgets are displayed on the page. When working with content widgets, you define whether content items in List mode are displayed paginated or not. In addition, you can select specific items to be displayed. Via widget designers, you also define which widget templates to use in List and Detail mode. You can also add CSS classes to the widget. For more information, see Widget designers.