Extend the built-in widgets

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.

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:

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.

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:

1. Navigate to ...\src\app.
   
2. Open the widget-registry.ts file.
3. Add the new view the views property of the widget entry:
   

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').

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:

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 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.

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.