Templates and popups

This page covers the three ways a screen is reused rather than navigated to: embedded as a template widget, opened as a popup, and the faceplate pattern that combines both with a tag type (UDT). It is for engineers building a library of symbols and faceplates.

Screen parameters

Any screen can declare parameters in the Parameters section of its settings (nothing selected in the editor). A parameter has a name and, optionally, a tag type path such as @types.Motors.Motor. On that screen, write {name} inside tag paths: {motor}.speed, {motor}.cmd.start. The tag path input completes {motor}. to the type's members.

At run time the parameter values are substituted, in this order of reach:

• in every tag path (tagPath, level and setpoint paths, trend pens, table columns),
• in tag bindings ({"_b":"tag","path":"{motor}.speed"}) and in expression code,
• in the tag of a Write tag, Toggle tag or Set variable action,
• in the tag paths a server-side script reads or writes through {param}; never in the script's source itself.

A {name} with no value stays as written, which shows up as a broken reference. A screen with parameters is a part: it is left out of the viewer's navigation and cannot be pinned as a start screen.

The template widget

The Template widget (group Templates) embeds one screen in another.

1. Place a Template widget and pick a screen under Template. Every other screen is offered.
2. For each parameter of that screen, a field appears. A parameter typed to a tag type shows an instance picker listing the instances of that type (and of types that extend it); a plain parameter takes free text, normally a tag path.
3. Size the widget. The embedded screen is drawn at its own design size and scaled on each axis to the widget's width and height, so keep the widget's proportions close to the template's.

The widget's configuration is templateId and paramValues: {"templateId":"<id>","paramValues":{"motor":"Plant.Line1.M101"}}. Parameters nest: a template placed inside a template receives the outer instance's values first, then its own.

Scripts on widgets inside a template are stored on the template screen and run with the placing instance's parameter values, so one faceplate script serves every instance. A template whose screen has been deleted shows "Template not found".

Make template

In the editor, select the components that make up a symbol and press Make template in the toolbar. The editor creates a new screen in the Templates folder holding those components (a selected container brings everything inside it). The longest dotted prefix the selection's tag paths share, plant.p101 for plant.p101.state and plant.p101.flow, becomes one parameter named tag, and the paths are rewritten to {tag}.state and {tag}.flow. The selection is replaced with a Template widget whose tag value is that prefix, so the screen keeps showing what it did. Paths that do not share the prefix stay absolute; with no common prefix, the template has no parameter.

Passing a tag type instance

The usual pattern is one parameter typed to a tag type, filled with the path of an instance:

{
  "parameters": [{ "name": "motor", "udtType": "@types.Motors.Motor" }]
}

Inside the template, {motor}.running, {motor}.speed and {motor}.fault resolve against that instance. The instance is passed by path, as a string; nothing is copied. Instances of a type that extends the declared type are accepted as well. Motor type walks through building the type, its instances and a template on top.

Popups

A popup is a screen opened in a movable window over the current screen. Two things open one:

• the Open popup action on a widget event, with the target screen by id or name, optional width, height, modal and parameters;
• a server-side script returning an openPopup directive with the same fields; see Screen scripts.

How a popup behaves:

Aspect	Behavior
Size	The action's width and height; otherwise the target screen's own size; otherwise 640 × 480. A 36 px title bar is added.
Position	Centered in the window on opening (at least 8 px from the edges). The title bar drags it; it cannot be dragged above the top of the window.
Title	The screen name, or the value of a parameter named title if one is passed.
Closing	The Close button or Esc. A modal popup dims the screen behind it and also closes when the dimmed area is clicked.
Toggle	Opening a popup that is already open for the same screen and the same parameters closes it instead.
Several	Any number can be open at once; each is its own window.
Content	The screen runs with the passed parameters and the same live data, roles and replay rules as any screen. A Navigate action inside a popup navigates the screen underneath.

In the editor's preview, popups open too, with writes shown as toasts instead of being sent.

The faceplate pattern

A faceplate is a popup bound to one instance of a tag type: a symbol on the overview opens it for its own device.

1. Create a tag type with the members every device of that kind shares (running, speed, cmd.start, cmd.stop, fault), and one instance per device. See Tag types.
2. Create the faceplate screen. Set Used as to Faceplate popup, pick the Faceplate 480 × 360 size or your own, declare a parameter typed to the type, and build it with {param}.member paths: a few Value field widgets, a Command or two, an Alarm summary limited to {param}.
3. Create the symbol as a template screen the same way, with a parameter of the same type, and give its click event an Open popup action whose target is the faceplate, passing {"motor":"{motor}"} so the instance travels along; set modal if the operator must close it before touching the overview.
4. On the overview, place one Template widget per device and pick its instance.

Because the instance is only a path, the same faceplate serves every instance, and a new device is one more instance plus one more template widget.

The field widget

The Value field (field, group Input) is a compact box for dense engineering pages, 80 × 22 px by default. It shows the tag's value with its unit and decimals, right-aligned. Settings:

Setting	Values
Tag	The tag shown, and written to when editable.
Unit, Decimals	Bindable.
Shown as	Number; Time (mm:ss, from milliseconds), which also accepts 20:00, 1:30:00 or seconds when typed; Hexadecimal, decimals digits wide.
Can be changed here	Off: a read-only value that never swallows a click meant for what it sits in. On: a click turns it into an entry; Enter writes, Esc or leaving cancels.
Min, Max	The entry is checked against them before it writes, and the allowed range is shown in the tooltip.

A field can be edited only when the role can write, the connection is up, the tag path is set and the value is not lost. A value whose quality is lost is shown as ----, struck through and hatched, rather than left looking current.

Limits

• Parameters are substituted into strings matching {name} (letters, digits and underscore). There is no default value for a parameter; a missing value stays {name}.
• A template is scaled, not re-laid out: text scales with the widget, and a widget stretched to another aspect ratio distorts its contents.
• A template screen cannot embed itself; a screen is offered as a template to every screen except itself.
• Popups always open centered; their position is not stored.
• The template and the embedded screen share one tag subscription set, so a page with many instances subscribes to every member they reference. The viewer batches redraws at 80 ms.