Step 16: Visual Design Tools

Create reusable graphics, device faceplates, and system schematics with the visual builders.

Sign Up
Environment
Node
Access
Architecture
Explore
Connect
Automate
History
Alarms
Users
Access+
Scripts
Logs
Dashboards
16
Builders
17
Kiosks
18
Themes
19
Config
20
Audio
21
Scaling
22
Failover
23
Email

In the previous step, you learned to build dashboards with the Layout Editor. Now you'll discover ControlBird's three specialized visual builders for creating reusable graphics that bring your devices to life.

Three Builders, Three Purposes

ControlBird provides three visual design tools, each optimized for a different use case:

Model Builder

Reusable Visual Components

Create template graphics with parameters. Like a "class" in programming - define once, instantiate many times with different values.

Example: An "Alarm Border" model that can wrap any device and shows red when that device has an active alarm.

Faceplate Builder

Single-Device Detail Views

Create detailed control panels for one device type. Uses indirection - the same faceplate works for any instance of that device type.

Example: A "Pump Faceplate" showing status, controls, and diagnostics. Opens when you right-click any pump entity.

Schematic Builder

Multi-Device Spatial Layouts

Create overview displays showing multiple devices in their physical arrangement. Each device is directly bound to a specific entity.

Example: A "Station Platform" schematic showing all sensors, displays, and equipment positioned as they appear in the real world.

Choosing the Right Tool

Here's a decision guide to help you pick the right builder:

If you need to...Use
Create a reusable graphic element (icon, indicator, symbol)Model Builder
Build a control panel that works for any device of a typeFaceplate Builder
Show multiple specific devices in a spatial layoutSchematic Builder
Create a graphic with configurable parametersModel Builder
Design a popup that appears when clicking a deviceFaceplate Builder
Create a floor plan or system overviewSchematic Builder

Model Builder: Reusable Components

The Model Builder creates visual templates with parameters. Think of models as reusable building blocks - you define the appearance and behavior once, then use them throughout your system with different parameter values.

Key Concepts

Parameters
Variables that customize each instance. A "Pump Symbol" model might have parameters for targetEntity, showLabel, and size.
Shapes
Visual elements like circles, rectangles, text, and images. Properties can reference parameters using ${paramName} syntax.
Notifications
Subscribe to entity field changes. When values change, callbacks update the visual appearance (colors, text, visibility).
Nesting
Models can contain other models. Build complex graphics from simple, reusable parts.

Creating a Simple Model

Let's create a "Status Indicator" model that shows green when a device is online and red when offline:

  1. Open Model Builder from the ControlBird menu
  2. Click + New Model
  3. Name it "Status Indicator"
  4. Add a parameter: targetEntity (type: EntityReference)
  5. Draw a circle shape on the canvas
  6. Add a notification channel watching ${targetEntity}.Status
  7. Write a callback that sets circle color based on value
  8. Save and test with different entities

In the callback, read the incoming status value and choose a fill color for the circle: green when the device is online, red when offline, and a neutral gray otherwise. The Model Builder applies the new color the moment the watched field changes, so the indicator stays in sync with the device in real time.

Faceplate Builder: Device Control Panels

The Faceplate Builder creates detailed interfaces for a single device type. Faceplates use indirection - they don't bind to a specific entity, but rather to "the entity being viewed." This means one faceplate design works for all instances of that device type.

How Indirection Works

Faceplate Design

Watches fields like "Status", "Value", "Name" without specifying which entity

Runtime Context

User opens faceplate for "Pump-A" - context entity is set

Bound Display

Faceplate shows Pump-A's actual Status, Value, and Name

When to Use Faceplates

  • Device detail popups - Right-click a device to see full controls
  • Operator control panels - Detailed view for monitoring one device
  • Diagnostic displays - Show all fields and history for troubleshooting

Faceplate vs Dashboard

Faceplates show one device in detail. Dashboards (Layout Editor) show multiple devices at once. Use faceplates for "drill-down" views opened from dashboards or schematics.

Schematic Builder: System Overviews

The Schematic Builder creates spatial layouts showing multiple devices in their physical arrangement. Unlike faceplates, schematics use direct entity references - each device placement explicitly points to a specific entity path.

Key Features

Device Placements

Position models or faceplates at specific locations on the canvas

Navigation Buttons

Link to other schematics for hierarchical navigation

Background Shapes

Draw static elements like floor plans, pipes, and labels

Zoom Levels

Show/hide details based on zoom - overview vs detail views

Creating a Schematic

  1. Open Schematic Builder from the ControlBird menu
  2. Click + New Schematic and name it
  3. Draw background shapes (floor plan, equipment outlines)
  4. Add device placements from the library panel
  5. For each placement, set:
    • Visual: Which Model or Faceplate to display
    • Target Entity: The specific entity path (e.g., /Root/Stations/Central/Pump1)
    • Position: Where on the canvas
  6. Add navigation buttons to link to sub-schematics
  7. Save and test in preview mode

How They Work Together

The three builders are designed to complement each other in a layered architecture:

Schematic
Station Platform Overview
Pump Symbol (Model)
Sensor Icon (Model)
Alarm Border (Model)
click device
Faceplate
Pump Control Panel
Gauge (Model)
Button (Model)
Trend Chart (Model)

A typical workflow:

  1. Create Models for basic visual elements (gauges, icons, status indicators)
  2. Build Faceplates that combine models into device control panels
  3. Design Schematics that place models and faceplates on spatial layouts
  4. Use in Dashboards by embedding schematics or faceplates in Layout Editor

Best Practices

Build a Model Library

Create reusable models for common elements. A good library speeds up all future work.

Consistent Sizing

Use standard sizes for models so they align nicely in schematics and dashboards.

Efficient Notifications

Use triggerOnChange: true for config fields to reduce unnecessary updates.

Layer Appropriately

Put background shapes on lower z-index, devices on top. Use panes for complex layouts.

Troubleshooting

Model shows "undefined" for parameter values
  • Check parameter binding: Ensure the parameter is bound when instantiating the model
  • Check syntax: Use ${paramName} not $paramName
  • Check default value: Set a sensible default in the parameter definition
Faceplate notifications not firing
  • Check field name: Field names are case-sensitive
  • Check context entity: Faceplate must be opened with a valid entity context
  • Check callback syntax: Ensure the callback function is valid JavaScript
Schematic device placements not showing
  • Check entity path: The target entity path must exist and be accessible
  • Check visual entity: The Model or Faceplate must be saved and accessible
  • Check zoom level: Device may be hidden at current zoom (minZoom/maxZoom)
When should I use a Model inside a Faceplate vs inside a Schematic?

In a Faceplate: The model inherits the faceplate's context entity. Use ${targetEntity} parameter bound to the context.

In a Schematic: Each model placement has its own explicit target entity. The parameter is bound to that specific entity path.

Coming Up Next

Now that you can create visual assets, learn how to deploy them to dedicated kiosk displays with automatic login and location-specific content.