Client script API
Client scripts are JavaScript; all code runs as async, so await can be used anywhere. The editor completes these
names as you type. For when scripts run, see Object and page events.
Tag — signals
| Call | Returns | Meaning |
|---|---|---|
Tag("P101.Speed") | Signal object | Use it like a value in comparisons and arithmetic |
.value | Value | Current value; undefined until the first value has arrived |
.quality | Number | 0 good, 1 gateway communication failure, 2 device communication failure, 3 signal failure, 4 manual |
.state | Text | ok, waiting, invalid, timeout or empty |
.waiting | On/off | The value has not arrived yet |
.unit | Text | Unit of the signal |
.timestamp, .source_time, .device_time, .arrival_time | Time | Times of the value |
.raw_value | Value | Value before scaling |
await Tag("x").read(timeoutMs?) | Value | Waits for a current value; use it for a signal that is not on the page |
await Tag("x").write(v), await Tag.write("x", v) | — | Sends a command (see Writing) |
await Tag.writeMany({ "a": 1, "b": true }) | — | Several commands at once |
setTag(path, value) and getTag(path) are short forms of write and read.
Writing
A write from a client script is an ordinary command of the signed-in user: the server checks the permission, the responsibility area, the limits, the interlocks and the communication, and writes it to the command log.
- A write that is refused, times out or does not read back throws an error; put
await Tag(...).write(...)intry/catch. - From an event script, a write to a field device asks the operator to confirm, and a critical command asks for the reason and a second user, as on the screen, and the result and a lost connection appear as messages on the screen. A page script (trigger) writes without a dialog and without those messages, and a critical command is refused there.
- Nothing is queued: when the connection is down, the write is refused at once.
- An automatic sign-in for watching only cannot write.
UI — screen
| Call | Meaning |
|---|---|
UI.toast(text, type?) | A message at the edge of the screen; type success, info, warning or error |
await UI.confirm(text) | Asks Yes / No; returns true or false |
await UI.prompt(text, { default }) | Asks for a text; returns it or null |
UI.navigate(pageId, params?) | Opens another page |
UI.set(name, property, value), UI.get(name, property) | Changes or reads a property of an object by its name, for example UI.set("Pump1", "fill", "@running") |
UI.getColor(name, variant?) | Value of a project color |
A property set by a script stays until the page is left. Use project color names (@running) rather than raw colors;
with strict color naming on, raw colors are not applied.
In an event script of a popup object, UI.set and UI.get look for the name among the objects of that popup first, then on
the page. On an input box, UI.set(name, "value", x) fills the box once: the operator can type over it, nothing is written to
the signal, and the value is gone when the box closes with its popup. See
Input boxes in a popup.
Alarm and Log
| Call | Meaning |
|---|---|
Alarm.info / warning / error / critical(text) | Shows a message on the screen. It does not create an alarm: use an alarm definition for that. |
Log.debug / info / warn / error(text), console.log / warn / error | Writes to the browser console with the prefix [Script] |
User
| Member | Meaning |
|---|---|
User.id, User.name | The signed-in user (anonymous without sign-in) |
User.role, User.roleIds | Profiles of the user |
The server checks the permissions of every command, so a script cannot send a command the signed-in user may not send.
Maps
Maps.setView(map, lat, lng, zoom?), Maps.fitItems(map, names?), Maps.follow(map, item | null),
Maps.gotoBookmark(map, name), Maps.getView(map) and Maps.reset(map) control a map object by its name. If the map
is not drawn yet, the call waits up to 10 seconds.
Driver — communication control
await Driver.start(key), Driver.stop(key) and Driver.restart(key) start, stop or restart a driver and return true on
success. The operator always confirms first, and the user needs the Communication control permission.
Other
| Name | Meaning |
|---|---|
await wait(500), await wait("2 sec") | Waits; a number is milliseconds, a text may be 500ms, 2 sec, 1 min |
globals | An object shared by the scripts of the open page and its event scripts; lost when the page is reloaded |
modals.open(name, { data, onConfirm, onCancel }), modals.close(name?), modals.closeAll() | Opens and closes popups |
page.name, page.widgets(), page.widget(name) | The open page and its objects |
math | JavaScript Math |
import / export | Between library files: named, default and namespace imports |
Standard JavaScript (JSON, Date, Map, Promise, setTimeout…) is available. window, document, fetch,
localStorage and similar browser interfaces are not.