Screens
A screen is a process graphic bound to live tags: a canvas of widgets that show values, change color with state, and let an operator send commands. Screens are built in the dashboard's editor and run in the dashboard or in a full-window viewer. This section is for engineers who build screens and for operators who use them.
The REST API calls a screen a view: routes are under /api/v1/views. The dashboard says screen everywhere.
What a screen is
A screen is a named document stored by the gateway, in a folder, with:
- metadata: width and height in pixels, background, color scheme, how it fits the viewer, what it is used as (operator screen, faceplate popup or template), its layers, its parameters, and its own
open,closeandtimerevent actions; - components: widgets with a position, size, z-order, an optional parent container (coordinate or flex), a name, and a configuration holding the tag path, bindings, style, visibility rule and events.
The gateway validates component types and the container tree on save and otherwise treats the document as opaque, so a newer dashboard can add fields without a gateway change. Saves are versioned by updatedAt; a save from an older version is refused and the editor asks whose version stands.
How screens relate to the rest of the gateway
| With | How |
|---|---|
| Tags | Every visible property can be a static value, a tag binding or an expression over tag values. The viewer subscribes to each referenced tag over /sync and redraws as values arrive. Write actions and input widgets write tags, which needs the operator role. |
| Tag types | A screen declares parameters, optionally typed to a tag type, and uses {param}.member in its paths. A template or faceplate is then bound to one instance by passing the instance's path. |
| Alarms | The viewer shows an alarm strip with every active or acknowledged alarm above the screen. The Alarm summary widget lists alarms, optionally only those under one tag path. |
| Scripts | A widget event or a screen event can run a script on the gateway. The script is stored with the screen; the viewer sends only its address, and the gateway runs it sandboxed with the session's identity and returns directives (toast, navigate, open popup, open URL). |
| History and replay | The trend widget reads history for its time range; a sparkline only accumulates the values it receives while shown. During a replay, screens show the replayed values and refuse writes. |
| Users and roles | Viewers watch; operators write; engineers and administrators edit. Start screens can be limited to roles for menus, but any signed-in user can open any screen by name. |
Pages in this section
- Screen designer: the editor, its panels and canvas, bindings, visibility, events and actions, preview, saving and conflicts, and the Screens list.
- Widgets: every widget type and its settings.
- Start screens: named entry points, the gateway default, groups, roles, each user's own choice, and why there are no projects.
- Running screens: the viewer inside the dashboard and the full-window app view, navigation, popups, roles, connection loss and replay.
- Templates and popups: embedding one screen in another with parameters, faceplates bound to a tag type instance, popups and the compact field widget.
API
| Route | Role | What |
|---|---|---|
GET /api/v1/views | viewer | List screens, newest first; ?withBody=true includes components. |
GET /api/v1/views/{id} | viewer | One screen with components. |
POST /api/v1/views | engineer | Create: name, description, meta (JSON string), folder. |
PATCH /api/v1/views/{id} | engineer | Rename, describe, move or change metadata. |
PUT /api/v1/views/{id} | engineer | Save name, metadata and components in one step with baseUpdatedAt; 409 on conflict unless force. |
PUT /api/v1/views/{id}/components | engineer | Replace the components only. |
DELETE /api/v1/views/{id} | engineer | Delete. |
GET, POST /api/v1/views/folders | viewer, engineer | List or create folders. |
POST, DELETE /api/v1/views/{id}/presence | engineer | Report that the editor is open; learn who else has it open. |
Details and payloads are in the Screens API; start screens have their own routes under /api/v1/start-screens, listed in Start screens.