Widget Functionality

Overview

The Grid widget renders one square per configured Tango attribute (attributes) and updates values via polling and/or streaming. It supports per-cell hover detail rows, enum-aware value display, and state-based coloring for both squares and hover chips.

Runtime behavior

  • The layout is responsive and computes the best column/row fit for the widget container.

  • Optional fixed square dimensions can be forced with squareSizePx=[width,height] (pixels). [] or [0,0] keeps automatic sizing.

  • The widget listens to host layout updates (Octopus.getWidgetLayout + subscribeWidgetLayout) and falls back to the octopus:widget-layout event channel when needed.

  • Hover cards open while the pointer is over a square and hide on mouse leave.

  • Hover cards only appear when hover targets are configured for that row (hoverAttributes).

  • Squares can perform click actions: update a configured dashboard variable and optionally navigate to a configured workspace.

Data sources

The widget uses:

  • GraphQL query attributes(...) for polled values and metadata (enumLabels, unit, etc.).

  • GraphQL query device(...) { properties { name value } } when [properties]... selectors are configured, to resolve dynamic device lists.

  • GraphQL subscription tangoAttributes(...) for live value updates.

Implementation: src/graphql/ops.ts.

Value rendering

  • Main square text uses cellLabelFormat.

  • If useEnumLabels=true, enum labels are shown (for example UNKNOWN, ON).

  • If useEnumLabels=false, numeric/raw values are shown.

  • Hover values optionally include units when showUnits=true.

Click actions

  • Clicking a square can update a dashboard variable (selectedVariableKey).

  • The new variable value is computed from selectedVariableFormat using the clicked row data.

  • Variable-key matching is case-sensitive and depends on host-defined variables; unknown keys may be ignored by the host.

  • Clicking a square can switch workspace (workspace) when configured.

  • When both variable update and workspace switch are configured, the variable is also re-applied after workspace change to improve cross-workspace propagation.

State colors

  • State colors come from the widget SDK palette (STATE_COLORS_HEX), sourced from ska-octopus-widget-sdk/src/colors/stateColors.ts.

  • Color mapping is enum-aware for state attributes:

    • Color lookup uses enum labels when available, even when useEnumLabels=false for displayed text.

  • Square background color uses the mapped state color when available; otherwise a neutral gradient fallback is used.

  • Hover chips use the mapped state color directly.

Hover detail rows

  • Each square can show one or more hover rows from hoverAttributes.

  • Each hover entry must be a full attribute path.

  • Hover entries can also use [properties]<controller-device>/<property-name>/<attribute> and will be expanded before polling/subscription.

  • If a [properties]... main row and its [properties]... hover row expand to equal counts, the widget maps hover values one-per-square by index.

  • If a main [properties]... row has multiple hover [properties]... selectors and all expansions match the main count, each square shows one indexed value per selector (for example both state and status on the same hover card).

Notes

  • Polling interval follows the dashboard refresh rate when useLiveData=false.

  • The widget prioritizes stream values when live mode is enabled and falls back to polled values.

  • Mutations are not used by this widget.