Appearance
Widgets on Custom Pages
Last updated
Any dashboard widget can be placed on a custom page by writing a <scada-widget> element in the HTML tab:
html
<scada-widget widget="gauge" min="0" max="10000"
bind-value="tag:3/Spindle/Speed"></scada-widget>The editor completes it as you type: <sca offers the element, widget=" lists every widget, and once a widget is chosen the remaining attributes are that widget's settings, with the allowed values for settings that have a fixed list. Choosing a value that hides other settings — a navigation widget with targetType="url" — stops suggesting the ones that no longer apply.
Widgets are drawn in the app views (/custom-pages/<id>), at /view/page/<id>, in the editor's Live Preview and inside a dashboard's Embed Page widget. They are not drawn when the raw /api/custom-pages/<id>/render address is opened directly.
Attributes
| Attribute | Meaning |
|---|---|
widget | Required. The widget type, e.g. value, gauge, chart, status, table, button, progress_bar, machine_status, floorplan, alarm. Unknown: "x" is not a widget. |
title | The widget's title. |
id, class, style | Ordinary HTML attributes for your own layout; not passed to the widget. |
bind-<property> | A live data binding (below). |
| Anything else | A widget setting, named as in its property panel on a dashboard (the setting's key), matched ignoring case. |
The widget fills the element, so give the element (or its container) a size in CSS — a gauge in a zero-height box shows nothing.
How setting values are read
| Setting type | Write it as | Invalid value |
|---|---|---|
| Number | min="0" | min="abc" is not a number. — the widget shows the error instead of rendering |
| Yes/no | true/false, 1/0, yes/no, or the bare attribute name for true | … is not true or false. |
| List of choices | One of the listed values, exactly | … is not valid. Expected: … |
| Color | Hex, with or without #: #ff0000, f00 | … is not a color. Use a hex value such as #ff0000. |
| Structured (rules, value maps, chart pens, form fields…) | JSON in single quotes: valueFormatMap='{"0":"Idle","1":"Running"}' | … is not valid JSON. |
| Pickers (device, dashboard, page, script, workflow…) | The numeric id: deviceId="3" | … should be a numeric id. |
| Text | As written | — |
An attribute that isn't a setting of that widget is not fatal: the widget renders and shows a warning such as "color" is not a setting for the gauge widget. A wrong value, by contrast, stops that widget rendering, so a typo can't leave a plausible-looking but wrong reading.
Live data
bind-* attributes connect a widget property to a source. The property is whatever the widget reads — value for most widgets; some have several. HTML lowercases attribute names. The property is matched ignoring case against the ones the widget is known to read, including a Symbol's element bindings. For any other property with capital letters, write it with hyphens: bind-fill-color binds fillColor.
| Syntax | Meaning |
|---|---|
bind-value="tag:3/Spindle/Speed" | Live tag: device id 3 (must be a whole number), then the tag path. |
bind-value="static:42" | A fixed value. Numbers and true/false are converted; anything else stays text. |
bind-value="expression:…" | An expression, as on dashboards. |
bind-value="influx:…" | A historian query, as on dashboards. |
Errors: "…" is missing a source type. Try tag:<deviceId>/<tagPath>., "…" needs a device id and a tag path, as tag:<deviceId>/<tagPath>., "x" is not a binding type. Use tag, static, expression or influx.
Changing how a value reads
Value-type widgets accept these settings. They change the display only — the stored value, its history and alarms are untouched.
| Attribute | Effect |
|---|---|
format="percent" | The tag holds a fraction — 0.5 reads as 50% |
format="duration" | The tag holds seconds — 8130 reads as 2h 15m 30s |
format="bytes" | 1536 reads as 1.5 KB |
format="number" | Fixed decimals with digit grouping |
format="text" | Never treated as a number |
format="auto" | Default: shown as it always was |
thousands="false" | Turn digit grouping off (number, percent, bytes) |
scale="0.1" | Multiply before displaying, for a PLC reporting tenths |
precision="1" | Decimal places |
unit="RPM" unitPosition="prefix" | The unit, and which side it sits on (suffix default) |
valueFormatMap='{"0":"Idle","1":"Running"}' | Show a state code as words |
html
<scada-widget widget="value" format="percent" precision="1"
bind-value="tag:2/Machine/LoadFraction"></scada-widget>
<scada-widget widget="value" format="duration" scale="0.001"
bind-value="tag:2/Machine/UptimeMs"></scada-widget>A widget that draws the value — a gauge, a progress bar — takes scale but not percent, duration or bytes, because the needle and the label would disagree. Show a fraction on a 0–100 dial with scale="100" unit="%".
Adding widgets from JavaScript
The page is watched for changes, so a <scada-widget> your script adds (or whose attributes it changes) after the page loads is drawn too.
Public pages
On a page marked Public and enabled, the tags in its bind-…="tag:…" attributes are published: they're delivered to viewers who aren't signed in. Only literal attributes in the saved HTML count — an element built by JavaScript doesn't publish its tag. Details in Custom Page Security.
What it does not do
A shortcode draws a widget; it doesn't turn the page into a dashboard. There's no drag-and-drop, grid, or editing from the rendered page — layout is your HTML and CSS. For a grid you can rearrange, build a dashboard.