Custom Widget Tutorial

Custom widgets are web components that you can add as specific content blocks to News or Pages on the Staffbase platform. In this tutorial, we take you through how to build a basic Countdown widget on your own and make it available on News or Pages. After completing this tutorial, you’ll be familiar with the widget building process and can start building custom widgets based on your business requirement.

A Countdown widget provides your users a countdown timer to major upcoming company events. This can be created as part of a campaign to build excitement and readiness around an anticipated event. Your editors can add the widget to News posts and Pages like other standard widgets.

Once you build the widget, install it on the Staffbase platform to make the widget available on News and Pages. Your editors can configure the widget with the event date in a News post or a Page.

Users, in turn, will see how much time is left until the event based on the event date entered by the editor.

This tutorial is designed only to help you start building a Countdown widget on your own, a basic version is shown here. Feel free to use this as a base to build more improvements and features on it, and design the Countdown widget suited best for your requirement. For instance, you can improve this further by adding a date picker for the Event Date field, a teaser message for the countdown, or even a check-in button for users attending the event, and much more.

• 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.
  
  If you have a higher version of Node.js, you need to revert to the version specified above.

1. Create a project folder with the name Widget in your local drive.

2. In the terminal, run the command to navigate to the directory where you created the project.
   For example, cd /Users/.../Documents/Widget

3. Run the command to create resources and files in your project.

 npx @staffbase/create-widget

The terminal prompts you to give the widget details.

4. Provide the following information:

• Name of your organization: Enter the name of your organization.
• Name of your widget: Set the widget name as countdown-widget.
  
  The custom widget name must include at least one hyphen. For example, my-widget.

A new folder named countdown-widget has been created under your project folder. All the required resources and files will be added to this folder.

5. Run the command to navigate to the countdown-widget folder in your project.

cd countdown-widget

6. Run the command to install the dependencies.

npm install

Now, you have created your custom widget project.

The preview shows how each of these views will look like:

• Configuration dialog of the widget to editors in the Staffbase Studio
• Final widget content for end-users

1. In your development environment, open the countdown-widget folder.
2. Run the command to start the project.

npm run start

The developer preview opens.

3. Type your message and click Submit.
   Your message will be displayed under Widget preview.
   

You have successfully installed and started your custom widget. Now you can define the Countdown widget.

You already have the base project for your custom widget. As the project is currently a simple hello world, you need to remove some properties and add new ones to define functionalities for the Countdown widget.

This file gives you the possibility to define the Configuration dialog for the widget in the Staffbase Studio. The data scheme used in the file follows the JSON Schema standard. Learn more about it here.

1. Under the src folder, open the configuration-schema.ts file.

2. Replace all the values 'message' with 'enddate' as shown in the code snippet. The property enddate allows you to define the event date for your Countdown widget later.

export const configurationSchema: JSONSchema7 = {
  properties: {
    enddate: {
      type: 'string',
      title: 'enddate',
    },
  },
}

/**
 * schema to add more customization to the form's look and feel
 * @see https://react-jsonschema-form.readthedocs.io/en/latest/api-reference/uiSchema/
 */
export const uiSchema: UiSchema = {
  enddate: {
    'ui:help': 'Please enter a message to show.',
  },
}

3. Under export const configurationSchema, modify the following properties:

• type: Replace "string" with "number"
• title: Replace "enddate" with "Event Date"

export const configurationSchema: JSONSchema7 = {
  properties: {
    enddate: {
      type: 'number',
      title: 'Event Date',
    },
  },
}

This modifies the type value entered in the field label of your widget configuration.

4. To add a help text for the Event Date field, modify the ui:help value to "Enter a date in Unix date format".

export const uiSchema: UiSchema = {
  enddate: {
    'ui:help': 'Enter a date in Unix date format.',
  },
}

5. Save the changes.

The index file contains the main class, which is invoked in the registration call and the block definition for the metadata.

In the index file, declare the metadata used in the configuration file in your index file.

1. In your development environment, navigate to the src folder.

2. Open index.tsx file.

3. Scroll to the code snippet where const widgetAttributes: string[] is defined.

4. Replace the value 'message' with 'enddate' so that the widget reacts to the changes made to the attribute.

const widgetAttributes: string[] = ['enddate']

5. Save the changes.

The widget file is the view layer of your widget and will be called by the main class. It gets all of the attributes as properties.

1. Under the src folder, open the countdown-widget.tsx file.
   

2. Replace 'message' with 'enddate' and 'string' with 'number' in CountdownWidgetProps export.

export interface CountdownWidgetProps extends BlockAttributes {
  enddate: number;
}

3. Paste the following code snippet before export function const CountdownWidget.

const calculatedifference = (startdate: number, enddate: number = Date.now()) => {
  const second = 1000,
    minute = second * 60,
    hour = minute * 60,
    day = hour * 24
  const distance = enddate - startdate
  const days = Math.floor(distance / day)
  const hours = Math.floor((distance % day) / hour)
  const minutes = Math.floor((distance % hour) / minute)
  const seconds = Math.floor((distance % minute) / second)

  return { days, hours, minutes, seconds }
}

4. Define the end-user view by inserting the following code snippet for export const CountdownWidget.

const [actualdate, setactualdate] = React.useState(Date.now())
const { days, hours, minutes, seconds } = calculatedifference(actualdate, enddate)
React.useEffect(() => {
  setInterval(() => {
    setactualdate(Date.now())
  }, 1000)
}, [])

5. Replace the return value with the following code snippet. This defines how the countdown will be displayed to the end-user.

  <div>
    <ul>
      <li>
        <span>{days}</span> Days
      </li>
      <li>
        <span>{hours}</span> Hours
      </li>
      <li>
        <span>{minutes}</span> Minutes
      </li>
      <li>
        <span>{seconds}</span> Seconds
      </li>
    </ul>
  </div>

6. Save the changes.

You may have already tested the widget after making changes to each file. Run it in the developer preview by providing an Event Date in Unix date format.

Ensure that your developer preview looks like this:

You have defined and tested your widget. Now you can build the widget by running the command:

 npm run build

Check the message to see if the build was successful.

Once you get a message that the build was successful, you can host the widget bundle. Under the dist folder, the .js file contains the license information and details to allow you to host the Countdown widget on a web server or a content delivery network (CDN).

• 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