GridStack on Insights dashboards¶

This guide explains how to add a GridStack dashboard (draggable, resizable grid) to any Insights page in Nautobot Professional. Layouts are not persisted client-side — drag/resize changes live only on the current page render. Persistent customization will be added later via a database-backed store.

Reference implementation: Hardware & Software Lifecycle dashboard (DeviceLifecycleMGMTInsightsView, URL insights/lifecycle/).

Prerequisites¶

The grid uses 12 columns. Panels use grid_x, grid_y, grid_w, grid_h (cell units).
JavaScript snaps position and size to any cell (free snap), with a minimum panel size of 3×3.

Step-by-step¶

1. Load CSS and JavaScript on the page¶

The shared dashboard template nautobot_tools/templates/nautobot_tools/insights_dashboard.html already loads the GridStack asset bundle in content. Insights views just need to use that template (template_name = "nautobot_tools/insights_dashboard.html"):

GridStack 12.6.0 (vendored under nautobot_tools/static/nautobot_tools/vendor/gridstack-12.6.0/)
nautobot_tools/static/nautobot_tools/css/insights_gridstack.css
nautobot_tools/static/nautobot_tools/js/insights_gridstack.js

The script registers a DOMContentLoaded listener and automatically initializes every element with the np-insights-gridstack class produced in the next step.

2. Define a `GridStackContainer`¶

In the view (or wherever you build context["components"]), add a GridStackContainer with panels=... where each panel's section is InsightsSectionsChoices.GRID_STACK.

Import GridStackContainer and InsightsSectionsChoices from nautobot_tools.components.

Optional — avoid clashes across pages or multiple grids on one page:

`GridStackContainer` argument	Default	Purpose
`grid_stack_element_id`	`np-insights-grid`	HTML `id` of the grid root element (must be unique on the page).
`grid_stack_static`	`False`	When `True`, render a non-interactive grid (no drag, no resize).

Each grid widget's gs-id comes from the panel's component_id, which the UI Component Framework auto-generates (deterministic hash of the panel's attributes). Pass component_id="..." explicitly when you need a stable id (e.g. for future DB-backed layout persistence).

3. Configure each panel on the grid¶

Use the usual panels (ProEChartsPanel, BigNumberCardPanel, etc.) with:

section=InsightsSectionsChoices.GRID_STACK
grid_x, grid_y, grid_w, grid_h — initial position and size on the grid
component_id="unique-id" — optional; auto-generated from the panel's attributes when omitted.

Set weight to order panels within the same section.

Abbreviated example:

from nautobot_tools.components import GridStackContainer, InsightsSectionsChoices, ProEChartsPanel

GridStackContainer(
    weight=100,
    grid_stack_element_id="my-dashboard-grid",
    panels=(
        ProEChartsPanel(
            weight=100,
            section=InsightsSectionsChoices.GRID_STACK,
            component_id="chart-1",
            grid_x=0,
            grid_y=0,
            grid_w=6,
            grid_h=6,
            label="Example",
            chart_class=MyChartClass,
        ),
    ),
)

4. View template¶

Point the view's template_name at nautobot_tools/insights_dashboard.html — it loads the asset bundle and renders {% render_components components %} for you. You do not need inline JavaScript to start the grid unless you have an edge case (see below).

JavaScript API (optional)¶

The global window.nt.insightsGridStack object exposes:

init() — initializes every .np-insights-gridstack on the page.
initAll() — same as calling init() with no arguments.
init('element-id') or init(domElement) — a single grid only.

File	Role
`nautobot_tools/templates/nautobot_tools/insights_dashboard.html`	Shared dashboard template; loads vendored GridStack + app statics
`nautobot_tools/components/dashboard_gridstack.html`	`.grid-stack` markup
`nautobot_tools/static/nautobot_tools/js/insights_gridstack.js`	GridStack init, snap, ECharts resize
`nautobot_tools/static/nautobot_tools/css/insights_gridstack.css`	Grid and card styling
`nautobot_tools/components.py`	`GridStackContainer` (subclass of `Container`) with `grid_stack_*` arguments

Best practices¶

Use a distinct grid_stack_element_id per dashboard (e.g. lifecycle vs. devices) and per grid when more than one is rendered on the same page.
Pass component_id explicitly on panels you expect to migrate to a future DB-backed layout store. The auto-generated id is a hash of panel attributes, so any change to those attributes will produce a different id.