Widgets

This page lists every widget you can place on a screen (the API calls a screen a view), with its properties, the tags it binds to, the events it fires and what it does for a role that cannot write. It is for the engineer building screens in the designer.

What every widget shares

A screen is a list of components. Each component has a type (the widget), a position and size, and a config object that holds everything in the tables below. The designer's right panel edits them; the names in bold are the panel labels, the names in code are the keys stored in the screen document.

Layout

The Layout panel is the same for all widgets:

Field	Meaning
X, Y, W, H	Position and size. Inside a Container each can be in px or % of the container.
Rotation °	0 to 359.
Z-index	Stacking order.
Name	Unique on the screen. New widgets are named after their type and a counter (label1); ISA-style prefixes count from 101 (FI-101, L-101). F2 renames.
Locked	The designer does not move or resize it.
Grow, Shrink, Basis, Align self	Only for children of a Flex container.

Binding to tags

Most widgets have one primary tag: Tag path (tagPath). The gateway's live value for that path drives the widget. A label without a tag path uses the tag its Text is bound to.

Many properties are bindable: a static value, a tag binding or an expression.

Form	Stored as	Behavior
Static	the value	Used as is.
Tag	{ "_b": "tag", "path": "site.pump1.speed" }	The live value of that tag.
Expression	{ "_b": "expr", "code": "tag('a.b') * 2" }	JavaScript run in the browser with tag(path) (a tag's value), tags (every subscribed value) and val (the primary tag's value). Code that contains return runs as a function body. An error falls back to the property's default. Tag paths written literally as tag("…") are subscribed.

Inside a template, {param} in any string, tag path or expression is replaced by the instance's parameter value. See Templates and popups.

Style

The Style panel applies to every widget that does not hide it (the process widgets below say when they do). Background, Color, Font Size, Border Radius, Border Width, Border Color and Padding are bindable. Font Weight (default 500), Align (left), Line Height, Letter Spacing and Opacity % are static. The font size default is 14.

Transform

The Transform panel changes the primary value before the widget sees it:

Field	Key	Meaning
Scale	transform.scale	Multiplies a numeric value.
Offset	transform.offset	Added after the scale.
Clamp Min, Clamp Max	transform.clampMin, transform.clampMax	Limits applied after the offset.
Invert	transform.invert	Flips a boolean, or swaps 0 and 1.
Format string	transform.formatStr	Text shown for the value, with {v} replaced by the gateway's formatted value, for example {v}°C.

A value that is not a number passes through untouched.

States

The States panel is a list of rules, each with a comparison (eq, neq, gt, gte, lt, lte), a value, a color and an optional label. The first rule that matches the primary value wins. Label, Indicator and Multistate use it; widgets that hide the panel ignore it.

Visibility

Show when compares the primary value: Always, = equals, ≠ not equals, > greater than, ≥ greater or equal, < less than, ≤ less or equal, against Value. In the designer a hidden widget is drawn as a dashed box that says hidden; at runtime it renders nothing.

The screen document also accepts showWhen.expr, an expression that keeps the widget shown while it is truthy; an expression that throws (a tag with no value yet) hides it. The panel has no field for it.

Tooltip and quality dot

Widgets whose panel has a generic Component section also get Tooltip (bindable hover text) and Show quality dot. The dot sits in the bottom-right corner: green when the tag's quality starts with good, red when it starts with bad, yellow otherwise. Hovering it shows Quality: ….

How quality is shown

