Model Builder

The Model Builder is a visual design application for creating reusable, parameterizable UI components called Models. You compose primitive shapes and nested model instances on a canvas, define input parameters, bind notifications to data fields in the entity store, and save the result as a Model entity. Models behave like templates: design once, then instantiate many times with different parameter values to build complex, data-bound visualizations.

Core Concepts

A model is described by a single configuration object, saved as JSON. The configuration brings together four ideas:

Throughout a model, the ${paramName} syntax substitutes a parameter's value into text, HTML, CSS, event handlers, and callback expressions. This is what makes a single design reusable across many entities.

The Workspace

The Model Builder is built around a central canvas surrounded by panels. The default canvas is 1200×700 px and supports zoom from 0.1× to 5× (default 1×).

• Shape Palette: click or drag primitives onto the canvas.
• Canvas: compose shapes with drag-and-drop, zoom, grid and snap-to-grid, and fit-to-view.
• Properties panel (right): edit the selected shape's position, rotation, scale, and appearance.
• Parameters panel: define and edit input parameters and their validation.
• Notifications panel: define notification channels and their callbacks.
• Validation panel: review errors and warnings in real time.
• Model Library: browse, load, and drag existing models for nesting.

Shapes

Shapes are the building blocks of a model. Primitives cover geometry, text, and embedded HTML, while the ModelInstance type lets you nest another model as a reusable component.

Shape properties

Every shape carries transform properties (location, rotation, and scale) plus an id and a type. Primitive shapes additionally support appearance and behavior properties:

• Geometry & color: radius, edges, color, fillColor, fillOpacity, weight, opacity.
• Text: text, fontSize.
• HTML content: html, className, css, keyframes.
• Image: url.
• Behavior: handlers, methods, contextMenu.

Because text, html, css, handlers, and callback expressions all support ${paramName} substitution, a single shape can render differently for every instance of the model.

Parameters

Parameters are typed inputs that make a model reusable. Each ModelParameter has a name, a type, an optional defaultValue, and optional validation rules.

Validation rules let you mark a parameter required, constrain a number with min/max, enforce a pattern, or restrict it to a set of options. The validator surfaces problems before you save (see Validation).

Notification Channels

Notification channels connect a model to live data. A channel watches a field on an entity and runs a callback when that field changes, letting the model react by updating shape colors, text, or visibility. A NotificationChannel has the following fields:

The contextFields list delivers related data atomically with the change, so your callback never sees a partial view. For more, see Notifications & Reactivity.

Nesting Models

A ModelInstance embeds another model as a reusable component. Drag a model from the Model Library onto the canvas to create an instance, then open the Parameter Binding Editor to supply values for its parameters. Each instance references a parent modelId and carries a parameterBindings map.

Because instances can themselves contain child shapes and bindings, you can compose deep hierarchies of small, well-tested models into a single rich visualization.

Validation

The Validation panel runs the model validator continuously and reports problems as you work. Common findings include:

• Unused parameters that are defined but never referenced.
• Missing parameter definitions referenced by a shape or binding.
• Required parameters that have no default value.
• Invalid references to entities or models that cannot be resolved.

Building a Model: Step by Step

1. Open the Model Builder from the ControlBird UI.
2. Click New to start a blank model, or pick one from the Model Library to edit.
3. Add shapes from the Shape Palette by clicking or dragging onto the canvas.
4. Edit the selected shape in the Properties panel (position, rotation, color, text, HTML, CSS, min/max zoom).
5. Define input parameters in the Parameters panel: name, type, default value, validation, and description.
6. Add notification channels in the Notifications panel, using ${paramName} in the entity expression and supplying a callback.
7. Nest other models by dragging from the library, then bind their parameters in the Parameter Binding Editor.
8. Review the Validation panel for warnings.
9. Use the canvas controls to zoom, snap to grid, and fit to view.
10. Undo/redo and arrange layers as needed.
11. Save to persist the model and add it to the Model Library.

Example: a status indicator callback

A notification channel watching a status field can recolor a circle shape. The callback runs whenever the watched field changes:

function(notification) {
  const status = notification.current.value;
  const circle = this.getShapeById('status-circle');

  if (status === 'Online') {
    circle.setFillColor('#10b981');   // green
  } else if (status === 'Offline') {
    circle.setFillColor('#ef4444');   // red
  } else {
    circle.setFillColor('#6b7280');   // gray
  }
}

Editing Workflow

The Model Builder keeps a 50-entry undo/redo history and tracks unsaved changes. When a model is dirty and has been saved at least once, it auto-saves every 30 seconds so work is not lost. Context-menu operations cover cut, copy, paste, duplicate, and layer arrangement.

Saving & Sharing

Each saved model has a name and an optional description, and appears in the Model Library for reuse. Saving persists the full model design (shapes, canvas settings, parameters, notification channels, and metadata). Models can also be imported and exported as JSON for sharing between environments.

Next Steps

Once you have a library of models, explore the underlying data with the Database Browser, or connect models to live field changes by reviewing Notifications & Reactivity and the Data Model.