Custom widgets

The WYSIWYG page editor of Sitefinity CMS works with reusable components called widgets. Widgets provide configurable and reusable parts for page building, which can vary from simple visual element to complex components for displaying content with rich logic.

The Sitefinity Next.js renderer framework provides essential features out of the box, including integration with the WYSIWYG page editor. What is left is writing the code for the React widgets. Developing widgets for the Next.js renderer follows the development principles of React and Next.js components. There are some specific integration points that need to be followed to ensure seamless integration with the Sitefinity CMS. This is demonstrated in the Hello World tutorial below.

Building the component

First you need to create a file that hosts the React component:

1. Use the Next.js starter template that provides the boilerplate for communication with Sitefinity CMS. The template can be found in Sitefinity's Next.js samples GitHub repository. 
2. Create a folder for the widget files, for instance Hello World folder.
3. Create a .tsx file to host our React component, for instance hello-world.tsx.
4. Paste this code in the file:  
5. Save the file.

NOTE: The htmlAttributes function generates the necessary HTML attributes that are required by the WYSIWYG editor to recognize the generated HTML snippet as a widget with its metadata and display its operation and widget designer.

Building the widget designer

Next create an entity file, that would describe the widget designer. We have created the Sitefinity Widget Designers SDK to make the process of defining the entity metadata as easy as possible. For additional information, see the SDK’s documentation on npm. The approach is aiming for parity with the existing Sitefinity autogenerated widget designers. For more information, see Widget designers.

1. Create a .ts file, for instance hello-world.entity.ts. This file holds the metadata for the widget designer to construct the designer.
2. Paste this code in the file:
   

Registration with the framework

The next step is to register the component implementation and the designer metadata with the Next.js renderer. The Sitefinity Next.js SDK will automatically generate the needed designer metadata based on the defined entity. The registry is used to find the component function reference for the widget from the response of the Page Layout service. It is also used when generating metadata for the widget when it is used in the WYSIWYG page editor – labels, visuals etc.

1. Navigate to ...\src\app.
2. Open the widget-registry.ts file.
3. Add a new entry to the map:

Define widget properties

After you implement new widgets, you register them with the renderer as shown above so they can appear in the widget toolbox dialog. With the widget entry in the registry using the editorMetadata property you can define the following optional properties of the widget:

• Title - The display name of the widget, shown in the widget toolbox. For example, Content block.
  
• Name - The name of the widget. If set it will override the name defined in the @WidgetEntity attribute.
• Category - This is one of the categories in which you can place the widget. Categories are predefined and you cannot add custom ones. Instead, you can add your custom widgets in custom sections in the existing categories.
• Section - The section of the widget in the parent category. You can define a custom value or use one of the predefined values to add widgets to the existing sections. You cannot change the ordering of the widget sections.
• EmptyIcon - The icon shown when the widget does not have any HTML output.
• EmptyIconText - The text shown when the widget does not have any HTML output.
• ЕmptyIconAction - The action to perform when the empty text and icon are clicked.
• Order - The order of the widget in the section.
• IconName - The icon shown for the widget in the widget selector.
• IconUrl - Used to define a custom icon to be shown for the widget in the widget selector.
• Toolbox - Used to distinguish widgets for pages and forms. For forms widget the value must be 'Forms'.
• HasQuickEditOperation - Marks whether the widget has quick edit operations.
• InitialProperties - Used to set initial properties for a widget when it is added to the page.

The Sitefinity Next.js SDK provides implementations for some of the standard Sitefinity widgets. For more information, see Next.js renderer widgets.
The widgets’ code can be found as a reference in the public source repository on GitHub.

REST SDK

The Sitefinity Next.js SDK comes out of the box with an SDK that facilitates the communication with the Sitefinity services both server side and on the front end. It provides a way to query content items and their properties, make modifications to them, get page layout, perform searches etc. 

The following example demonstrates how to query content items from Sitefinity CMS. Note that the full type name should be used as the parameter for the request – in the case of news items it should be Telerik.Sitefinity.News.Model.NewsItem. The RestSDK has some of the basic content types predefined under RestSdkTypes:

For more information, see the Sitefinity Next.js SDK at npm.

HTML sanitization

The Sitefinity Next.js SDK provides SanitizerService.sanitizeHtml(html, config?) static method that uses server side and client side DomPurify. For more information on DomPurify, see the npm package page of DomPurify Isomorphic DOMPurify.

The default configuration allows for some additional tags and attributes and could be overridden via SanitizerService.configure(config) where the configuration object is a partial implementation of the DomPurify. For more information on DomPurify configuration, see the GitHub readme DOMPurify.