Topics

All topics

Development

    Best practices for implementing custom widgets

    This article contains
    NEW TO SITEFINITY?

    Overview

     When you develop custom widgets, you need to solve problems such as how to implement canonical URLs, what are the best development practices, or how to reuse built-in widgets logic. This article demonstrates how to use important interfaces or abstract base classes to solve these problems.

    ContentBaseController

    You use ContentBaseController abstract class to construct all the out-of-the-box SEO properties for the widget in Detail view mode - when displaying a single item. When you implement a descendant of this class, you can call the InitializeMetadataDetailsViewBag method and pass the item that is currently being displayed. Based on the item and the SEO configurations of the site, Sitefinity CMS automatically creates the Open Graph and other SEO properties.

    GITHUB EXAMPLE: For more information about this class, see the sample code in Sitefinity CMS GitHub repository » ContentBaseController.cs.

    ContentModelBase

     The ContentModelBase class holds the auxiliary implementation for various functionality, such as getting content locations, creating generic list view models, creating generic details view models, creating a list view model based on a related data item, part of the implementation of the IHasCacheDependency interface, and more.
    For more information, see ContentModelBase.cs.

    IContentLocatableView

     You implement the IContentLocatableView interface, if you want your custom widget to have a canonical URL and to provide a location for items.
    For more information, see Register content location with your custom widgets and How to implement IContentLocatableView for custom widgets.

    IHasCacheDependency

     You implement IHasCacheDependency interface to provide cache invalidation for the respective content type in your custom widget. If this interface is not implemented, there can be stale content displayed in the following scenario:
    • The user that is logged in is not a backend user or no user is logged in.
      Sitefinity CMS does not use cache when serving content to backend users.
    • The widget is displayed on a page and the user has requested this page, thus, the query made by the widget is cached according to the cache profile.
    • An editor makes a change to an item that the widget is displaying.
    • The user will not see the change until the cache expires, since there is no way for Sitefinity CMS to know that these items are being displayed by this widget.
    For more information, see Implement Cache Dependencies.

    IRouteMapper

     You implement IRouteMapper interface when you need custom logic for resolving the route parameters. When you implement it, the default behavior for MVC routing will be turned off and only your custom routing implementation will be used.

    EXAMPLE: You have custom book widget that displays a list of books on a page. You can implement custom routing logic for filtering by a specific author that will resolve the required author from the route – for example, http://mysite/book-catalog/Index/Author. For more information, see #region IRouteMapper in the sample at the end of the article.

    HandleUnknownAction

     You use the HandleUnknownAction method in a Sitefinity CMS widgets to retain a correct state in certain scenarios. One such scenario is the details mode of a separate widget. When a page is rendered with a widget in a mode different than the default one, Sitefinity CMS checks all the widgets on the page whether they can go into this mode. In this case, the news widget is going into details mode and Sitefinity CMS is trying to push all widgets in this mode. The widgets who have details action will get mapped earlier and Sitefinity CMS will not execute them. However, the widgets that do not have details action must implement the HandleUnknownAction method so that the developer can specify what action should be executed in such a case.
    For more information see HandleUnknownAction in the sample at the end of the article.

    Returning a view

     When you return a view in your Controller class, always name explicitly the view that is going to be called:
    return this.View("ViewName", viewModel); For more information, see the sample below.

    Code sample

    The following sample demonstrates how to use IContentLocatableView, IRouteMapper,  HandleUnknownAction, and how to return a view from your Controller classes:

    using System;
    using System.Collections.Generic;
    using System.ComponentModel;
    using System.Linq;
    using System.Web.Mvc;
    using System.Web.Routing;
    using Telerik.Sitefinity.ContentLocations;
    using Telerik.Sitefinity.DynamicModules.Model;
    using Telerik.Sitefinity.Frontend.Mvc.Helpers;
    using Telerik.Sitefinity.Frontend.Mvc.Infrastructure;
    using Telerik.Sitefinity.Frontend.Mvc.Infrastructure.Controllers;
    using Telerik.Sitefinity.Frontend.Mvc.Infrastructure.Routing;
    using Telerik.Sitefinity.Model;
    using Telerik.Sitefinity.Mvc;
    using Telerik.Sitefinity.Personalization;
    using Telerik.Sitefinity.Services;
    using Telerik.Sitefinity.Taxonomies.Model;
    using Telerik.Sitefinity.Web;
    using SitefinityWebApp.Mvc.Models;
    namespace SitefinityWebApp.Mvc.Controllers
    {
    [ControllerToolboxItem(Name = "CustomPressReleasesWidget_MVC", Title = "Press Releases Widget", SectionName = "CustomWidgets")]
    public class PressReleasesWidgetController :
    ContentBaseController,
    IContentLocatableView,
    IRouteMapper,
    IPersonalizable
    {
    #region Properties
    public string ListTemplateName
    {
    get { return this.listTemplateName; }
    set { this.listTemplateName = value; }
    }
    public string DetailTemplateName
    {
    get { return this.detailTemplateName; }
    set { this.detailTemplateName = value; }
    }
    public bool OpenInSamePage
    {
    get { return this.openInSamePage; }
    set { this.openInSamePage = value; }
    }
    public Guid DetailsPageId { get; set; }
    [TypeConverter(typeof(ExpandableObjectConverter))]
    public IPressReleasesWidgetModel Model
    {
    get
    {
    if (this.model == null)
    this.model = this.InitializeModel();
    return this.model;
    }
    }
    #endregion
    #region Actions
    public ActionResult Index(int? page)
    {
    ITaxon taxonFilter = TaxonUrlEvaluator.GetTaxonFromQuery(this.HttpContext, this.Model.UrlKeyPrefix);
    var fullTemplateName = this.listTemplateNamePrefix + this.ListTemplateName;
    var currentPageUrl = this.GetCurrentPageUrl();
    this.ViewBag.CurrentPageUrl = currentPageUrl;
    this.ViewBag.RedirectPageUrlTemplate = this.GeneratePagingTemplate(currentPageUrl, this.Model.UrlKeyPrefix);
    this.ViewBag.DetailsPageId = this.DetailsPageId;
    this.ViewBag.OpenInSamePage = this.OpenInSamePage;
    this.SetRedirectUrlQueryString(taxonFilter);
    this.UpdatePageFromQuery(ref page, this.Model.UrlKeyPrefix);
    var viewModel = this.Model.CreateListViewModel(taxonFilter, this.ExtractValidPage(page));
    this.AddCacheDependencies(this.Model.GetKeysOfDependentObjects(viewModel));
    if (this.ShouldReturnDetails(this.Model.ContentViewDisplayMode, viewModel))
    return this.Details((DynamicContent)viewModel.Items.First().DataItem);
    return this.View(fullTemplateName, viewModel);
    }
    public ActionResult ListByTaxon(ITaxon taxonFilter, int? page)
    {
    var fullTemplateName = this.listTemplateNamePrefix + this.ListTemplateName;
    this.ViewBag.CurrentPageUrl = this.GetCurrentPageUrl();
    this.ViewBag.RedirectPageUrlTemplate = this.ViewBag.CurrentPageUrl + "/" + taxonFilter.UrlName + "/{0}";
    this.ViewBag.DetailsPageId = this.DetailsPageId;
    this.ViewBag.OpenInSamePage = this.OpenInSamePage;
    var viewModel = this.Model.CreateListViewModel(taxonFilter, this.ExtractValidPage(page));
    if (SystemManager.CurrentHttpContext != null)
    this.AddCacheDependencies(this.Model.GetKeysOfDependentObjects(viewModel));
    return this.View(fullTemplateName, viewModel);
    }
    public ActionResult Details(DynamicContent item)
    {
    this.InitializeMetadataDetailsViewBag(item);
    var fullTemplateName = this.detailTemplateNamePrefix + this.DetailTemplateName;
    this.ViewBag.Title = item.ApplicationName;
    var viewModel = this.Model.CreateDetailsViewModel(item);
    if (SystemManager.CurrentHttpContext != null)
    this.AddCacheDependencies(this.Model.GetKeysOfDependentObjects(viewModel));
    var page = this.HttpContext.CurrentHandler.GetPageHandler();
    this.AddCanonicalUrlTagIfEnabled(page, item);
    return this.View(fullTemplateName, viewModel);
    }
    protected override void HandleUnknownAction(string actionName)
    {
    this.ActionInvoker.InvokeAction(this.ControllerContext, "Index");
    }
    #endregion
    #region IRouteMapper
    public bool TryMapRouteParameters(string[] urlParams, RequestContext requestContext)
    {
    if (urlParams == null)
    throw new ArgumentNullException(nameof(urlParams));
    if (requestContext == null)
    throw new ArgumentNullException(nameof(requestContext));
    if (urlParams.Length == 0)
    return false;
    var url = RouteHelper.GetUrlParameterString(urlParams);
    var providerName = this.Model.ProviderName;
    var contentItemResolver = new ContentDataItemResolver();
    var item = contentItemResolver.GetItemByUrl(url, this.Model.ContentType, providerName, out string redirectUrl);
    if (item != null)
    {
    SystemManager.CurrentHttpContext.Items["detailItem"] = item;
    this.AddContentItemToRouteData(requestContext, redirectUrl, item);
    return true;
    }
    return false;
    }
    protected void AddContentItemToRouteData(RequestContext requestContext, string redirectUrl, IDataItem item, bool setUrlParametersResolved = true)
    {
    requestContext.RouteData.Values["action"] = "details";
    var actionMethod = new ReflectedControllerDescriptor(this.GetType()).FindAction(this.ControllerContext, "Details");
    var parameters = actionMethod.GetParameters();
    if (parameters.Length > 0 && parameters[0].ParameterType.IsAssignableFrom(this.Model.ContentType))
    {
    requestContext.RouteData.Values[parameters[0].ParameterName] = item;
    }
    if (!redirectUrl.IsNullOrEmpty())
    {
    requestContext.RouteData.Values[Telerik.Sitefinity.Mvc.ControllerActionInvoker.ShouldProcessRequestKey] = redirectUrl;
    }
    }
    #endregion
    #region IContentLocatableView
    public bool? DisableCanonicalUrlMetaTag { get; set; }
    [NonAction]
    public IEnumerable<IContentLocationInfo> GetLocations()
    {
    return this.Model.GetLocations();
    }
    #endregion
    #region Private Methods
    private IPressReleasesWidgetModel InitializeModel()
    {
    return ControllerModelFactory.GetModel<IPressReleasesWidgetModel>(this.GetType());
    }
    private void SetRedirectUrlQueryString(ITaxon taxon)
    {
    if (taxon == null || this.HttpContext == null)
    {
    return;
    }
    var taxonQueryStringParams = HyperLinkHelpers.BuildTaxonQueryStringParams(taxon, this.Model.UrlKeyPrefix);
    this.ViewBag.RedirectPageUrlTemplate = this.ViewBag.RedirectPageUrlTemplate + taxonQueryStringParams;
    }
    #endregion
    #region Fields
    private IPressReleasesWidgetModel model;
    private string listTemplateName = "PressReleases";
    private string listTemplateNamePrefix = "List.";
    private string detailTemplateName = "DetailPage";
    private string detailTemplateNamePrefix = "Detail.";
    private bool openInSamePage = true;
    #endregion
    }
    }
    view raw PressReleassWidgetController.cs hosted with ❤ by GitHub

    Want to learn more?

    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?