@progress/sitefinity-nextjs-sdk

Sitefinity Next.js SDK

Provides OOB widgets for Sitefinity, written in the Next.js framework; abstraction for communicating with Sitefinity; additional API, typings, and tooling.

Getting started

Install via npm:

npm i @progress/sitefinity-nextjs-sdk --save

Via yarn:

yarn add @progress/sitefinity-nextjs-sdk

You can get started using it with our starter template in the follwing NextJS samples repo. It provides the needed integration for communicating with a Sitefinity server, setup documentation, and the basic boiler plate for getting started.

Contents

Main

The root module contains mainly tooling and interfaces related to widget rendering, models, metadata, renderer contracts.

Custom widgets

Creating and declaring custom widgets should adhere to the following convention. Widgets should be registered in a WidgetRegistry by WidgetMetadata, which consists of:

• componentType - reference to the component funciton
• metadata, describing the properties of the widget:
  • entity? - class reference, decorated using the @progress/sitefinity-widget-designers-sdk custom decorators
  • designerMetadata? - JSON format for a custom designer
• editorMetadata? - implementing the interface EditorMetadata, providing information to the editor about widget category, name, and other visual and operational data
• ssr? - indicating whether the widget should be server-side rendered or not

For more information and samples visit our NextJS samples repo.

Required html attributes

In order for the WYSIWYG page and form editor to work properly, several custom html attributes need to be provided while viewing the markup in edit mode. The htmlAttributes handles the general case for this need. For aggregating custom CSS classes we provide the helper classNames.

import { htmlAttributes, classNames } from '@progress/sitefinity-nextjs-sdk';

export function CustomWidget(props: WidgetContext<CustomWidgetEntity>) {
    const dataAttributes = htmlAttributes(props);
    const customCssClasses = classNames('someClassNames');
    dataAttributes['className'] = customCssClasses;

    return (
        <div {...dataAttributes}>
            custom widget content
        </div>
    );
}

Widget children content holder

To define an area in your custom widget template where children widgets could be added, to the HTML element that would hold them should have the data-sfcontainer attribute set.

The WYSIWYG editor will diplay on that spot the option to add a widget. If you want to have the ability to add widgets to your manually designated places and hide the default empty widget "add widget" placeholder, you can use the setHideEmptyVisual function to modify the dataAttributes.

import { htmlAttributes, setHideEmptyVisual } from '@progress/sitefinity-nextjs-sdk';

function CustomWidget(props: WidgetContext<CustomWidgetEntity>) {
    const dataAttributes = htmlAttributes(props);
    setHideEmptyVisual(dataAttributes, true); // this would hide the default empty visual

    return (
        <div {...dataAttributes}>
            ...
            <div id='childrenHolder' data-sfcontainer='containerId'>
            </div>
        </div>
    )
}

Rest SDK

import { RestClient } from '@progress/sitefinity-nextjs-sdk/rest-sdk';

Provides a way to communicate with Sitefinity's REST API for the majority of the necessary operations and data queries. The entry static class RestClient is part of the @progress/sitefinity-nextjs-sdk/rest-sdk module.

Widgets

import * from '@progress/sitefinity-nextjs-sdk/widgets';
import * from '@progress/sitefinity-nextjs-sdk/widgets/forms';

These modules contain the following OOB basic widgets:

• Breadcrumb
• Call to action
• Classification
• Content list
• Content block
• Document list
• Forms
  • Form
  • Checkboxes
  • Content block
  • Dropdown
  • Dynamic list
  • File upload
  • Multiple choice
  • Paragraph
  • Section
  • Submit button
  • Text field
• Image
• Language selector
• Navigation
• Search
  • Search box
  • Search results
  • Search facets
• Section
• User management
  • Login form
  • Change password
  • Registration
  • Reset password

Styling

import { StyleGenerator } from '@progress/sitefinity-nextjs-sdk/widgets/styling';

Provides styling helper methods and interfaces that we provide mainly in the StyleGenerator class.

Code reference

For the exact implementation of the widgets and tooling, plese refer to the public NextJS sdk read-only repo