Register content location with your custom widgets
By default, all built-in and dynamic Sitefinity CMS widgets, which can display content items, register the items’ locations and generate the items’ links using the ContentLocationService. When you place such widget on a page and publish the page, each widget sends data to Sitefinity CMS. The data contains the items that the widget displays, their type, and the page they appear on.
When you are using your own custom widgets to display Sitefinity CMS content items, you must manually register for the ContentLocationService. This way, Sitefinity CMS will know the locations of the content items displayed with you custom widget.
When you publish a page, Sitefinity CMS check for all widgets on the page that implement the IContentLocatableView interface, and for each of them it gets the location information.
If you want your custom widget to have a canonical URL and to provide a location for items, you must implement the IContentLocatableView interface.
NOTE: Sitefinity CMS supports using the IContentLocatableView interface only with custom widgets that inherit from SimpleViewor SimpleScriptView.
Implement the IContentLocatableView interface
The IContentLocatableView interface defines the common information that must be provided by each widget that is able to show content items. It is used for the preview of content items and for issuing a canonical link element for SEO.
You implement the interface, by implementing the IEnumerable<IContentLocationInfo> GetLocations() method and the DisableCanonicalUrlMetaTag property.
The GetLocations() method is called by Sitefinity CMS upon page publish and returns the specific location information about the item type and provider that is used to display the items. In your implementation of the GetLocations() method you must construct an object of type ContentLocationInfo, which tells Sitefinity CMS what type of content is displayed on the page, and what is the full name of the provider used for this content type.
The DisableCanonicalUrlMetaTag property requires no additional implementation by default. It is responsible for instructing Sitefinity CMS whether to render a canonical link. You can add some additional logic to determine its value inside the property implementation or set the value correspondingly.
The following code sample demonstrates the implementation of the IContentLocatableView in a custom widget that inherits from SimpleView:
And its corresponding widget template:
Register a ContentLocation for widgets that display multiple content types
In case your custom widget displays items from more than one content type, you must specify all content types when you register a ContentLocation. To achieve that, you need to return a list of ContentLocationInfo objects, containing a separate ContentLocationInfo object for each content type displayed by your widget.
The following sample demonstrates returning a list of ContentLocationInfo objects in the GetLocations method implementation:
Use a ContentLocationFilter to adjust the registered ContentLocation information
By default, when you register a content location with your custom widget, you inform Sitefinity CMS that all items from the specified content type and respective provider are displayed by this widget. However, there are certain scenarios where you need to limit the scope of displayed items (for example show only items that meet certain criteria like a taxonomy, publication date range, and so on). In such cases you must adjust the information you are passing with your
ContentLocation, so you inform Sitefinity CMS that only certain items from the specified type can be found on the registered location. This is done via configuring a
ContentLocationFilter. A
ContentLocationFilter is an implementation of the
IContentLocationFilter interface and represents a string filter applied to the content location. You must specify a
Value and an optional
Name properties for the filter. The
Value represents a
FilterExpression which is parsed by Sitefinity CMS when working with this location. For more information about constructing a FilterExpression for Sitefinity CMS content see:
Filter expressions for content items.
The following sample demonstrates adding a ContentLocationFilter to the sample referenced earlier in this article. The filter informs the Sitefinity CMS ContentLocationService that this custom widget displays only content items which are marked with a taxon.