A live value has one of five states: good, uncertain, bad (the gateway cannot vouch for the reading), stale (the browser's /sync link dropped, so this is the last value received) or no data (nothing received yet).

• Widgets marked handles quality below draw their own treatment: the figure becomes ----, the box is hatched or dashed, and a mark says BAD, STALE, NO DATA or UNCERTAIN with the gateway's detail on hover.
• Every other widget with a primary tag is struck out by the runtime when the value is bad, stale or missing: a hatched, dashed overlay with the same mark. In the designer nothing is struck out.

Events and actions

The Events panel lists the events a widget fires: On click (click) and On value change (valueChange). Each holds an ordered list of actions. An action can carry a then list that runs after it.

Action	Key	What it does
Write tag	writeTag	Writes value to tag. An empty value writes 1; true/false become booleans; a number becomes a number; anything else is written as text.
Toggle tag	toggleTag	Reads the tag; true, 1, "1" and "true" count as on. Writes the opposite boolean, or 0/1 for a numeric tag.
Navigate	navigate	Opens a screen by screenId or name, passing params. See Start screens.
Open popup	openPopup	Opens a screen as a popup with params, width, height and modal. See Templates and popups.
Open URL	openUrl	Opens url, in a new tab when newTab is set.
Set variable	setVar	Writes value to the variable name. Variables are tags; the gateway resolves their scope.
Confirm	confirm	Asks message (default Are you sure?). A No stops the rest of the list, not only this action's then chain.
Script (server)	script	Runs code on the gateway in the sandbox. The browser only sends the script's address (screen, component, event, index); the gateway loads the stored source. The script can return toast, navigate, openPopup and openUrl directives. Errors are shown as a toast. See Screen scripts.

{param} in a tag or name is substituted from template parameters. Events only fire at runtime, never in the designer. For most widgets the click lands on the whole widget box, which also answers Enter and Space on the keyboard. For Button and Command, configured click actions replace the widget's own write. valueChange fires right after the widget's own write.

Screens also have their own open, close and timer events (timerMs, default 5000 ms); they are covered in Screen scripts.

Roles

A role can write when it is operator or higher (see Users and roles). What a role cannot do is hidden rather than disabled:

• A Button or Command whose click writes a tag (or has no actions, so it would write) is not rendered for a role that cannot write. A button that only navigates or opens a popup stays.
• Toggle, Text Input, Slider, Dropdown, Value field and Setpoint stay visible as displays and ignore clicks.
• Action lists that contain a write, a toggle, a variable set or a script do not run for a role that cannot write. Navigation and popups still do.
• A write attempted anyway is refused with Your role can read this value but not change it.

In the designer's preview, writes are not sent; a toast says what would have been written.

Display

Label

Static or tag-bound text with an optional unit. Default size 220×70.

Property	Type	Default	Meaning
Text text	bindable text	""	What is shown. Empty shows the primary tag's formatted value, or Label.
Unit unit	bindable text	""	Small text under the value.

Binds tagPath, or the tag its Text is bound to. A matching States rule recolors the text. Fires click.

Text

Multi-line paragraph with the full style panel. Default 320×100, font size 14, line height 1.6.

Property	Type	Default	Meaning
Text text	bindable text	""	The paragraph. Empty shows the primary value; in the designer the placeholder Text block.
Vertical align valign	top, center, bottom	top	Where the text sits in the box.
wrap	boolean	wraps	false keeps one line, cut with an ellipsis. The panel has no field for it.

Fires click.

Live value

A value and its unit that cannot look current when it is not: a bad or lost value is replaced by ---- and a word. Default 136×56. Handles quality; needs a tag; the States panel is hidden.

Property	Type	Default	Meaning
Tag path tagPath	tag path	""	The value.
Label text	bindable text	""	Small caption above the figure.
Unit unit	bindable text	""	Shown after the figure.
Decimals decimals	bindable number	1	0 to 6.
Alarm limits limits	hh, h, l, ll	none	At or beyond H/L the figure turns yellow with an H or L mark; at or beyond HH/LL red with HH or LL.

Font size comes from Style (default 22). When the value is lost the last figure is kept as small struck-out text. Fires click.

Numeric

Large monospaced readout. Default 180×90, font size 28, weight 700.

Property	Type	Default	Meaning
Tag path tagPath	tag path	""	The value.
Unit unit	bindable text	""	Under the figure.
Decimals decimals	bindable number	2	Fixed decimals.

Shows — while there is no value. Fires click.

Indicator

A dot whose color and caption follow the States rules. Default 160×90.

Property	Type	Default	Meaning
Tag path tagPath	tag path	""	The value the rules test.
States states	rules	[]	The matching rule gives the dot its color and the caption its label.

With no match the dot is grey and the caption is the formatted value. Fires click.

LED

Boolean lamp. Default 64×64.

Property	Type	Default	Meaning
Tag path tagPath	tag path	""	Lit when truthy. 0, "0" and "false" are off.
On Color onColor	color	#10b981	Lit color, with a glow.
Off Color offColor	color	#475569	Unlit color.

Fires click.

Status indicator

One equipment state as a glyph and a word, for equipment that is not drawn or for a status list. Default 112×32. In the palette under Instruments. Handles quality; needs a tag; Style, Transform and States are hidden.

Property	Type	Default	Meaning
State tag tagPath	tag path	""	The value mapped to a state.
State map stateMap	rules	0 stopped, 1 running, 2 fault, 3 manual	Each rule compares the value and names a state: running, stopped, fault or manual. Booleans follow 0 and 1. Words such as running, on, open, stopped, off, closed, fault, tripped, manual, local map without rules.
Label text	bindable text	""	Caption above the word.
Word when running wordRunning	text	RUN	For example OPEN for a valve.
Word when stopped wordStopped	text	STOP

Fault shows red, manual blue. A value with bad quality or a dropped link shows NO COMMS; a value the map has no meaning for shows UNKNOWN, both grey and dashed. Without a tag the word is NOT BOUND. Fires click.

Multistate

A filled badge whose background and label follow the States rules. Default 160×80.

Property	Type	Default	Meaning
Tag path tagPath	tag path	""	The value the rules test.
States states	rules	[]	Matching rule sets the background color and the label.

Without a match the background is the style background (or grey) and the label the formatted value. Fires click.

Clock

Wall clock from the browser's time, updated every second. Default 200×60, font size 28, weight 700. No tag.

Property	Type	Default	Meaning
Time Format text	text	HH:mm:ss	Tokens HH, mm, ss, DD, MM, YYYY, each replaced once.

Fires click.

Header

Section heading. Default 320×48, font size 20, weight 700.

Property	Type	Default	Meaning
Text text	bindable text	""	Shows Header when empty.

Fires click.

Image

An image from a URL. Default 200×140. In the palette under Decor.

Property	Type	Default	Meaning
Image URL src	bindable text	""	Without it a dashed Image placeholder is shown.
alt	bindable text	""	Alternative text. No panel field.
fit	contain, cover, fill	contain	How the image fills the box. No panel field.

Fires click.

Bit map

A whole-number status word as two rows of lamps, one per bit: the high half on top, highest bit first in each row. Default 120×40.

Property	Type	Default	Meaning
Tag path tagPath	tag path	""	The word. A value that is not a whole number lights nothing.
Bits bitCount	8, 16, 32	16	Width of the word.
On Color onColor	color	#8F83F5	Lit bit.
Off Color offColor	color	#6B6B7A	Ring of an unlit bit.

Hovering a lamp shows Bit n: on or off. Fires click.

Input

Button

Push button. Default 140×56.

Property	Type	Default	Meaning
Tag path tagPath	tag path	""	Written on click.
Text text	bindable text	""	Caption; Button when empty.
Write Value writeValue	bindable text	""	Written as given; empty writes 1.

When On click has actions they run instead of the write. Fires click. Not rendered for a role that cannot write unless its actions do not write.

Command

A button that names its consequence and confirms before it sends. Default 136×36. In the palette under Controls. Handles quality; needs a tag; Style, Transform and States are hidden.

Property	Type	Default	Meaning
Name the consequence text	bindable text	""	Caption, for example Start pump 3. Shows Name this command until set.
Writes to tag tagPath	tag path	""	Written on click.
Value to write writeValue	bindable text	1	Coerced like an action value: true/false, numbers, else text.
Kind commandStyle	normal, stop	normal	Stop or trip gives a red outline and a destructive confirm button.
Ask before sending confirm	boolean	true	Shows a dialog first.
Question confirmMessage	text	the caption plus ?	Title of the dialog. Its body says Writes <value> to <tag>.

While /sync is disconnected the button is disabled and says No connection: this command can't be sent. On click actions replace the write. Fires click. A role that cannot write never sees it.

Toggle

On/off switch. Default 170×64.

Property	Type	Default	Meaning
Tag path tagPath	tag path	""	Read for the position; on writes 0, off writes 1.
text	bindable text	""	Caption beside the switch; Toggle when empty. No panel field.
onColor	color	theme primary	Track color when on. No panel field.

Truthiness as for LED. Fires click and valueChange. Read-only for a role that cannot write.

Text Input

Free-text field. Default 200×56.

Property	Type	Default	Meaning
Tag path tagPath	tag path	""	Written with the typed text on Enter.
text	bindable text	""	Placeholder; value when empty. No panel field.

The field starts with the current formatted value. Fires valueChange. Read-only for a role that cannot write.

Setpoint

Numeric entry with limits and units. Out-of-range input is refused, not clamped. Default 136×56. In the palette under Controls. Handles quality; needs a tag; Style, Transform and States are hidden.

Property	Type	Default	Meaning
Setpoint tag tagPath	tag path	""	Read and written.
Label text	bindable text	""	Caption above the value.
Unit unit	bindable text	""	After the value and in messages.
Min, Max min, max	number	0, 100	Allowed range, shown under the value. A value outside gets Minimum is 0 %. or Maximum is 100 %.
Decimals decimals	bindable number	1	For the displayed figure.
Ask before changing confirm	boolean	false	Dialog Change <label> to <value>? with the current value.

Click the value to type; Enter commits, Escape cancels; a comma is accepted as the decimal separator. Editing needs a role that can write, a connected /sync link and a value that is not lost; otherwise the tooltip says why. Without a tag the commit shows This setpoint has no tag to write to. Fires valueChange. Read-only for a role that cannot write.

Value field

A compact value box for dense engineering pages, read-only or editable. Default 80×22, right-aligned, font size 12, 1 px border. Handles quality; needs a tag.

Property	Type	Default	Meaning
Tag path tagPath	tag path	""	Read and, when editable, written.
Unit unit	bindable text	""	After the figure.
Decimals decimals	bindable number	1	Decimals, or digit width for hexadecimal.
Shown as format	number, duration, hex	number	Time shows milliseconds as 20:00 or 1:30:00 and accepts 20:00, 1:30:00 or seconds. Hexadecimal shows the word upper-case, padded to Decimals digits.
Can be changed here editable	boolean	false	A click opens an entry that checks Min/Max before writing.
Min, Max min, max	number	none	Limits for the entry; the tooltip lists them as Allowed: 0 to 100.

Editing needs a role that can write, a connected link, a value that is not lost and a tag. Enter commits; Escape or leaving the field cancels. A lost value is ----, struck out and hatched. A read-only field is not a button, so a click passes to whatever it sits in. Fires valueChange.

Slider

Range slider. Default 240×60.

Property	Type	Default	Meaning
Tag path tagPath	tag path	""	Written with the number on every change.
Decimals decimals	bindable number	0	For the figure above the slider.
Min, Max min, max	bindable number	0, 100	Range.
Discrete steps (integer) step	boolean	false	Step 1; otherwise a hundredth of the range.

Fires valueChange. Read-only for a role that cannot write.

Dropdown

Select list. Default 180×48.

Property	Type	Default	Meaning
Tag path tagPath	tag path	""	Written with the chosen option's value (text).
Options options	list of label and value	[]	Shows No options when empty.

The selected entry follows the tag's formatted value. Fires valueChange. Read-only for a role that cannot write.

Charts and meters

Trend

Multi-pen trend with a range selector, a crosshair that reads every pen at one instant and one scale per pen. Default 480×240. Handles quality; needs pens; Transform and States are hidden.

Property	Type	Default	Meaning
Title text	bindable text	""	Shown in the toolbar.
Default range trendRangeMs	1m, 5m, 15m, 1h, 8h	5m	The range it opens on; the operator can switch.
Pens pens	list	[]	Each pen has a tag path, a Label and a color (empty takes the pen's default). Add pen stops at three; Allow one more raises the limit (maxPens) by one. A pen with min and max in the document has a fixed scale; otherwise it is auto-ranged.

History is loaded over /sync (up to 600 points per pen for the visible range) and live values extend it; the line steps, so a value holds until the next sample, and a bad reading breaks the line. Default pens differ in color and dash. Notices: No pens yet, No history in this range, No connection: history is unavailable, Trend paused: connection lost, History is catching up and History is cut off: choose a shorter range. During a replay the chart ends at the replayed moment. Fires click.

Sparkline

A rolling line of the values received while the screen is open. It does not load history. Default 240×100.

Property	Type	Default	Meaning
Tag path tagPath	tag path	""	The value.
samples	bindable number	60	How many values are kept. No panel field.

Scaled to the min and max of the kept values. Shows Waiting… until a value arrives, No tag when unbound. Fires click.

Bar

Fill bar with range and thresholds. Default 260×80.

Property	Type	Default	Meaning
Tag path tagPath	tag path	""	The value.
Unit unit	bindable text	""	After the figures.
Decimals decimals	bindable number	1
Min, Max min, max	bindable number	0, 100	Range; the fill is clamped.
Vertical orientation vertical	boolean	false
Thresholds thresholds	list of value and color	none	The highest threshold at or below the value gives the fill color.

Fires click.

Analog indicator

ISA-101 moving analog indicator: a grey scale with a lighter normal band, limit marks and a moving pointer. Color appears only once a limit is crossed. Default 96×200. Handles quality; needs a tag; Style, Transform and States are hidden.

Property	Type	Default	Meaning
Tag path tagPath	tag path	""	The value.
Label text	bindable text	""	Caption above the figure.
Unit unit	bindable text	""
Min, Max min, max	bindable number	0, 100	Scale ends.
Decimals decimals	bindable number	1
Vertical vertical	boolean	true
Alarm limits limits	hh, h, l, ll	none	Marks on the scale (yellow for H/L, red for HH/LL). The normal band runs from L (or LL) to H (or HH).
Setpoint tag (optional) setpointTagPath	tag path	none	Draws a hollow setpoint mark. setpoint (bindable number) does the same from the document.

A lost value hatches the scale, shows ---- and hides the pointer. Fires click.

Gauge

Radial gauge over a 270° arc with a needle. Default 180×180.

Property	Type	Default	Meaning
Tag path tagPath	tag path	""	The value.
Unit unit	bindable text	""
Decimals decimals	bindable number	1
Min, Max min, max	bindable number	0, 100
Thresholds thresholds	list of value and color	none	Colors the filled arc, as for Bar.

Fires click.

Level gauge

A vessel with a percent fill and the value below it. Default 80×200.

Property	Type	Default	Meaning
Tag path tagPath	tag path	""	The level.
Unit unit	bindable text	""
Decimals decimals	bindable number	1
Min, Max min, max	bindable number	0, 100	0 % and 100 %.
Thresholds thresholds	list of value and color	[]	Fill color; #3b82f6 without a match.

Fires click.

Instrument

ISA-5.1 instrument bubble: function letters over the loop number, with the live value beside it. Default 128×44. New instances are named FI-101, FI-102, … In the palette under Instruments. Handles quality; needs a tag; Style, Transform and States are hidden.

Property	Type	Default	Meaning
Tag path tagPath	tag path	""	The measurement.
Function letters instLetters	text	FI	TI temperature, PI pressure, LI level, FI flow, AI analysis.
Loop number instLoop	text	101	Under the letters. Empty draws the letters alone.
Unit unit	bindable text	""
Decimals decimals	bindable number	1
Alarm limits limits	hh, h, l, ll	none	Colors the bubble outline and the figure, with the zone letters, as for Live value.

A lost value dashes the outline and shows ----. Fires click.

Graphics

All graphics are in the palette under Decor except the pipes, which are under Piping. Stroke and fill colors are the style's Color (style.fg) and Background (style.bg).

Rectangle

A styled box for grouping and backgrounds. Default 240×140, background the theme's card color. No properties of its own; use Style. Fires click.

Ellipse

Default 160×100.

Property	Type	Default	Meaning
Stroke Width strokeWidth	number	2	In screen pixels, whatever the size.
Stroke Color style.fg	color	#64748b
Fill Color style.bg	color	transparent

Fires click.

Line

A diagonal from the bottom-left to the top-right corner of its box. Default 160×80.

Property	Type	Default	Meaning
Stroke Width strokeWidth	number	2
Stroke Color style.fg	color	#64748b
Flip diagonal direction flipX	boolean	false	Top-left to bottom-right instead.

Fires click.

Arrow

A line with arrowheads. Default 160×80.

Property	Type	Default	Meaning
Stroke Width strokeWidth	number	2
Stroke Color style.fg	color	#64748b
Flip diagonal direction flipX	boolean	false
Arrowhead at end arrowEnd	boolean	true
Arrowhead at start arrowStart	boolean	false

Fires click.

Polyline

An open multi-point line. Default 160×80. Double-click it on the canvas to edit the points.

Property	Type	Default	Meaning
Stroke Width strokeWidth	number	2
Stroke Color style.fg	color	#64748b
Fill Color style.bg	color	none	Only used when the path is closed.
Close path (polygon) closePath	boolean	false	Joins the last point to the first.
Points points	list of x, y in 0 to 1 of the box	(0,1) (0.5,0) (1,1)	At least two.

Fires click.

Polyshape

The same renderer as Polyline, closed by default. Default 160×80, fill #64748b33, closePath true. Fires click.

Pipe

A pipe run between ports: no animation, no color for flow. A bound tag makes the line heavier while flowing and dashed when the reading is lost. Default 160×8. New pipes are named L-101, L-102, … Handles quality; Style, Transform and States are hidden; no events.

Property	Type	Default	Meaning
Flow direction flow	forward, reverse, none	forward	Places a chevron at the middle of the longest straight run, or none.
Flowing tag (optional) tagPath	tag path	""	Mapped to a state with State map as for Status indicator.
State map stateMap	rules	0 stopped, 1 running, 2 fault, 3 manual
Route points	list of x, y in 0 to 1 of the box	a horizontal line	Edited with the points editor or the pipe tool (P), which routes between symbol ports.

Running draws the active pipe color at 3 px, fault red, a lost or unknown value grey and dashed, otherwise the pipe color at 2 px. Clicks are picked up along a wide invisible stroke, not the empty bounding box.

Pipe fitting

A junction. Default 24×24. Rotate to orient. Pipes connect to its four sides. Handles quality; Style, Transform and States are hidden; no events.

Property	Type	Default	Meaning
Shape junction	dot, tee, elbow, cross, cap	dot	Junction dot, Tee, Elbow, Cross or End cap.

Layout

Containers draw only their own chrome; their children are laid out by the screen's layout engine. The root of a screen is itself a coord or flex container with a sizing of fixed, stretch or scale; see the designer.

Container

Coordinate container: children are positioned absolutely, in px or % of the container, chosen per axis in the child's Layout panel. Default 320×240.

Property	Type	Default	Meaning
Clip overflowing children clip	boolean	true	Hides what spills outside.

Fires click.

Flex container

Children flow in a row or column. Default 320×240.

Property	Type	Default	Meaning
Direction flexDir	row, column	row
Gap gap	number	8	Pixels between children.
Align items alignItems	stretch, start, center, end	stretch	Cross-axis alignment.
Justify content justifyContent	start, center, end, between, around, evenly	start	Main-axis distribution.
Wrap onto multiple lines wrap	boolean	false
Clip overflowing children clip	boolean	true

Each child gets Grow, Shrink, Basis (px, % or auto) and Align self in its own Layout panel. Fires click.

Template

An instance of a template screen with parameter values. Default 240×160. It has its own palette section and no Style, Transform, States, Tooltip or quality fields.

Property	Type	Default	Meaning
Template templateId	template screen	""	Shows No template selected or Template not found until valid.
Parameter values paramValues	one per template parameter	{}	A tag path for a parameter typed to a tag type (UDT), otherwise text.

The template's design size is scaled to the instance's box on each axis. {param} is substituted in the children's strings, tag paths and expressions. Scripts stored on the template screen run with the instance's parameter values. A click on the instance fires its own click unless it landed on a child that has its own action. See Templates and popups.

Tables and alarms

Table

A two-column table of live readings, one row per tag. Default 400×240.

Property	Type	Default	Meaning
Columns columns	list of tag path, label, unit	[]	Each entry is a row: the label (or the path) and the gateway's formatted value with the unit.

The widget subscribes to each tag itself. Shows — for a tag without a value and No columns configured when empty. Fires click.

Alarm summary

The alarms that need attention, most severe first, with acknowledge for operators. Default 640×240. In the palette under Alarms. Handles quality; the States panel is hidden; no events.

Property	Type	Default	Meaning
Only under prefix	tag path	""	Shows alarms whose tag is this path or under it (prefix.…). Empty shows all.

An alarm is listed while it is not cleared or not yet acknowledged. Shelved alarms are left out; the operator finds them on the alarms page. Rows sort by severity, then by the newest activation. With nothing to show it says No alarms are active under <prefix>. See Alarms.