Dashboards

Overview

Dashboards are operator interfaces you build in the Layout Editor app by dragging and dropping widgets onto a responsive canvas. Each widget binds to a live entity field and updates in real time, so a dashboard becomes a reactive view of your plant, building, or home. Layouts support interactive controls (buttons, sliders, toggles), read-outs (entity state, gauges), and visualizations (charts), with conditional styling and role-based publication.

Reach for the Layout Editor when you want to present exactly what an operator needs to see and do: no more, no less. A dashboard organizes widgets in a recursive tree of containers (using grid, flexbox, or absolute layout modes) and adapts across screen sizes through responsive breakpoints. Layouts are saved and, once published, appear in the Layouts menu for users with the right permissions.

Key Concepts

A few ideas tie the dashboard model together:

• Recursive tree. A layout is a tree of nodes. Container nodes hold children and apply a layout mode; panel nodes are leaves that render either a card widget or an embedded app component.
• Card widgets. Six card types (Entity State, Gauge, Toggle, Slider, Button, and Chart) cover display, control, and visualization needs.
• Data binding. A card binds to a live entity field. Binding happens by dragging an entity from the Database Browser onto the canvas, or by setting the binding in the Properties Panel.
• Layout modes. Containers arrange children with Grid, Flexbox (horizontal or vertical), or Absolute positioning.
• Responsive breakpoints. Breakpoints let a layout target distinct screen dimensions for desktop, tablet, and mobile.
• Draft vs published. Edits stay in a draft state visible only to the editor until you Save and then Publish.

Opening the Layout Editor

The Layout Editor is the primary tool for building dashboards. Open it from the ControlBird logo in the taskbar. The editor provides a widget palette, a snap-to-grid design canvas, and a Properties Panel for the selected widget, plus undo/redo history and a preview mode for testing with live data before you publish.

Card Types

Each panel selects one of six widgets, each with its own configuration:

Gauges support color-coded segments and a min/max display. Sliders include a debounce (default 300 ms) and a step control. Charts support time ranges from 1 hour up to custom windows with a 30-second refresh interval.

Entity state formatting

An entity-state card can format its value using one of several modes:

• default: show the raw value.
• number: format with decimals and a unit.
• boolean: render custom true/false labels.
• date: format as a date.
• duration: format as an elapsed duration.

Layout Modes

Each container node applies one layout algorithm to its children:

Panel sizing modes

• fit (default): the panel grows to fit its content.
• compact: hides optional UI and shrinks fonts.
• fixed: a strict pixel height; content that overflows is clipped.

Common Patterns

• Conditional formatting via segments. Use a gauge's segments array to color zones: for example blue below 65°F, green 65–78°F, yellow 78–85°F, and red above 85°F.
• Debounced control writes. Sliders debounce writes (default 300 ms) so a dragged value does not flood the target field with intermediate updates.
• Confirmable actions. Button actions support write/toggle/increment/decrement with an optional confirmation prompt for destructive operations.
• Quick binding by drag-and-drop. Drag an entity from the Database Browser onto the canvas and ControlBird creates and binds an appropriate widget automatically.
• Per-device dashboards. Build separate layouts for different audiences (an overview for managers, detailed controls for operators) and publish each with its own access permissions.

Troubleshooting & Limitations

• Widget shows "No Data". The binding path is incorrect, the user lacks read permission on the field, or the field type is incompatible with the card type.
• Controls fail silently. Slider, button, and toggle widgets give no design-time error when the target field is read-only or the user lacks write permission, so verify both before publishing.
• Drafts invisible to others. Unpublished layouts cannot be seen by other users; click Save, then Publish, to share. Unsaved changes are lost on app close.
• Sparse breakpoints break intermediate sizes. Breakpoints match width/height exactly, so layouts may break on screen sizes between defined breakpoints. Define enough breakpoints to cover your target devices.
• Grid overflow. A grid with more children than cells (columns × rows) overflows unpredictably, so validate the cell count before adding cards.
• Overlapping gauge segments. Segment ranges must not intersect; overlapping ranges (e.g. from: 0–100 and from: 50–150) produce undefined behavior.
• Drag-drop strips nested paths. Entity drag-drop binding drops the field path context. For entities with nested or complex structure, set the field path manually in the Properties Panel.
• Charts need a saved ChartConfiguration. Chart cards require a saved ChartConfiguration entity created via the Chart Builder app; inline chart configs are not supported.
• Fixed sizing clips content. The fixed sizing mode clips overflow and does not reflow, so prefer fit or compact when content length is uncertain.
• Mobile preview stacks cards. A canvas narrower than 1280 px switches to a stacked layout; test card responsiveness at your target breakpoint widths to confirm stability.