Sample: Widget views

Next.js

Overview

Use the View widget sample to create a custom widget, which can have its default view overridden. The widget utilizes the renderview component that requires the following properties:

• widgetKey: The name of the widget
• viewName: The name of the currently selected view (SfViewName), as defined in the views property in the widget registry
• viewProps: ViewPropsBase<T>. It can be extended to include custom properties
• children: A default implementation of a view that will be rendered if nothing is found in the views property with the provided viewName

PREREQUISITES: You must set up a Sitefinity renderer application and connect it to your Sitefinity CMS application. For more information, see Install Sitefinity in Next.js mode. 

Building the component

First you need to create a default view that will be rendered if no view with the provided sfViewName is found.

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. In your widget folder, under ~/src/app/widgets, create a folder for the widget files, for instance custom-views folder.
3. Create a .tsx file to host our React component, for instance widget-view-default-view.tsx.
4. Paste this code in the file:
   TSX

   import { ViewPropsBase } from '@progress/sitefinity-nextjs-sdk';
   import { WidgetViewEntity } from '../widget-view-entity';
   
   export function CustomViewExample(props: ViewPropsBase<WidgetViewEntity>) {
       return (<h1>Custom view for the widget view that overrides the default one</h1>);
   }

5. Save the file.

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

1. Navigate to the ~/custom-viewsfolder.

2. Create a .tsx file to host our React component, for instance widget-views.tsx.

3. Paste this code in the file:

   TSX

   import { WidgetContext, htmlAttributes, getMinimumWidgetContext } from '@progress/sitefinity-nextjs-sdk';
   import { RenderView, ViewPropsBase } from '@progress/sitefinity-nextjs-sdk/widgets';
   import { WidgetViewEntity } from './widget-view-entity';
   import { WidgetViewDefaultView } from './widget-view-default-view';
   
   export function WidgetView(props: WidgetContext<WidgetViewEntity>) {
       const entity = props.model.Properties;
   
       const viewProps: ViewPropsBase<WidgetViewEntity> = {
           attributes: htmlAttributes(props), // attributes are needed for the widget to be visible in edit mode
           widgetContext: getMinimumWidgetContext(props) // this function makes sure that the information is react-safe for transfer between SSR and CSR components
       };
   
       return (
         <RenderView
           viewName={entity.SfViewName} // Automatically populated from the widget designer. The name of the selected custom view registered in the 'views' property in the widget registry
           widgetKey={props.model.Name} // the name of the widget as registered in the widget registry. In this case 'WidgetView'
           viewProps={viewProps}> {/*viewProps can be any type inheriting the ViewPropsBase*/}
           <WidgetViewDefaultView {...viewProps} /> {/*the default view that will be rendered if no view with the provided SfViewName is found */}
         </RenderView>
       );
   }

4. Save the file.

Building the widget designer

Next create an entity file, that would describe the widget designer.

1. Create a .ts file, for instance widget-view-entity.ts. This file holds the metadata for the widget designer to construct the designer.

2. Paste this code in the file:

   TypeScript

   import { ContentSection, DisplayName, ViewSelector, WidgetEntity } from '@progress/sitefinity-widget-designers-sdk';
   
   @WidgetEntity('WidgetView', 'Widget view')
   export class WidgetViewEntity {
       @ContentSection('Display settings')
       @DisplayName('Widget view')
       @ViewSelector()
       SfViewName: string = 'Default';
   }

3. Save 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:

   TypeScript

   import { WidgetRegistry, initRegistry, defaultWidgetRegistry } from '@progress/sitefinity-nextjs-sdk';
   import { WidgetView } from './widgets/widget-view/widget-view';
   import { WidgetViewEntity } from './widgets/widget-view/widget-view-entity';
   import { CustomViewExample } from './widgets/widget-view/custom-views/custom-view-example';
   
   const customWidgetRegistry: WidgetRegistry = {
       widgets: {
           'WidgetView': {
               componentType: WidgetView, // registration of the widget
               entity: WidgetViewEntity, // registration of the designer
               ssr: true, // whether this is a server rendered or client rendered component
               editorMetadata: {
                   Title: 'Widget view'
               },
               views: {
                   'CustomViewForWidgetView': {
                       Title: 'Custom view for widget view',
                       ViewFunction: CustomViewExample
                   }
               }
           }
       }
   };
   
   customWidgetRegistry.widgets = {
       ...defaultWidgetRegistry.widgets,
       ...customWidgetRegistry.widgets
   };
   
   export const widgetRegistry: WidgetRegistry = initRegistry(customWidgetRegistry);

Run the sample

This sample is available in Sitefinity’s GitHub repository. You can run and play with it.
To do this, perform the following:

1. Go to Sitefinity’s GitHub repository Sitefinity Next.js samples.
2. Expand Code and click Download ZIP.
3. Extract the files on your computer.
4. In the extracted folder, navigate to \nextjs-samples-main\nextjs-samples-main\src\widget-view folder.
5. In the command console run npm install.
6. Open the .env.development file.
7. In section PROXY SETTINGS, change the SF_CMS_URL property to the URL of your Sitefinity CMS site.
   If you have deployed Sitefinity CMS on the IIS, point to https://localhost:<https_port>.
8. If your Sitefinity CMS is hosted on the cloud, in SF_LOCAL_VALIDATION_KEY= add your validation key. For more information, see Set up the project for local development (using Next.js Renderer).
9. In the command console run npm run dev.
10. Log in to your Sitefinity CMS instance and place the widget on a page.