Extend the built-in widgets
Overview
Sitefinity Next.js renderer comes with a set of built-in widgets, such as Navigation, Content list, Content block, etc. You can extend these widgets to suit your requirements in the following ways:
- Customize the views of the widgets.
- Modify the logic behind the widgets.
- Add/Modify fields in the widget designer.
The source code of the built-in widgets is located in the Next.js SDK GitHub repository.
Modify the logic behind the widgets
You can modify the default or add custom logic to the behavior of a built-in widget. For more information and reference, see the built-in widgets code base in GitHub.
This is achieved by replacing the functional component of that widget with a custom one and registering it in the widget registry.
The creation of the new functional component is the same as when creating a one for a custom widget. For more information, see Custom widgets.
To register the new component in the widget registry you have to find the existing entry for the widget and modify its componentType
property:
Add fields to the widget designer
You can include, hide or modify additional fields in the widget designer. You do this by extending the default Entity class that serves as the metadata source for the automatic generation of widgets designers.
The Sitefinity Widget Designers SDK is created to make the process of defining the entity metadata as easy as possible. For more information, see the SDK’s documentation on npm.
NOTE: Decorators added in the extended entity, which are also present in the base entity, override the base ones. Decorators are inherited from the base class.
EXAMPLE: To view a sample of how to extend the Content list widget's entity, see Extend the Content list widget sample.
Customize the views for the widgets
You can add new or override the existing widget views.
You can do this by creating a .tsx
file to host the view. The view is a standard Next.js functional component. The component accepts a single parameter that holds the view properties coming from the widget.
EXAMPLE: Example for Breadcrumb widget: export function CustomView(props: BreadcrumbViewProps<BreadcrumbEntity>) { }
After the view is implemented it should be registered in the widget registry:
- Navigate to
...\src\app
.
- Open the widget-registry.ts file.
- Add the new view the views property of the widget entry:
Creating custom views for widgets
To create a custom view for an OOB widget it is needed to have:
- A function representing a Next.Js component that will render the new view.
- That function must accept a
ViewPropsBase<T>
where T
is the entity related to the widget. Both the view props and entity can be extended with custom implementations that add additional properties which can be used in your view. Out of the box widgets usually come with such view props classed that allow for custom views.
- The HTML of the new view must be wrapped in an element that has the attributes provided in the
viewProps.
- The view must be registered in the widget registry in the desired widget's
views
property and the entity class of that widget must have either a SfViewName
or SfDetailViewName
string properties marked with @DataType('viewSelector')
.
Widget default view
The view function:
The default widget view is what is inside of the RenderView
element and is rendered if there is no view provided that would match the selected value from the designer.
Then this function must be registered in the views
property for the widget. In this case LanguageSelectorEntity
has SfViewName
property so this step is covered:
Widget details view
The widgets that support detail views are Content list and Document list. They can accept custom implementations for the detail rendering:
After that it should be added in the views for the widget. There are some views already provided out of the box (content list views, content list detail views etc.), so your custom view can be either added to them or it can replace them. Either way, the detail view name must be prefixed with 'Details.'
:
The views property of the widget metadata
The views property can be used to add custom views or detail views to widgets. In order to use it, the widget's entity class should have one of two properties called SfViewName
(used for the widget's view) and SfDetailViewName
(Used for the detail view of a widget (Content list and Document list have it)). Both these properties should be marked with the decorator @DataType('viewSelector')
and should be strings.
For example:
Views property can have one of the two following structures:
- Object that has the unique name (which is visualized in the widget editor) of the view as a key and the reference to the component function as value.
- Object that has the unique name of the view as a key and another object that has a friendly title as
'Title'
property (which is visualized in the widget editor) and the reference to the component function as 'ViewFunction'
property.
The naming convention for the unique name is: Everything that starts with 'Details.'
is considered as a view that will be rendered for the details view and everything else is for the widget view.
For example:
RenderView component
You can create your own view logic based on the selected view name in the widget designer by taking advantage of the RenderView
component. It is designed to read the widget registry and take the metadata for the widget based on the widgetKey
and viewName
parameters. If a match is found in the registry, it will render that view, otherwise it renders the child of the RenderView
.
If an entity class is missing one of the view name properties mentioned above, it can be extended:
For more infomration on the RenderView API usage, see the following example of a Csutom widget view.
Widget personalization operation
Every custom widget that is created will have the personalization operation available in the page editor by default. That can be turned off by setting a flag in the editor metadata when registering the widget in the widget registry, but you should be aware of some limitations, for more information about the limitations, see Widget personalization.