Custom Widget Development

Getting Started With Custom Widgets

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.

Tip: 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.

Prerequisites

  • Reach out to your Customer Success Manager to enable installing custom widgets for your organization on the Staffbase platform.
  • Install Node.js and Node Package Manager (npm) to your computer to build the custom widget.

Note: 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 custom widget.

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

  2. 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 Experience 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, must be kebab-case
15 */
16
17 attributes: ['message'],
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://react-jsonschema-form.readthedocs.io/en/latest/
27 */
28
29 configurationSchema: configurationSchema,
30 /**
31 * schema to add more customization to the form's look and feel
32 * @see https://react-jsonschema-form.readthedocs.io/en/latest/api-reference/uiSchema/
33 */
34
35 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: 'https://example.com/widget-icon.png',
47}
48
49/**
50 * Meta Information about the widget
51 */
52const externalBlockDefinition = {
53 blockDefinition,
54 author: 'Staffbase',
55 Version: '1.0.0',
56}

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 const factory: BlockFactory = (Base, widgetApi) => {
2 private theme;
3
4 return class ContentBlock extends Base {
5
6 get props() {
7 return {
8 message: this.getAttribute('message') || '',
9
10 }
11 }
12 get observedAttributes() {
13 return ['message'];
14 }
15 }
16 };
17
18 /**
19 * Definition of the widget
20 */
21 const blockDefinition = {
22 ...
23 attributes: ['message'],
24 ...
25 }

You need to:

  • Add another name to the array in the property attributes in the block definition
  • Add the same name to the array in the observedAttributes method in the widget class
  • Add a getter to the props method in the widget class

After adding the name and get props(), the code will look like this:

1 const factory: BlockFactory = (Base, widgetApi) => {
2 private theme;
3
4 return class ContentBlock extends Base {
5
6 get props() {
7 return {
8 message: this.getAttribute('message') || '',
9 name: this.getAttribute('name') || ''
10 }
11 }
12 get observedAttributes() {
13 return ['message', 'name'];
14 }
15 }
16 };
17
18 /**
19 * Definition of the widget
20 */
21 const blockDefinition = {
22 ...
23 attributes: ['message', 'name'],
24 ...
25 }

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.

Tip: 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 }) => {
2 return (
3 <div>
4 <h1>Hello {message}</h1>
5 <p>I’m {name}.</p>
6 </div>
7 )
8}

Tip: 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.

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/custom-widget.js

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

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 at: dist/custom-widget.js

Host the Custom Widget

Host your custom widget on a web server, after you have tested and ensured that 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 Experience Studio.

Note: 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.