Custom widgets

• Create custom widget
• Connecting custom widget
  • Connect to сustom widget’s local development server
  • Upload bundled source file
• Activating custom widget
• Development

In addition to offering a set of standard ready-to-go widgets, the Kaa web UI (WD) allows you to upload your own custom widgets. Such widgets can be then added to your library of standard widgets and used throughout your IoT solution dashboards. This guide will give you step-by-step instructions on how to get started.

A sequence of steps to add a custom widget to Kaa is the following:

1. Create a custom widget
2. Connect the widget to Kaa
3. Activate the widget in the Kaa Web UI
4. Add the widget to your Kaa solution dashboard for further uses

Create custom widget

A custom widget should be created in a separate project and bundled using any project bundler. The development technologies and tools can be of your own choice.

In order to make the first acquaintance with custom widgets and their development process easier, we have prepared basic project configurations with Webpack and Rollup bundlers:

• Webpack starter
• Rollup starter

We have also created quick-start projects based on the React.js library, however, React.js is not a requirement and you may develop custom widgets using any front-end stack that you prefer.

Moreover, to support TypeScript typings in custom widgets, we have created an npm package that includes all the needed TypeScript types.

A custom widget must meet the following conditions in order to be compatible with the Kaa web UI:

• The custom widget bundle should be compatible with System.js
• The custom widget bundle file should export at least one function mount that accepts two arguments: widget nodeElement and widget context

Connecting custom widget

In the Kaa web UI, there’s a separate page for working with custom widgets - the Custom widgets page.

There are two ways to start working with your custom widget:

• Connect and use - run your custom widget project locally and connect the Kaa web UI to the local development server by defining its localhost url
• Upload - upload your bundled custom widget source into the Kaa web UI

Connect to сustom widget’s local development server

By clicking Connect and use, you will open up a dialog window that will help you connect the Kaa web UI to the local development server running your custom widget.

To enable your custom widget to connect to the Kaa WD, its development server should expose three files from the root of its base URL:

• /index.js
• /widget.json
• preview image.

Taking the above into consideration, the URL to the bundle file should correspond to the following schema: http://localhost:{port}/index.js.

index.js - the bundle file with the custom widget sources. Note that the widget source must be bundled into the system format.

widget.json - the custom widget configuration file.

The widget.json file should contain the following setting keys and might look as follows:

{
  "packageName": "@kaa/custom-widget-demo",
  "name": "Custom widget demo",
  "description": "Example of custom widget",
  "category": "Experimental",
  "preview": "preview.svg",
  "version": "1.0.0"
}

After the local development server is up and running and all the above conditions are met, you can connect the new widget to the WD.

After you add your custom widget to the WD widget system,

it will also be added to the Custom widgets page.

Upload bundled source file

The widget upload feature allows you to fill in the widget settings manually and upload the widget preview image and a bundled javascript source file.

There are multiple ways how you can update the bundle version. For example, you can use the Upload bundle button on the newly added widget on the Custom widgets page:

or upload it from the widget configuration edit dialog window:

Another convenient way to update the bundle is from the sandbox page:

The sandbox upload utilities will fetch the bundle from the development server by the http://localhost:{port}/index.js URL and persist it as the widget source.

Activating custom widget

To be able to use your custom widget on the solution dashboard, you should first activate it in the custom widget registry:

After you mark the widget Active, it will become available for usage from the standard library of Kaa widgets.

Development

The custom widget sandbox functionality is available in the Kaa web UI.

The sandbox page loads the widget from the local development server and makes it easy for you to develop, view, and test your widget.

If you enable the Development mode,

the latest local widget version will be used on the solution dashboard, otherwise the bundled javascript file will be loaded.