README.md

node-red-contrib-mdashboard

Important: Please note that I can no longer spare time to work on this project. If you are interested in taking over, please mail me at umasudhanp[at]gmail and i will outline next steps.

Note that this is not the official node-red-dashboard. This is a fork which solves a very specific requirement- widget state is emitted only to the socket origin that caused the change. For example, if two users have the same dashboard open and one user types into a text input, the other user will not get the text update. This works well when a typical web form like behavior is needed- multiple users can use the same dashboard url as a form to submit data back to the flow. This version of the dashboard can be installed along with the original node-red-dashboard- the UI configuration for the two dashboards are distinct and the settings appear in different tabs in the sidebar. Note that this changes the behavior of the original node-red-dashboard - specifically, one user's changes could overwrite another's without them knowing about it. In that sense, this dashboard is multi-user only for input- all dashboard users still share the same backend instance.

Most of the documentation is left as is from the original project as it is applicable to the current project as well.

This module provides a set of nodes in Node-RED to quickly create a live data dashboard.

These nodes require node.js version 8. The last version to support node v6 was 2.9.5.

From version 2.10.0 you can create and install widget nodes like other Node-RED nodes. See the Wiki for more information.

For the latest updates see the CHANGELOG.md

Pre-requisites

The Node-RED-Dashboard requires Node-RED to be installed.

Install

To install the stable version use the Menu - Manage palette option and search for node-red-contrib-mdashboard.

Restart your Node-RED instance and you should have UI nodes available in the palette and a new mdashboard tab in the right side panel. The UI interface is available at http://localhost:1880/mui (if the default settings are used).

Settings

The default url for the dashboard is based off your existing Node-RED httpRoot path with /ui added. This can be changed in your Node-RED settings.js file - mui: { path: "mui" },

You can also add your own express middleware to handle requests by using the ui: { middleware: your_function } property in settings.js. For example

ui: { path: 'ui', middleware: function (req, res, next) {
            // Do something more interesting here.
            console.log('LOGGED')
            next()
        }
    },

You can also set the dashboard to be read only by ui: { readOnly: true }. This does not stop the user interacting with the dashboard but does ignore all updates coming from the dashboard.

Layout

The dashboard layout should be considered as a grid.

Each group element has a width - by default 6 'units' (a unit is 48px wide by default with a 6px gap).

Each widget in the group also has a width - by default, 'auto' which means it will fill the width of the group it is in, but you can set it to a fixed number of units.

The layout algorithm of the dashboard always tries to place items as high and to the left as they can within their container - this applies to how groups are positioned on the page, as well as how widgets are positioned in a group.

Given a group with width 6, if you add six widgets, each with a width of 2, then they will be laid out in two rows - three widgets in each.

If you add two groups of width 6, as long as your browser window is wide enough, they will sit alongside each other. If you shrink the browser, at some point the second group will shift to be below the first, in a column.

It is advisable to use multiple groups if possible, rather than one big group, so that the page can dynamically resize on smaller screens.

Features

Dashboard sidebar

The widget layout is managed by a mdashboard tab in the sidebar of the Node-RED editor.

Layout

• Tabs - From here you can re-order the tabs, groups and widgets, and add and edit their properties.

• Links - to other web pages can also be added to the menu. They can optionally be opened in an iframe - if allowed by the target page.

Site

• Title - the title of the UI page can be set.

• Options - optionally hide the title bar, and allow swiping sideways between tabs on a touch screen. You can also set whether the template uses the selected theme or uses the underlying Angular Material theme. You can also choose to use the Angular Material theme everywhere.

• Date Format - sets the default date format for chart and other labels.

• Sizes - sets the basic geometry of the grid layout in pixels. The width and height of widgets can be set, as can the width of groups. These are the basic definitions of the "units' used elsewhere within the dashboard.

Theme

• Style - the theme and font of the UI is set in the dashboard sidebar. You can select a default Light, Dark or Custom Theme. You cannot have different themes for each tab.

You can also choose to use the basic Angular Material themes instead if you like, either just within any ui_templates or for the whole Dashboard. This will only affect angular components so some of the charts and so on may need extra work.

