# Dashboards of a model

> The free-form dashboards defined on a model, the unit placeholder their bindings carry, and how each unit opens its own resolved copy.

A **dashboard of a model** is an ordinary dashboard that names its model: it is assembled from the
same components and edited with the same editor as every dashboard on the View page (see
[The dashboard editor](view-editor)), and what makes it a model's is where it lives and what its
bindings name. It is listed under Process > Models > model > Visualization > **Dashboards**, its
address fields offer the model's channels, and it writes a unit placeholder where a single unit
would otherwise be named. One definition serves every unit of the model. Creating, removing and
marking a dashboard needs the **Manage process** permission; editing what is on it needs the
**Edit dashboards** permission of the Dashboard area.

## The Dashboards folder {#the-dashboards-folder}

Selecting the **Dashboards** row opens the folder page: the header ("Operator dashboards defined
on this model. One definition serves every unit: each unit carries a row of its own that opens it
over that unit's bound channels.") and one card per dashboard, with its icon and name. Clicking a
card opens the dashboard; the X on a card removes it. When the model has none, the page says "No
dashboards yet. Add one, then edit it with the dashboard toolbox." The tree lists the dashboards
under the folder by name, and the folder row counts them.

| Command | What it does | Greyed when (situation) | Not drawn when (role) |
| --- | --- | --- | --- |
| **Dashboard** (detail bar, folder selected; right-click **Add dashboard**) | Creates an empty dashboard named `Screen <n>` (the first number no dashboard of this model already uses), saves it and selects it so you can name it where you made it. | Any unit holds a run, or the runtime is stopped. | Without Manage process. |

A new dashboard starts with nothing on it. Its name, description, icon and everything else a
dashboard carries are the editor's to change (see [Dashboard settings](view-settings)); the
Process page carries no field for them.

## The dashboard's page {#the-dashboards-page}

Selecting a dashboard runs it in the content panel, full bleed, with nothing in front of it: this
is the definition itself, drawn on the same canvas every other dashboard is drawn on. Because no
unit is named here, a component bound to one of the model's channels draws its own layout and
reads no value; the editor's address line reads "one point per unit of this model" for such a
binding instead of reporting a missing point. A component bound to a station point (a tag, a
variable) reads it as usual.

An empty dashboard says so instead of standing as a blank strip: "Nothing on this screen yet.
Edit it to place components: their address fields offer this model's channels, and every unit
then reads its own."

The detail bar carries three things for a selected dashboard: **Edit dashboard**, the **Show on
View** switch and, in the danger cluster, **Remove dashboard**.

## Edit dashboard {#edit-dashboard}

**Edit dashboard** hands the body of the Process page to the one dashboard editor of the app,
mounted on this definition: the stage, its hairline and the task rail take the place of the
content panel, and the editor's strip carries **Done editing** ("Finish editing and go back to
viewing this dashboard"), which gives the body back to the content panel running the dashboard as
it now stands. Nothing is committed on the way out: every edit is saved as it is made. The
dashboard's own address (`/d/<id>`) stays a deep link into the editor for whoever arrives with
one.

| Situation | What you see |
| --- | --- |
| Your role lacks Edit dashboards | The verb is not drawn at all: what the role may never press is left out rather than greyed. |
| A unit holds a run | The verb is greyed with "Engineering is locked while a Unit is running". A lock that arrives while you are editing ends the editing mode; coming back once the station is free is your own press. |
| The selection moves off the dashboard, or the role loses the bit | The editing mode ends the same way. |

Deleting the dashboard from inside the editor closes the editor and lands the selection on the
model's Dashboards folder.

### The unit placeholder in bindings {#the-unit-placeholder-in-bindings}

On a model's dashboard, every address field of the editor leads with the model's channels, one
row per channel in the model's channel order, each written as the address of "this channel, on
the unit that opens the screen": `Process.<Model>.{unit}.Channels.<Channel>`. Picking one binds the
channel and leaves the unit to be answered later. The station's own points follow those rows (a
model's dashboard may legitimately read an ambient tag or a shared variable), the list is capped
at 50 suggestions, and the field stays freely typeable. A field that writes (a Button, an Input)
lists only the channels whose role is writable, because which channels a unit can be written
through is the channel's role.

The rows are filtered by the value category the field accepts, exactly as the station's own
points are, so a channel is hidden only where nothing could carry it.

Three tokens are answered when a unit opens the dashboard:

| Token | Where it is written | What it becomes |
| --- | --- | --- |
| `{unit}` | Inside an address, and as the whole value of a component property that binds a unit (the comment timeline's or occurrence list's Unit, for example). | The unit's address segment in an address; the unit's identity in a unit-bound property. Written inside ordinary text (a label, a caption) it is left exactly as it is. |
| `{unit.name}` | Any text: the dashboard's name and description, a component's name or caption, a chart title or series label, any text property. | The unit's display name. |
| `{channel.name:<segment>}` | Any text. The segment is the channel's sanitized address segment, the same key the address beside it uses. | The name the channel carries on that unit: its per-unit alias where the model allows one and the unit set it, the channel's own name otherwise. A segment that names no channel of the model stays as it is. |

While the dashboard is edited on the model, a component whose address still carries `{unit}`
is treated as not bound: it draws nothing and marks nothing, because silence is only real on the
resolved copy.

## How each unit gets its resolved dashboard {#how-each-unit-gets-its-resolved-dashboard}

Under **Operate**, every unit of the model carries one row per dashboard of the model, after its
panel rows. Selecting that row runs the definition as this unit's own:

- The definition is copied and re-identified (fresh identities for the dashboard, its components
  and its connection networks), so two units' copies never share a component identity.
- Every `{unit}` becomes this unit, so each address comes out as the ordinary
  `Process.<Model>.<Unit>.Channels.<Channel>` point and each unit-bound property holds this unit.
  Nothing downstream learns that the definition was abstract: the components read live values,
  the Button and Input components write, and a line chart whose series read this unit draws the
  evaluation bands of the run under way on it, exactly as on any dashboard bound to a unit.
- `{unit.name}` and `{channel.name:...}` become the unit's name and the channel names in force on
  it.

The row wears the stage bar the View page uses: the entry name `Model · Unit · Dashboard`, the
dashboard's icon, **Expand** ("Use the whole window") and **Full screen** ("Full screen (F11)").
There is no Copy and no Edit on it: a unit's row shows a dashboard and never edits it. An empty
dashboard says on the unit's row: "Nothing on this screen yet. It is drawn on the model's
Dashboards row, under Visualization, and what is placed there appears here for every unit."

An edit saved on the model reaches every unit's row: the row holds the model's definition and
resolves it again whenever a fresh instance arrives.

## Show on View {#show-on-view}

**Show on View** is the switch on the detail bar, beside Edit dashboard. It reads the state in
force and its tooltip says what that state does:

| State | Tooltip |
| --- | --- |
| On | "Each unit of this model has an entry for this dashboard in the Visualization list." |
| Off | "This dashboard is opened from the unit, under Operate. Nothing of it stands on the View page." |

Switching it on puts one entry per unit of the model in the View page's Visualization column,
named `Model · Unit · Dashboard` and wearing the dashboard's icon; each entry is the definition
resolved for that unit, the same screen the unit's row under Operate runs. The entries are rows of
that list and not dashboards of the station: they are never reordered, edited or copied there
(Copy is refused on them), though each unit's entry may be filed into the View page's folders on
its own. A model with no units puts nothing on the View page. A dashboard may stand on the View
page in its own right and also be a card of a panel that stands there; both at once is an ordinary
arrangement. What the entries look like is on [Unit panels on View](view-unit-panels).

The switch is not drawn for a role without Manage process. It stays drawn and greyed under the
engineering lock and the stopped runtime, saying which of the two it is. The decision is saved
with the dashboard itself (the same autosave its name takes), so a refused write puts the switch
back.

## A dashboard as a card of a panel {#a-dashboard-as-a-card-of-a-panel}

A panel of the model may draw any of the model's dashboards as one of its cards, at a height
chosen on the panel (120 to 1200 px, 320 by default). A dashboard enters a panel only when you
switch it on there; it starts off. See [Panels](process-panels#the-card-catalogue).

## Remove dashboard {#remove-dashboard}

**Remove dashboard** stands in the detail bar's danger cluster with the dashboard selected, on the
tree's right-click menu, and as the X on the folder page's card. It asks first ("Delete
dashboard": the name, then "This removes the dashboard and everything on it. The addresses they
read stay in Logic."). After the deletion the selection lands on the model's Dashboards folder, an
open editor on that dashboard closes, every panel row that drew it drops that card, and its entries
leave the View page. It needs Manage process and is greyed under the engineering lock and the
stopped runtime.

## What this page does not do {#what-this-page-does-not-do}

- It does not edit the dashboard's content, name or settings: those are the editor's, opened by
  Edit dashboard.
- It does not make a per-unit copy. What a unit shows is resolved from the one definition each
  time; there is nothing to edit per unit, and a dashboard the operator wants to change for one
  station is a second dashboard of the model.
- It does not put a dashboard in the View page's own folders. A model's dashboard is never in the
  station's dashboard list; it reaches the View page only through Show on View, one entry per
  unit.
- It does not start or steer a run. A Button bound to a command point on the resolved dashboard
  does, under the Run procedures permission, exactly as on any dashboard; see
  [Runs and comments](process-runs).