Dashboard Builder & Customisation

The Dashboard Builder at /dashboard/builder is the full customisation interface for creating, editing, and managing your dashboards. It gives you complete control over layout, widgets, and sharing settings.

Creating a new dashboard

Click New Dashboard in the builder toolbar. You are prompted to enter:

• Name — A descriptive label for this dashboard (e.g., “Weekly Operations View”)
• Description (optional) — A brief note about the dashboard’s purpose
• Start from template — Choose a pre-built template (Executive, Operations, Financial, Warehouse, or Crew) or start with a blank canvas

The first dashboard you create automatically becomes your default. Subsequent dashboards can be set as default using the is_default toggle in settings.

Dashboard settings panel

Open the settings panel by clicking the gear icon in the builder toolbar. The following options are available:

• Name — Rename the dashboard at any time
• Description — Update the optional description stored in description
• Set as default — Toggle is_default to make this the dashboard that loads on login. Setting a new default automatically unsets the previous one.
• Layout configuration — Adjust grid_columns (default 12), row_height (default 80px), margin (default [10, 10]), and container_padding (default [10, 10])

Adding widgets

Click Add Widget to open the Widget Library dialog. The library organises 50+ widgets into seven categories: KPI, Charts, Lists, Calendar, Activity, Financial, and AI. You can:

• Browse by category — Click a category tab to filter the widget list
• Search by name — Type in the search field to find a specific widget
• Filter by role — Some widgets are restricted to CoreAdmin and CoreManager roles (financial widgets, for example)
• Check addon availability — Widgets requiring the Analytics & AI addon display an upgrade prompt instead of the add button

When you select a widget, choose a size preset:

• Small — 4 columns wide
• Medium — 6 columns wide
• Large — 12 columns wide (full width)

The widget is placed at the next available position on the grid. Every widget type has minimum and maximum size constraints — typically 2 columns by 2 rows minimum and 12 columns by 8 rows maximum.

Drag-and-drop positioning

In edit mode, GridStack enables full drag-and-drop widget repositioning. Grab a widget by its header bar and drag it to a new location. The grid snaps widgets to the nearest column and row boundaries. Collision detection automatically shifts other widgets out of the way to prevent overlap.

Resizing widgets

Drag the corner or edge handles of any widget to resize it. Resize operations respect each widget type’s minimum and maximum constraints, stored as width and height on the DashboardWidget model. For example, a KPI tile can be as small as 2 columns by 2 rows, whilst a calendar widget may require at least 6 columns by 3 rows.

Widget configuration

Click the settings gear icon on any widget to open its configuration dialog. Common settings include:

• Title — Customise the widget’s display name (stored in widget_name)
• Time period — Select from today, this week, this month, this quarter, this year, last 7 days, last 30 days, last 90 days, or last 12 months
• Trend indicators — Toggle comparison with the previous period (on/off)
• Legend visibility — Show or hide the chart legend
• Cache TTL — Override the default 300-second cache duration for this specific widget (cache_ttl_seconds)

Widget-specific settings vary by type. For instance, a bar chart widget may offer grouped or stacked bar modes, whilst a list widget allows you to set the maximum number of rows displayed.

Widget wrapper

Every widget is wrapped in a standardised container that provides a consistent header bar with the following controls:

• Title — The widget name displayed in the header
• Refresh button — Manually recalculate the widget’s data, bypassing the cache
• Fullscreen toggle — Expand the widget to fill the browser viewport for detailed inspection
• Settings gear — Open the widget configuration dialog
• Remove button (edit mode only) — Remove the widget from the dashboard

Saving and resetting layouts

Position and size changes are persisted immediately when you move or resize a widget in edit mode. Configuration changes made through the settings dialog require clicking Save. If you want to undo recent rearrangements, click Reset Layout to revert to the last explicitly saved state.

Duplicating a dashboard

To duplicate an existing dashboard, open its settings panel and click Duplicate. This creates a full copy of the dashboard including all widgets, positions, and configurations. The copy is named with a “(Copy)” suffix by default, which you can rename immediately.

Deleting a dashboard

Open the settings panel and click Delete. Deletion is a soft delete — the dashboard is archived rather than permanently removed. You cannot delete your last remaining dashboard. If the deleted dashboard was your default, NexusRMS automatically promotes the next most recent dashboard to default status.

Forced dashboards (CoreAdmin only)

CoreAdmins can force a dashboard onto specific users or entire roles. Forced dashboards are created by cloning the source dashboard via the ForcedDashboardService. Two modes are available:

• Additive — The forced dashboard appears alongside the user’s personal dashboards
• Exclusive — The forced dashboard replaces all personal dashboards for the target user or role

Forced dashboards cannot be deleted by their recipients — they can only be revoked by a CoreAdmin.

Widget locking on forced dashboards

When forcing a dashboard, CoreAdmins can optionally lock all widgets. Locked widgets display a padlock icon and cannot be moved, resized, or removed by non-admin users. The WidgetLockingService manages lock state via the is_locked, locked_by_user_id, and locked_at fields on each widget. Only CoreAdmins can toggle locks.

Tips

• Start from a role template and then customise — it gives you a solid foundation without building from scratch
• Use full-width (12-column) widgets for charts that need space, and 3-column KPI tiles across the top row
• Group related widgets together — place financial widgets near each other, operational ones in another section
• Reduce cache TTL on KPI tiles for more frequent updates, and increase it on heavy charts to save database load

Next steps

Continue to the next article for a detailed breakdown of the Widget Library, including all seven categories and every available widget type.