Sitefinity MVC Widget Best Practices

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:

1. Remove the custom widget from the page
2. Publish the page
3. Re-add the custom widget
4. 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:

1. Install the custom widget on a page (e.g., /about)
2. Ensure your controller includes:
   • An /index method
   • The HandleUnknownAction method
3. Visit an undefined path like /about/detail — the request will be resolved by HandleUnknownAction.

---

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 (via SubscribeCacheDependency()) 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