Custom widgets

Overview

Besides usage of already available widgets for the Kaa Web Dashboard it is also possible to embed custom widgets into the WD. The custom widgets library (further CWL) should be placed into a separate git repository and may contain any number of widgets.

Custom library requirements

CWL must be bundled according to the CommonJS Module specification, an entrypoint must be placed in the {projectRoot}/lib/index.js path. To be able to use custom widgets, CWL repository should be mounted into the WD Kubernetes pod into the /usr/src/kaa-dashboard/externalWidgets directory.

An example project structure of CWL:

  |__lib
    |__index.js
  |__public
    |__index.html
  |__src
    |__components
    |__index.js
  |__package.json
  |__yarn.lock

Note: lib is a required directory.

Widget export notation details

A source code entrypoint (e.g., {projectRoot}/src/index.js from the given directory structure above) for widgets must contain the following exports notations:

  {
    value: <string>,          // Widget type
    node: <node>,             // Widget React node
    validation: <array>       // Array of the required fields for the widget configuration
  }

value in the widget’s export notation corresponds to the widget type in widget configuration. node is a link to React component representing the widget. validation should be represented as an array and may contain any number of required keys for the widget configuration.

Widget export notation examples

From the example directory structure given above {projectRoot}/src/index.js file may contain export as a single object:

  export default {
    value: 'widgetType',
    node: Widget, 
    validation: ['required_field_key']
  };

or an array of objects:

  export default [
    {
      value: 'widgetType1',
      node: Widget1,
      validation: []
    },
      {
      value: 'widgetType2',
      node: Widget2,
      validation: ['required_field_key']
    }
  ];

Custom widget configuration in Web Dashboard

Assuming that you have mounted your custom widget repository to the WD Container, it would be possible to include the custom widgets into the WD configuration as follows:

  config:
    type: widgetType

Minimal required configuration for custom widget

Minimal required configuration for the custom widget in the WD:

  config:
    type: <string>
    header: <object>
      title: <string>

After the widgets are integrated into the WD, they will inherit their configurations from WD configuration as their component props.