Custom Widget Development

Custom widgets are web components that allow you to add specific types of content blocks to News or Pages on the Staffbase platform. Learn more about custom widgets here.

Staffbase makes developing custom widgets easy with the Staffbase widget generator. The Staffbase widget generator is a project generator to help you kickstart your widget development. It provides a widget SDK to enable your custom widget to communicate with the Staffbase platform.

The generated project uses:

• TypeScript to simplify JavaScript coding
• React.js to build the user interface for your custom widget
• Webpack as a module bundler for the JavaScript file created for your custom widget

With this widget generator, you are completely equipped to create a custom widget easily.

• The page to install and manage custom widgets is enabled for your organization. Reach out to your Customer Success Manager if it is not enabled.
• Node.js version 18 or higher and Node Package Manager (npm) version 9 are installed on your computer.
  Note: If you have a higher version of Node.js, you need to revert to the version specified above.

As a first step, create a custom widget project that will act as the framework for you to develop your custom widget.

Use the Staffbase widget generator and follow these steps:

1. Run the create-widget command in your terminal.

 npx @staffbase/create-widget

The create widget project prompts you to provide a name for your organization and custom widget.

2. Provide a name for your organization. For example: windstar

3. Provide a name for your custom widget. For example: custom-widget

4. Run the command to navigate to the directory you created. For example, if the name you provided is custom-widget, run the command:

cd custom-widget

5. Install your custom widget project.

npm install

Now, you have created your custom widget project. You can start adding functionalities to your custom widget.

Once you have created your custom widget project, define the look of your custom widget, add custom properties, and add the functionalities you want. Later test, build, and host the widget on a web server.

Requirement:

• The custom widget must run on all browsers supported for the Staffbase platform.

You need to define the custom widget so that it registers itself to the platform when the custom widget URL is installed to the Staffbase Studio. This happens by calling the window.defineBlock method and passing the definition as the parameter during registration.

The definition needs to follow the following structure and conventions:

/**
 * Definition of the widget
 */
const blockDefinition = {
  /**
   * tag of the widget, must be compatible with webcomponent naming conventions
   */
  name: 'custom-widget',
  /**
   * the implementation of the webcomponent
   */
  factory: factory,
  /**
   * DOM-attributes of the element
   */

  attributes: widgetAttributes,
  /**
   * set to "inline" if you want the element to behave like a span element rather than a div element
   * if not specified, it defaults to "block"
   */

  blockLevel: 'block',
  /**
   * schema used for creating the configuration form
   * @see https://rjsf-team.github.io/react-jsonschema-form/docs/
   */

  configurationSchema: configurationSchema,
  /**
   * schema to add more customization to the form's look and feel
   * @see https://rjsf-team.github.io/react-jsonschema-form/docs/api-reference/uiSchema
   */

  uiSchema: uiSchema,
  /**
   * Label displayed in the settings dialog and in the default widget preview.
   */

  label: 'My Custom Widget',

  /**
   * Icon displayed on the widget installation page.
   * We recommend an icon with the dimensions 32x32 px.
   */
  iconUrl: icon,
};

/**
 * Meta Information about the widget
 */
const externalBlockDefinition: ExternalBlockDefinition = {
  blockDefinition,
  author: pkg.author,
  version: pkg.version
};

By default, a placeholder icon is used for any new custom widget. You can add a custom icon to your custom widget to make it more visually appealing.

// Import the icon
import icon from "../resources/custom-widget.svg";

// Add the icon to the block definition
const blockDefinition = {

  iconUrl: icon,

};

You can also reference an external URL for the icon.

const blockDefinition = {

  iconUrl: 'https://example.com/custom-widget-icon.png',

};

Icon Requirements:

• Format: PNG or SVG
• Size: 32 x 32 px
• Color: #464B50
• Line thickness: 1.5 px
• Outline style (no filled icons)
• Transparent background

You can add more properties to customize your widget. The properties are explained in the Widget SDK via TypeScript typings.

To do this:

The script follows the following structure:

  /**
   * Define which attributes are handled by the widget. This should be also reflected in configuration schema
   */
  const widgetAttributes: string[] = [
    'message',
  ];

  /**
  * Definition of the widget
  */
  const blockDefinition = {
      ...
      attributes: widgetAttributes,
      ...
  }

You need to:

• Add the name of the new attribute to the const widgetAttributes: string[] array in the widget class

After adding the name, the code will look like this:

  const widgetAttributes: string[] = [
    'message', 'name',
  ];

This is done in the configuration-schema.ts file and follows the JSON Schema format. Learn more about the possibilities here.

Your configuration-schema.ts file should look like this:

  export const configurationSchema: JSONSchema7 = {
    properties: {
      message: {
        type: "string",
        title: "Message",
      },
      name: {
        type: "string",
        title: "Name",
      },
    },
  };

  export const uiSchema: UiSchema = {
    message: {
      "ui:help": "Please enter a message to show",
    },
    name: {
      "ui:help": "Please enter a name to show",
    },
  };

You can add functionalities to your custom widget to show a specific content block in News and Pages. Based on the business use case, add functionalities to your custom widget, such as showing weather updates, feeds from other platforms and so on. If you want the content block in the widget to display a simple message, you can add the function accordingly.

For example:

export const CustomWidget = ({ message, name }: CustomWidgetProps): ReactElement => {
  return (
    <div>
      <h1>Hello {message}</h1>
      <p>I'm {name}.</p>
    </div>
  )
}

Once you have added the functionalities, build the custom widget and get it ready to integrate with the Staffbase platform.

Build the custom widget by running the command:

npm run build

Once you type the command a new dist folder is added to your project folder. The bundled sources will be available in the dist folder following the naming convention <organization-name>.<widget-name>.js. For example: dist/windstar.custom-widget.js

You can preview and test the custom widget you have developed to ensure that it works as expected.

Run the following command to:

• Preview the custom widget

npm start

• Test the widget on your machine

npx live-server dist/windstar.custom-widget.js

Alternatively, use github-pages for testing before hosting it on the production web server.

Host your custom widget on a web server or a content delivery network (CDN) after testing and ensuring it functions as desired.

Provide the Staffbase platform administrator the widget bundle URL to integrate the custom widget with the Staffbase platform. The administrator can then install the URL in Staffbase Studio.

• Web Components
• Staffbase Widget Generator
• Staffbase Custom Widget Examples
• Node.js
• Node package manager (npm)
• React.js
• React Form Based on JSON Schema
• General uiSchema Reference