Sitefinity MVC Widget Best Practices
sitefinity | 2020-08-20
Introduction
This guide outlines key implementation patterns and best practices for building custom MVC widgets in Sitefinity CMS, based on a tested example using version 11.1.
The sample includes implementations of IContentLocatableView
, IHasCacheDependency
, and HandleUnknownAction
, which together ensure enhanced SEO, cache control, and graceful routing.
Core Implementation Overview
✅ Interfaces Implemented:
IContentLocatableView
IHasCacheDependency
(SubscribeCacheDependency
)HandleUnknownAction
1. ContentBaseController
and ContentModelBase
These foundational classes encapsulate the core logic for generating out-of-the-box SEO properties, supporting both listing and detail pages.
Once integrated, calling the InitializeMetadataDetailsViewBag
method—while passing in the content item being displayed—enables Sitefinity to automatically generate Open Graph (OG) tags and standard SEO metadata based on the site’s configuration.
📚 Explore the sample implementation: Sitefinity GitHub Repository
Verifying IContentLocatableView
To verify that IContentLocatableView
is functioning correctly:
- Remove the custom widget from the page
- Publish the page
- Re-add the custom widget
- Publish again
Then, navigate to the related content type page. You should see the location registered properly.
2. IHasCacheDependency
– Smart Cache Invalidation
Implementing this interface in your widget allows Sitefinity to correctly invalidate the cache when related content changes.
This is especially important for content types like News or Events.
For example, placing an MVC widget that displays News items on a page means:
- If a News item is updated,
- The widget’s cache is automatically invalidated,
- And fresh content is served immediately without calling the controller unnecessarily.
3. HandleUnknownAction
– Graceful Fallback Routing
The HandleUnknownAction
method ensures that unexpected route parameters do not lead to 404 Not Found errors.
Instead, it marks the URL as handled and redirects users to a relevant view.
✅ To test this:
- Install the custom widget on a page (e.g.,
/about
) - Ensure your controller includes:
- An
/index
method - The
HandleUnknownAction
method
- An
- Visit an undefined path like
/about/detail
— the request will be resolved byHandleUnknownAction
.
Putting It All Together
Once the recommendations are implemented:
IContentLocatableView
will register public URLs for the content type upon publishing, ensuring SEO and sitemap alignment.IHasCacheDependency
(viaSubscribeCacheDependency()
) will automatically invalidate cache when new items are created or edited.HandleUnknownAction
will provide graceful fallback routing, improving UX and error handling.
References & Official Docs
- Best Practices for Custom MVC Widgets (Sitefinity KB)
- Register Content Location for Custom Widgets
- Implement Cache Dependencies
- How to Implement
IContentLocatableView
📌 Recommendation
Extend the auto-generated views of your content type module (e.g., ImageGallery
) to inherit best practices by default.
This aligns your widget with Sitefinity's architectural standards.
Example:
/ImageGallery
/List.MyGallery.cshtml
/Detail.MyGallery.cshtml
This approach ensures SEO metadata, content routing, and cache behavior work out of the box.
🔗 Sample Code
- GitHub Gist: hawjeh/sitefinity-mvc-widget-best-practice