Dashboard Scripts

The editor allows you to add scripts to each type of dash (except “Group”). A distinction is made between filter scripts, to filter the content of a received message, and output scripts for formatting the content before publishing.

For “Custom Views” the corresponding functionality must be implemented directly in the HTML code (see Custom View).

Filter script

function filterMsg(msg, acc, view) {
  var content = msg.text;
  ...
  return content;
}

Functionality is like Filter scripts for topics. Likewise, the parameter view can be used to access properties of the dash. For example, the text or background color can be changed depending on the received message msg.text.

Example:

view.setTextColor(MQTT.Color.RED);

The individual functions are explained in a separate section.

Output script

function setContent(input, msg, acc, view) {
  var msg.text = input;
  ...
  return msg;
}

input contains the value to be sent (publish). By default it is assigned to the msg.text variable. For example, if the JSON output format is required, the JSON content (type string) must be assigned to the variable msg.txt.

For binary data, assign the corresponding ArrayBuffer object (which contains the binary data to be sent) to msg.raw:

Example:

var buffer = new ArrayBuffer(2);
var dataView = new DataView(buffer);
dataView.setInt8(0, 1); // put 1 in slot 0
dataView.setInt8(1, 127); // put 127 in slot 1
msg.raw = buffer;

msg contains the message to be sent, acc information on the account. See the table “Variables”).

As with the filter scripts, the parameter view can be used to access properties of the dash, for example to reset colors. See this section.

Script error

JavaScript and connection errors (e.g. no network connection during publish()) are indicated in the dash by a warning ().

JavaScript interface

The display of dashes can be dynamically modified using script code.

Filter scripts are executed before they are displayed. If a new message is received, it can be evaluated and the display of the dash icon can be modified depending on the message content (e.g. by setting a different text color).

Access to the properties of the dash (e.g. of a “Button/Switch”) can be obtained by the view parameter, which is passed in the filterMsg() and setContent() functions (see the Filter script/Output skript) sections.

With a “Custom View” type dash, the properties of the dash can be accessed in the HTML code via the global object MQTT.view. If implemented, this can also be done using the onMqttInit(account, view) function (see the Custom View HTML section).

To change e.g. the text color, setTextColor() must be called as follows:

a) in filterMsg(), setContent()

view.setTextColor(MQTT.Color.RED);

b) JavaScript code in the HTML of Custom View

MQTT.view.setTextColor(MQTT.Color.RED);

Properties/Functions

Some properties/functions are only available for certain dashes:

setTextColor(color), getTextColor()
Description: set/read text color
Parameter: color - ARGB color value (see Color constants)
Dashes: Text View, Option List, Progress Bar/Slider

setTextSize(size), getTextSize()
Description: set/read text size
Parameter: size - 0 = System Default, 1 = small, 2 = medium 3 = large
Dashes: Text View, Option List, Progress Bar/Slider

setBackground(color), getBackground()
Description: set/read background color
Parameter: color - ARGB color value (see Color constants)
Dashes: all

setBackgroundImage(resourceName), getBackgroundImage()
Description: set/read background image
Parameter: resourceName internal or external ressource name (image imported by the user). A path “int/” or “user/” can be prefixed (required for name collision; if not fully qualified, an external ressource has priority)
Dashes: TextView, Option List, Progress Bar/Slider, Button/Switch

getSubscribedTopic()
Description: read out topic (sub)
Dashes: all

getPublishedTopic()
Description: read out topic (publish)
Dashes: Text View, Button/Switch, Progress Bar/Slider, Option List

setCtrlColor, getCtrlColor
Description: set/read controller color (foreground image)
Parameter: color – ARGB color value (see Color constants)
Dashes: Button/Switch “On” State, ProgressBar/Slider

setCtrlBackground, getCtrlBackground
Description: set/read controller background color
Parameter: color – ARGB color value (see Color constants)
Dash: Button/Switch “On” State

setCtrlImage, getCtrlImage
Description: set/read controller image
Parameter: resourceName – internal or external ressource name (image imported by the user). A path “int/” or “user/” can be prefixed (required for name collision; if not fully qualified, an external ressource has priority)
Dash: Button/Switch “On” State

setCtrlColorOff, getCtrlColorOff
Description: set/read controller color (foreground color)
Parameter: color – ARGB color value (see Color constants)
Dash: Button/Switch “Off” State

setCtrlBackground,Off getCtrlBackgroundOff
Description: set/read controller background color
Parameter: color – ARGB color value (see Color constants)
Dash: Button/Switch “Off” State

setCtrlImageOff, getCtrlImageOff
Description: set/read controller image
Parameter: resourceName – internal or external ressource name (image imported by the user). A path “int/” or “user/” can be prefixed (required for name collision; if not fully qualified, an external ressource has priority)
Dash: Button/Switch “Off” State

