iot-dashboard Documentation
Table of Content
- iot-dashboard Documentation
- Hosting the iot-Dashboard
- Contributing
- Basic Concepts
- Coding Guidelines
- Webpack Analysis
- Configuration
Learn more:
- Getting Started: Write your own plugins
- Architecture Overview
- Plugin API
- Dependency Management
- Security related topics
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
definesDatasources
andWidgets
based onPlugins
that can be arranged in differentLayouts
. It can be imported and exported manually or from a server. -
Layout: A
Layout
belongs to oneDashboard
and defines howWidgets
are arranged. -
Widget: A
Widget
can be arranged inside theLayout
and renders content based on theWidgetType
,WidgetProps
andDatasources
. -
Datasource: A
Datasource
provides data forWidgets
based on theDatasourceType
andDatasourceProps
-
Plugins: Plugins provide the implementations for
Datasources
andWidgets
.
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 thetypings.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.
- Execute:
npm run webpack-profile
- Goto: https://webpack.github.io/analyse/
- Load the generated stats.json
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 viaPOST
request on save. A server can deliver the posted state asdashboard.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