How to create a widget

Widgets is a client-side entities which knows how exactly interact with the Virtual Devices through the ZAutomation API. Every widget is aware of specific VDev type/subtype metrics and commands and provides human-reachable UI to control VDevs.

Before you make a decision to author your own client-side widget, please take a look at the bundled widgets library named CommonWidgets and try to use one of the bundled widgets. This can save your time and provide your VDev support on other UIs (such as mobile UIs which doesn't use customized widgets at all).

Step 1. Register you custom widget's meta information

// ...part of the BatteryPolling.init() method
this.controller.registerWidgetClass({
    className: "BatteryStatusWidget",
    code: "BatteryPolling/batteryStatus.js",
    mainUI: "BatteryPolling/batteryStatus.html"
});

This code instructs Automation Controller to register a widget which jsvascript part of the code resides in the htdocs/modules/BatteryPolling/batteryStatus.js and widget's main UI template resides in the templates/BatteryPolling/batteryStatus.html.

Javascipt code loaded by the Zautomation UI's setup once, when document ready event is fired by the web-browser.

HTML template is a nunjucks (Javascript port of the famous Jinja2 templating library) template which SHOULD be precompiled before the ZWay server will be started (in case you just added or installed that template folder and files).

Installing nunjucks globally (node.js SHOULD be installed prior)

$ [sudo] npm install -g nunjucks

Precompiling client-side templates

$ cd /path/to/automationFolder
$ nunjucks-precompile ./templates/ > ./htdocs/_templates.js

This will create (or update) /htdocs/_templates.js file which contains all precompiled client-side templates (including CommonWidgets library templates).

Existance of the /htdocs/_templates.js is vital to the ZAutomation web UI, so there is a bundled version of it in every fresh install of the ZWay server and ZAutomation engine.

Step 2. Define widget's class

function BatteryStatusWidget (parentElement, deviceId) { BatteryStatusWidget.super_.apply(this, arguments); }

inherits(BatteryStatusWidget, AbstractWidget);

Step 3. Override updateUI() method

BatteryStatusWidget.prototype.updateWidgetUI = function () { this.elem.innerHTML = nunjucks.env.render("BatteryPolling/batteryStatus.html", { vDev: this.device.id, widgetTitle: this.widgetTitle, reports: this.metrics.reports }); }

Almost everything you should do to override a widget's updateUI() method is to set proper object as a second arguments of the template's render call.

This settings dictionary directly used in the template to render your widget's UI.

Step 4. Check the widget in the UI

At the loading time, ZAutomation web UI will automatically scan vdevs and instantiate a widget for every vdev which defines widgetClass property. This property SHOULD contain string referencing to the widget's class name. If this coincidence found, widget will be instantiated and rendered at the UI's dashboard.

Client-side javascript code maintains event bus and notifies widget to redraw itself if one or more metrics were changed in a VDev to which particular widget is linked.