Skip to content

I
iot-dashboard

Home

Last edited by Tobias Kaupat
Page history

iot-dashboard Documentation

Table of Content

Learn more:

Hosting the iot-Dashboard

If you plan to host an own instance of the iot-dashboard please have a look into our Security page. A documentation on how to setup your own instance on a server might follow in future and will require some additional work on the Dashboard before.

Contributing

All contributions to the core and plugins are very welcome.

To get started with writing code for the Dashboard core you need a good understanding of the Basic Concepts (see below) and follow the Coding Guidelines (see blow). If you want to provide another datasource or visualization in form of a new widget checkout the Plugin Development page.

Basic Concepts

A basic overview of the concepts and ideas behind the Dashboard.

  • Dashboard: A Dashboard defines Datasources and Widgets based on Plugins that can be arranged in different Layouts. It can be imported and exported manually or from a server.
  • Layout: A Layout belongs to one Dashboard and defines how Widgets are arranged.
  • Widget: A Widget can be arranged inside the Layout and renders content based on the WidgetType, WidgetProps and Datasources.
  • Datasource: A Datasource provides data for Widgets based on the DatasourceType and DatasourceProps
  • Plugins: Plugins provide the implementations for Datasources and Widgets.

Coding Guidelines

Eslint and tslint is in place and must be followed to get successful CI builds.

JavaScript should be converted to TypeScript when touched.

New code must be tested, unittests can be provided next to the code as <filename>.test.ts, they will be executed automatically during build. Read the redux guide about writing tests.

Folder Structure

  • Folders should reflect the business domain not Framework structures
  • root - Globally used stuff & new stuff that can not be sorted in yet
  • ui - generic, reusable UI components
  • util - generic, reusable functions that helps in certain situations
  • typings - contains custom typings in case the ones managed by the typings.json are not sufficient
  • Everything else - should match to the Basic Concepts (see ab ove)

File Naming

  • .js / .ts - Business Logic: Actions & Reducers
  • .ui.js / .tsx - React components
  • .test.js / .test.ts - Tests, automatically loaded by gulp inject

Webpack Analysis

Useful to check problems in the Webpack build.

Configuration

When the dashboard starts it loads the state from dashboard.json relativ to the index.html of the dashboard. When no dashboard.json is found, the dashboard starts in developement mode where you can edit everything and persistence happens in local storage.

For a quick start using a custom configuration just export your dashboard and paste the exported json into dashboard.json. next to the index.html. To customize the behaviour (e.g. to save state to a server or disable devMode) just add a new key to the dashboard.json

"config": {
  "devMode": true,
  "persistenceTarget": "/url/to/post/dashboard.json-on-save"
},

Config Keys

You can set several keys in the config object.

  • persistenceTarget: string - If set to "local-storage" all state is saved into local storage of the browser. Else the value is used as URL where data is sent via POST request on save. A server can deliver the posted state as dashboard.json to restore previous state.
  • devMode: true|false - When false, no data is saved and the board is in readOnly mode.
  • auth.username: string - If set, the username is displayed in the header of the board when devMode is enabled.
  • auth.logoutUrl: string - If set a logout button linking the given URL is displayed in devMode.
  • title.text: string - Set the title text in the upper left corner
  • title.url: string - Set the title URL