setUserData, getUserData
Description: Buffering user-defined values
Parameter: JavaScript object or value
Explanation: For example, to buffer state variables, historical data (values of the last messages received).
IMPORTANT: The data is not stored permanently, but only for the lifetime of the dash, which ends when the dashboard is left or modified. The size is limited, also not all data types are stored, e.g. objects of the type ArrayBuffer (JSON.stringify() and JSON.parse() are used internally to set and read user data)
Dashes: all

isDialog
Description: Query whether the dash is currently executed in detail view
Explanation: Dashes displayed in the detail view use the data of the corresponding dash in the dashboard, but run as a standalone instance
Dash: Custom View

getHistoricalData
Description: Returns the last messages (up to 100 last messages are retained on the server if the “Provide historical data” option is selected in the dash)
Return value: JavaScript array of messages (sorted in ascending order)
Dash: Custom View

Example:

var data = MQTT.view.getHistoricalData();
for(var i = 0; i < data.length; i++) {
   var msg = data[i];   
}

msg.receivedDate – date (JavaScript Date object)
msg.topic – topic (type string)
msg.text – message content (type string)
msg.raw – binary message content (JavaScript ArrayBuffer object)

getParameters()
Description: Returns a list of parameters (the user can define the Custom View parameter in the dash settings)
Return value: JavaScript array with parameters of the type String
Dash: Custom View

Example:

MQTT.view.getParameters()

More functions and constants

Further functions and constants are available via the global object MQTT.

publish(topic, payload, retain)
Description: Send a message (from the “Custom View” dash)
Parameter: topic (type String), payload (type String, if in text format, or ArrayBuffer for binary data), retain (type Boolean)
Explanation: For application in the “Custom View” dash, if e.g. a “SendButton” element was tapped
Dash: Custom View

Example:

MQTT.publish('demo/test', 'hello world!', false);

Color functions:

MQTT.Color.rgba(r, g, b, a) – Returns the RGB color value from the passed individual values, including alpha channel

MQTT.Color.rgb(r, g, b) – Returns the RGB color value from the passed individual values (100% opaque)

MQTT.Color.red(color) – Returns the red portion of a color

MQTT.Color.green(color) – Returns the green portion of a color

MQTT.Color.blue(color) – Returns the blue portion of a color

Color constants:

MQTT.Color.WHITE

MQTT.Color.LT_GRAY

MQTT.Color.DK_GRAY

MQTT.Color.BLACK

MQTT.Color.TAN

MQTT.Color.YELLOW

MQTT.Color.ORANGE

MQTT.Color.RED

MQTT.Color.BROWN

MQTT.Color.LT_GREEN

MQTT.Color.GREEN

MQTT.Color.PINK

MQTT.Color.PURPLE

MQTT.Color.CYAN

MQTT.Color.LT_BLUE

MQTT.Color.BLUE

MQTT.Color.TRANSPARENT

MQTT.Color.OS_DEFAULT – Standard color of the operating system (according to iOS/Android, dark mode)

MQTT.Color.CLEAR – Resets colored areas (e.g. in “Button/Switch”)

Custom View HTML

Any HTML can be used. However, some things should be considered.

  1. Set default margins (of the browser/WebView) to 0:
  2. <style>
    body {margin: 0; padding: 0;}
    </style>
    
  3. The content to be displayed should always lie within the viewport. At initialization and when changing the window size (after tapping on “Zoom”) a function should be called which adapts the content to the size of the viewport. The viewport sizes can be queried with window.innerWidth and window.innerHeight:
  4. <script>
    function onMqttResize() {
      document.getElementById('visible_area').style.width = window.innerWidth + "px";
      document.getElementById('visible_area').style.height = window.innerHeight + "px";
    }
    
    window.addEventListener('resize', onMqttResize);
    </script>
    
  5. Implement the following functions to receive messages and retrieve information about the current dash:
  6. <script>
    function onMqttInit(account, view) {
      onMqttResize();
      /* implement */
    }
    
    function onMqttMessage(msg) {
      /* implement */
    }
    </script>
    

    Explanation:
    onMqttInit() is called by the app after initialization. account contains information about the current account (see also the table “Variables”). Using view you can access the properties of the dash (see above).

    onMqttMessage() is called by the app whenever a new message has arrived (on initialization the last received message is passed). Of course, a topic must be specified in the dash for this to work.

    msg parameter: see also the table “Variables”.

    Tip:

    Use the “Basic HTML” template ( > Insert > Basic HTML) for the above code.

  7. To send data (via publish), you should implement a click handler, e.g. for a button, and then send the message via the JavaScript interface MQTT.publish():
  8. <button onclick="MQTT.publish('demo/test','Hello world!',false);">Send Hello World!</button>
    
    See also More functions and constants.
  9. Internal and imported images can be referenced in HTML. Use the ressource name as specified under “Manage Images”. For distinction, a path “int/” or “user/” can be prefixed (required for name collision; if not fully qualified, an external ressource has priority).

    Example:

    Using an imported image with the (ressource) name “light_on”:
  10. <img src="light_on">
    
    or
    <img src="user/light_on">
    
  11. Historical data:
    The checkbox “Provide historical data” must be selected. See the section getHistoricalData()