Custom Widget Development

Get started with developing your own custom widget.

Employee App
Front Door Intranet

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.

You can develop widgets with your in-house team or outsource development to our partners or vendors. Staffbase has built a network of technical implementation partners and we are happy to support you in finding the right partner or vendor.

Custom widgets cannot be made available in the public area of your app.

Prerequisites

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

Custom widgets are developed and owned by your organization. Although Staffbase as the platform is not liable for the content or services used for the custom widget, we recommend that the custom widgets comply with Staffbase's Terms of Service and Acceptable Use Policy defined by the platform.

Create a Custom Widget Project

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.

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

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

  3. 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
  1. Install your custom widget project.
npm install

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

Develop 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:

Define the Custom Widget

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:

1/**
2 * Definition of the widget
3 */
4const blockDefinition = {
5 /**
6 * tag of the widget, must be compatible with webcomponent naming conventions
7 */
8 name: 'custom-widget',
9 /**
10 * the implementation of the webcomponent
11 */
12 factory: factory,
13 /**
14 * DOM-attributes of the element
15 */
16
17 attributes: widgetAttributes,
18 /**
19 * set to "inline" if you want the element to behave like a span element rather than a div element
20 * if not specified, it defaults to "block"
21 */
22
23 blockLevel: 'block',
24 /**
25 * schema used for creating the configuration form
26 * @see https://rjsf-team.github.io/react-jsonschema-form/docs/
27 */
28
29 configurationSchema: configurationSchema,
30 /**
31 * schema to add more customization to the form's look and feel
32 * @see https://rjsf-team.github.io/react-jsonschema-form/docs/api-reference/uiSchema
33 */
34
35 uiSchema: uiSchema,
36 /**
37 * Label displayed in the settings dialog and in the default widget preview.
38 */
39
40 label: 'My Custom Widget',
41
42 /**
43 * Icon displayed on the widget installation page.
44 * We recommend an icon with the dimensions 32x32 px.
45 */
46 iconUrl: icon,
47};
48
49/**
50 * Meta Information about the widget
51 */
52const externalBlockDefinition: ExternalBlockDefinition = {
53 blockDefinition,
54 author: pkg.author,
55 version: pkg.version
56};

Add Custom Widget Icon

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.

1// Import the icon
2import icon from "../resources/custom-widget.svg";
3
4// Add the icon to the block definition
5const blockDefinition = {
6
7 iconUrl: icon,
8
9};

You can also reference an external URL for the icon.

1const blockDefinition = {
2
3 iconUrl: 'https://example.com/custom-widget-icon.png',
4
5};

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

Add Custom Properties to Configure the Widget

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

To do this:

Extend the List of Attributes

The script follows the following structure:

1 /**
2 * Define which attributes are handled by the widget. This should be also reflected in configuration schema
3 */
4 const widgetAttributes: string[] = [
5 'message',
6 ];
7
8 /**
9 * Definition of the widget
10 */
11 const blockDefinition = {
12 ...
13 attributes: widgetAttributes,
14 ...
15 }

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',
];

Add Specifications for the Configuration Dialog

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:

1 export const configurationSchema: JSONSchema7 = {
2 properties: {
3 message: {
4 type: "string",
5 title: "Message",
6 },
7 name: {
8 type: "string",
9 title: "Name",
10 },
11 },
12 };
13
14 export const uiSchema: UiSchema = {
15 message: {
16 "ui:help": "Please enter a message to show",
17 },
18 name: {
19 "ui:help": "Please enter a name to show",
20 },
21 };

A preview of the configuration dialog is shown in the developer preview mentioned below.

Add Functionalities to Your Custom Widget

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:

1export const CustomWidget = ({ message, name }: CustomWidgetProps): ReactElement => {
2 return (
3 <div>
4 <h1>Hello {message}</h1>
5 <p>I'm {name}.</p>
6 </div>
7 )
8}

You can find your custom widget project file in src with a tsx extension. For example, if your custom widget name is custom-widget, you will find the file custom-widget.tsx in your project.

Build the Custom Widget

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

Test the Custom Widget

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 the Custom Widget

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

Provide the Widget Bundle

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.

You can also have multiple custom widgets in a bundle. If the widget bundle URL contains more than one widget, each widget in the bundle must register itself separately during installation. Read define custom widget for more information.

Additional Helpful Information