Widget Placement

In Atlas dashboards, widgets are placed using the V2 layout engine. The V2 engine works with proportional positioning (nx/ny/nw/nh ∈ [0,1]); widgets are positioned as a ratio of the canvas, not in pixels. This way the dashboard auto-scales across different screen sizes.

Prerequisite

An Atlas dashboard must be created and the canvas open.

→ Create Dashboard

1. Switch to Edit Mode

Click the Edit Mode toggle in the top bar. While in edit mode:

Grid lines appear at 15% opacity
Drag and resize handles become active on widgets
A border highlight appears when a widget is selected
The Delete icon becomes visible

2. V2 Grid Logic

Feature	V2 Behavior
Base column count	60
Positioning	Proportional: `nx = pixelX / baseWidth`, `nw = widthCells / 60`
Min widget size	2×2 cells
Overlap	Snap-to-grid + auto-placement (left-to-right, top-to-bottom)
Z-order	List order — added later renders on top
Multi-layer panel	None (single-layer canvas)

V1 vs V2

In Horizon V1, widgets are pixel-positioned; layout can overflow when screen size changes. In Atlas V2 the ratios are preserved — placement scales as-is on mobile/tablet.

Click the Add Widget button in the top bar. The dialog that opens shows the Cartography widget library:

Dialog Sections
Search (by name)
Chart type filter
Tag filter
Folder tree
Widget preview card

Pick a widget and add it to the dashboard with Add. The widget is placed in the empty area via auto-placement (scanning left-to-right, top-to-bottom).

To place the widget:

Action	Behavior
Drag (grab the top edge to move)	Snaps the widget to a new nx/ny coordinate
Resize (corner handle)	Changes width/height; min 2×2
Right-click → Delete	Removes the widget
Selection (click)	Selects the widget; highlight border appears

Auto-placement Algorithm

When a new widget is added, the system scans empty areas left-to-right and row-by-row; it places the widget in the first suitable spot. Without manual intervention, widgets fill the grid automatically.

5. Resize Limits

Limit	Value
Minimum width	2 cells (2/60 ≈ 3.3%)
Minimum height	2 cells
Maximum width	60 cells (entire row)
Maximum height	Canvas height

If a resize falls below the minimum, it is auto-clamped.

6. Overlap Prevention

Atlas V2 does not allow widget overlap. If a dragged widget is dropped on another, snap-back places it in the nearest empty area.

When There's No Room

When canvas runs out of room, auto-placement opens a scrollbar; the widget is added at the bottom. Vertical scroll activates when content exceeds 50% of the viewport (scrollThresholdFactor=0.5).

7. Layout Persist

The layout JSON is written to the backend in this shape:

{
  "items": [
    {
      "item_id": "uuid-...",
      "chart_name": "Plant1_Line3_OEE",
      "nx": 0.0,
      "ny": 0.0,
      "nw": 0.4,
      "nh": 0.3
    },
    {
      "item_id": "uuid-...",
      "chart_name": "Plant1_HourlyProduction",
      "nx": 0.4,
      "ny": 0.0,
      "nw": 0.6,
      "nh": 0.3
    }
  ]
}

When Save / Update is clicked, this JSON is sent via the update_dashboard API.

8. Common Errors

Symptom	Possible Cause	Solution
Drag does not work	Edit mode is off	Turn on the Edit Mode toggle
Widget disappeared	Compass query returned an error	Test the query in Compass
Resize is inconsistent	Browser zoom is not 100%	Set browser zoom to 100%
Auto-placement cannot find empty space	Canvas is full	Add a smaller widget or open the scrollbar

9. Next Step

→ Responsive Behavior

Widget Placement

1. Switch to Edit Mode

2. V2 Grid Logic

3. Add Widget Dialog

4. Widget Placement