Developers/Graphic libraries

Faceplates and dynamics

Parameterised templates, element catalogue, button actions and per-state dynamics.

3 min read

A faceplate is a template with typed parameters. Its elements use $parameter in the tag field; each instance binds those parameters to project variables.

Template

{
  "width": 320, "height": 180, "background": "#ffffff",
  "parameters": {"running": "bool", "flow": "float", "fault": "bool"},
  "elements": [
    {"id": "body", "kind": "rectangle", "x": 0, "y": 0, "w": 320, "h": 180,
     "color": "#f1f5f9", "stroke_color": "#334155"},
    {"id": "pilot", "kind": "lamp", "x": 16, "y": 16, "w": 40, "h": 40, "tag": "$running"},
    {"id": "flow", "kind": "text", "x": 70, "y": 16, "w": 230, "h": 40,
     "text": "Flow ", "tag": "$flow", "unit": " m³/h", "decimals": 1}
  ]
}

Instance

{"id": "pump1", "kind": "faceplate", "x": 30, "y": 100, "w": 320, "h": 180,
 "template": "pump",
 "bindings": {"running": "Pump1.running", "flow": "Pump1.flow", "fault": "Pump1.fault"}}

bindings must contain exactly every parameter, with leaf variables of the same type.

Element catalogue

kind Specific properties
text text, tag, unit, decimals, font_size, bold, text_align, color, text_color
input Same as text; writable tag
button text, action and the action's fields
lamp bool tag, lamp_colors: {on, off, bad}
bar numeric tag, min, max, color
gauge numeric tag, min, max, gauge_style (dial, semi, thermometer), text, unit, decimals, warning, alarm, color
image source (SVG recommended)
text_list tag, texts [{value, text}], default_text
line / polyline / pipe normalised points, stroke_color, stroke_width, stroke_style, arrows
rectangle / ellipse color, filled, stroke_color, stroke_width

points are [u, v] pairs between 0 and 1 inside the box: X = x + u·w, Y = y + v·h.

Button actions

action Fields Effect
toggle bool tag Inverts the value
set tag, value Writes value
momentary bool tag true on press, false on release
press_release tag, press_value, release_value Two values
screen screen, target_container Navigates (project only)
popup screen, modal Opens a pop-up (project only)
script script Runs Python (project only)

Dynamics

"dynamics": {
  "visible": {"tag": "$visible", "op": "eq", "value": true, "bad": false},
  "enabled": {"tag": "$permit", "op": "eq", "value": true, "bad": false},
  "default": {"color": "#d7e0e9"},
  "states": [
    {"when": {"tag": "$fault", "op": "eq", "value": true}, "style": {"color": "#c64b51", "text": "FAULT"}},
    {"when": {"tag": "$running", "op": "eq", "value": true}, "style": {"color": "#147d75"}}
  ],
  "bad": {"color": "#da982f"},
  "disabled": {"color": "#e0e5eb"},
  "disabled_reason": "Missing permit"
}

Operators: eq, ne for everything; gt, ge, lt, le for numbers only. The first matching state wins. Up to 128 states.

kind Style keys
text, input, button, text_list color, text_color, border_color, text
rectangle, ellipse color, stroke_color
line, polyline, pipe stroke_color
image source
lamp, bar, gauge color

Try it live

The faceplate playground renders a template in the browser and lets you change parameters to watch the dynamics.

Library objects in Studio

The UI calls these templates library objects; the format still uses faceplate. Standard symbols use estandar__<object> references and library://estandar/graficos/<symbol>.svg assets. Buttons and inputs support permission to require a specific permission. Operation validates this field independently of dynamics.enabled. See Libraries and Users and roles.

Faceplates and dynamics · abSCADA