Binding widgets to tags

A widget knows nothing about the database. It knows exactly one tag — and it draws what that tag returns.

The binding survives a rename

What is stored is the tag’s stable id, never its path. Rename KPI.Availability and the widget keeps working; the current path is resolved on every call and shown above the tile.

How a result row becomes a value

A query tag returns result rows. From them a widget reads:

• a number, or a number as text → that is the value;
• an array of rows → the configured value column of the first row, otherwise its first numeric column.

For charts and tables you also set which column carries the label and which ones form the series, stacks, groups or sums.

Parameters: where it usually goes wrong

A tag can declare named parameters — from, to, line. Each one is filled in exactly one of three ways:

Source	When
Board filter	when a filter widget on this board sets a value of the same name
Fixed value	when you pin it in the widget
— not at all	then it is not knowable for the data layer

The third case is the one that matters: a single unfilled parameter degrades the whole read to uncertain. The setup dialog names, per parameter, where it comes from, so this does not turn up later as an unexplained badge on a tile.

How a filter works

A filter widget writes its value onto a memory tag, for example Plant.Filter.Line. The dependent widgets follow because their own tag has a parameter bound to that tag; the refetch is triggered by the data layer itself.

The period filter writes start and end onto two tags and thereby fills the parameters from and to. Offered are Today, This shift, 7 days, 30 days and Custom; Week and Month can be configured in as well.

Mind the difference: 7 days and 30 days are rolling windows, while Week and Month start at the Monday and at the first of the month. On the second day of a month, “the last 30 days” and “this month” differ by a factor of fifteen.

If a filter points at a path where no tag exists, the dialog says so at once.

When a widget refreshes

Two ways, and the difference is deliberate.

When a tag a widget shows directly changes, the new value appears at once — the plant announces the change, and only the widgets it concerns fetch it.

A widget bound to an evaluation does not hang on a single tag but on a whole table: “elements today” counts rows that arrive every few seconds. Nobody announces a change for those, so they fetch their value themselves, every ten seconds.

That is why a counter sometimes trails by a few seconds while the status line beside it switches immediately. Both are right: a daily figure does not become wrong for being ten seconds old — a line that just stopped does.

The instant the shown value was true is on the widget, as as of.

What the widget says about quality

Shown	Meaning
uncertain	a parameter is unfilled, or the source is not set up yet
faulted	the source reported, but the value is not usable
denied	you are not allowed to see this value
as of	the moment the shown value held

These sit on the widget deliberately, and not only in a log: a figure whose provenance is unclear must be open about it.