Dashboard Builder #

The Dashboard Builder allows you to create personalized dashboards to visualize data from the Kuzzle IoT platform.

A dashboard is made up of widgets that can be of different types. By default, the Dashboard Builder offers 3 types of widgets:

• Chart: allows you to visualize data sources in the form of a graph
• Map: allows you to view assets and devices on a map or position history
• Table: displays information in a spreadsheet type table

Custom Widgets #

It is possible to create new widgets and make them available to users of the IoT platform to create dashboards.

Widgets are fairly simple. They are constituted by two components:

• a widget, e.g. MyWidget.vue
• a form, e.g. MyWidgetForm.vue

Keep in mind that the Dashboard Widget will provide the Kuzzle SDK, which you can inject in these components.

The Widget #

The widget is nothing more than a Vuejs component that will receive the following props

Copied to clipboard!

  props: {
    // The settings, created by the Form
    widgetSettings: {
      type: Object,
      required: true,
    },
    // The height, expressed in Vue Grid slots
    widgetHeight: {
      type: Number,
      required: true,
    },
    // The width, expressed in Vue Grid slots
    widgetWidth: {
      type: Number,
      required: true,
    },
    // The index name where the Dashboard engine is installed
    engineIndex: {
      type: String,
      required: true,
    },
  },

The shape of the widgetSettings prop is up to you, it is an object where you can store all the settings you widget needs to work. This object is created and edited by the widget form.

Example:

Copied to clipboard!

<template>
  <div class="text-left">
    <div class="w-100 h-100">
      <h1> Hello World </h1>
    </div>
  </div>
</template>

<script>
export default {
  name: 'DemoWidget',

  data() {
    return {};
  },
};
</script>

<style lang="scss"></style>

The Form #

The form is a Vuejs component that is included in the New/Edit Widget Modal, accepting the following props:

Copied to clipboard!

  props: {
    // The index name where the Dashboard engine is installed
    engineIndex: {
      type: String,
      required: true,
    },
    // The collections of the engine-index
    collections: {
      type: Array,
      required: true,
    },
    // The settings, passed to the widget
    editedWidgetSettings: {
      type: Object,
      required: false,
      default: () => EMPTY_WIDGET_SETTINGS,
    },
  },

It is a good practice to define the shape of the widget settings object in an empty-state constant, like the following one:

Copied to clipboard!

const EMPTY_WIDGET_SETTINGS = {
  collection: null,
  fields: [],
  query: {
    body: null,
  },
};

Example:

Copied to clipboard!

<template>
  <div class="text-left" />
</template>

<script>
export default {
  name: 'DemoWidgetForm',
  components: {},
  props: {},

  data() {
    return {};
  },

  computed: {},

  async mounted() {},

  async destroyed() {},

  methods: {},
};
</script>

<style lang="scss"></style>

Pass data from the Form to the Widget #

The Form should emit an change event containing the widget settings object when a setting is modified by the form.

The Dashboard Builder will then pass the updated settings object to the Widget component in the widgetSettings props.

The definition #

Once you have created your widget and form compoenents, you can define the custom widget as follows

Copied to clipboard!

import DemoWidget from "./widgets/demo/DemoWidget.vue";
import DemoWidgetForm from "./widgets/demo/DemoWidgetForm.vue";

const demoWidgetDef = {
  name: "demo",
  label: "My super custom widget",
  component: DemoWidget,
  formComponent: DemoWidgetForm,
};