Note: For users creating their own templates the following CSS variable names are available to help pick up the theme colours.

• --nr-dashboard-pageBackgroundColor
• --nr-dashboard-pageTitlebarBackgroundColor
• --nr-dashboard-groupBackgroundColor
• --nr-dashboard-groupTextColor
• --nr-dashboard-groupBorderColor
• --nr-dashboard-widgetColor
• --nr-dashboard-widgetTextColor
• --nr-dashboard-widgetBgndColor

Widgets

Group labels are optional.

Most widgets can have a label and value - both of these can be specified by properties of the incoming msg if required, and modified by angular filters. For example the label can be set to {{msg.topic}}, or the value could be set to {{value | number:1}}% to round the value to one decimal place and append a % sign.

Each node may parse the msg.payload to make it suitable for display. This converted version is exposed as the variable called value, (see example above).

Any widget can be disabled by passing in a msg.enabled property set to false;. Note: this doesn't stop the widget receiving messages but does stop inputs being active and does re-style the widget.

Most ui widgets can also be configured by using a msg.ui_control message - see config-fields.md for futher details.

• Audio out - a widget that will let you play audio (wav or mp3) or send Text to Speech (TTS) to the client.

• Button - the icon can be set using either Material or fa-icons - the colour and background colour may also be set. If the widget is sized to 1 wide the icon has precedence.

• Chart - has both line, bar and pie chart modes. Also the X-Axis labels can be customised using a date formatter string. See this document for more information on the chart data formats accepted.

• Colour Picker - a colour picker widget.

• Date Picker - a date picker widget. The displayed Date format can be specified in the Site tab using moment.js formatting.

• Dropdown - a dropdown select widget has been added. Multiple label, value pairs can be specified. The choices can also be set via msg.options containing an array of objects. If just text then the value will be the same as the label, otherwise you can specify both by using an object of "label":"value" pairs :

  [ "Choice 1", "Choice 2", {"Choice 3": 3} ]
  

  Setting msg.payload will pre-select the value in the dropdown.

• Form - a widget that can be composed of several sub-widgets. When submitted all values are submitted as a single message.

• Gauge - has 4 modes - standard (simple gauge), donut (complete 360°), compass, and wave. You can also specify the colour range of the standard and donut gauges.

• Notification - creates alerts to the user - can either be a toast popup, or a dismissable alert box. The alert may be targeted to a single user.

• Numeric - a Numeric input widget with up/down buttons.

• Slider - a simple horizontal slider, with variable step size.

• Switch - can also set two icons and/or colours depending on state.

• Template - the template node allows the user to specify and create their own widgets within the framework using HTML, Javascript. This is an Angular.js widget. You may also use this to override the built in CSS styles.

• Text - A read only widget, the layout of the label, and value can be configured.

• Text input - text input box, with optional label, can also support password, email and colour modes.

• UI-Control - allows some dynamic control of the dashboard. Sending a msg.payload of the tab number (from 0) or tab_name will switch to that tab. Tabs can be enabled/disabled/hide/show via msg like {"tabs":{"hide":["tab_name_with_underscores"],"show":["another_tab_name"],"disable":["unused_tab_name"]}}. Groups can be hidden and made visible via a msg like {"group":{"hide":["tab_name_group_name_with_underscores"],"show":["tab_name_another_group"],"focus":true}}. Outputs a msg.payload for every browser connect and loss, and every tab change. This can be used to trigger other actions like resetting the visibility of tabs and groups.

Tip: The Text widget will accept html - so you can use it together with the fa-icons we already use to create indicator type widgets.

Securing the Dashboard

You can use the httpNodeAuth property in your Node-RED settings.js file to secure the Dashboard as it is created the same way as other HTTP nodes are. The details can be found at the bottom of this page in the docs http://nodered.org/docs/security

Multiple Users

This Dashboard supports multiple individual users- see note at top. If a widget state on a dashboard changes, the event is emitted only to the dashboard from which it originated.

Messages coming from the dashboard do have a msg.socketid, and updates like change of tab, notifications, and audio alerts will be directed only to that session. Delete the msg.sessionid to send to all sessions.