JavaScript API¶

Pre-built bundles ship under grid_view_spec/static/grid_view_spec/. The main entry is gridviewspec.min.js (global GridView). Host projects do not need Node at runtime.

Boot¶

After {% grid_view_spec_assets part='js' force_core=True %}, one script initializes the page:

API	Purpose
`GridView.bootScope(scope?)`	Scan a DOM subtree (default `document`) and boot tables, filters, KPI, charts, column settings, and GridViewSpec roots
`GridView.boot(root?)`	Boot one element, or re-run scope boot when omitted

| GridView.confirm(options) | Show unified modal confirmation dialog (returns Promise<boolean>) | | GridView.notify(options) | Show toast notification in unified notification stack | DOMContentLoaded and HTMX afterSwap call GridView.bootScope(). Do not load separate chart, KPI, or artifact boot scripts.

Loading scripts¶

GridViewSpec pages¶

{% load grid_view_spec %}
{% grid_view_spec_assets part='js' force_core=True %}

Load order:

Inline — GridView.preferencesUrl, GridViewI18n
gridviewspec.min.js — unified runtime

Inclusion tags (render_grid_view_spec, …) only mark which optional bundles a page needs; the actual <script>/<link> tags are emitted by {% grid_view_spec_assets %}. Always call it once per page (CSS in <head> + JS before </body>).

Declarative confirmation¶

Managed GridView action, cell-action, and link dispatch paths read data-cm-confirm as a JSON string or object. Cancellation prevents the managed action, while acceptance invokes it once. Plain DOM buttons, links, and forms are not intercepted by this attribute. Boot also adapts global window.confirm and window.alert, and bridges htmx:confirm.

Globals the host must provide (before the bundle):

Global	Required for
`echarts`	Charts
`Sortable`	Column drag-reorder in settings modal

Use {% echarts_cdn_url %} and {% sortable_cdn_url %} or your own CDN links.

AG-Grid pages¶

Load CDN scripts, ag-grid-host.js, and boot JSON — see AG-Grid integration.

GridView.init¶

Used by chat panels and SPAs that receive a resolved spec or table root:

var disconnect = GridView.init({
  root: document,
  artifact: payload,
  gridAdapter: adapter,
});

Initializes simple tables, KPI strips, charts, and optional AG-Grid bindings. disconnect() removes listeners.

AG-Grid infinite model¶

GridView.AgGrid.createInfiniteDatasource({
  url: "/api/my-grid-data/",
  gridId: "my-grid",
  getExtraParams: function () { return { period: "2024-01" }; },
});

GridView.AgGrid.syncExportHref(linkEl, "my-grid", { exportColumns: true });
GridView.AgGrid.syncExportLinks("my-grid");

API	Purpose
`createInfiniteDatasource(options)`	Wire AG-Grid infinite `getRows` to your JSON API
`buildInfiniteQueryParams(...)`	Serialize block params, filters, sort, search
`syncExportHref(linkEl, gridId, options)`	Copy filters, sort, `q`, `col_q`, `export_cols` into export URL
`syncExportLinks(gridId, options)`	Update all `[data-cm-export-sync]` links
`GridView.byId.get(gridId)`	Runtime handle (`AgGridHost` or column settings)
`GridView.createColumnSettings(...)`	Column settings for AG-Grid or Simple Table

Toolbar markup uses data-cm-grid-id, data-cm-col-action, data-cm-grid-action, and data-cm-grid-search — no inline JS required.

AG Grid stores browser-local table state through GridView.PageState; URL filter and search values take precedence. See AG-Grid — Persistence.

Page state¶

GridView.PageState stores opaque browser-local persistent JSON for a rendered spec root. It does not manage runtime state or render UI.

const pageState = GridView.PageState.forRoot(root);

if (pageState) {
  pageState.put("layout.drawer", { open: true, width: 480 });
  const drawer = pageState.get("layout.drawer");
  pageState.remove("layout.drawer");
}

forRoot() returns null outside a connected GridViewSpec root. See Page state for identity, scopes, namespaces, storage failures, and URL precedence.

AG-Grid adapter (filtered KPI / charts)¶

var adapter = GridView.createAgGridAdapter(gridApi);
GridView.bindGridKpis({ root: document, gridAdapter: adapter });
GridView.bindGridFilteredCharts(document, adapter);

Method	Purpose
`getRows()`	Visible rows after filter/sort
`onChange(cb)`	Subscribe to model updates

For static rows: GridView.staticRowsAdapter(rowsArray).

KPI helpers¶

API	Purpose
`GridView.resolveKpis(specs, rows)`	Client-side aggregates
`GridView.Kpi.initKpiStrip(root, kpis, columns)`	Render resolved KPI cards
`GridView.bindGridKpis({ gridAdapter })`	Wire `[data-cm-grid-kpi]` strips

Charts¶

API	Purpose
`GridView.initChart(el, config, rows)`	Mount one ECharts instance
`GridView.initAllCharts(scope)`	Scan `[data-cm-chart-config]`
`GridView.buildEchartsOption(config, rows)`	Build ECharts option object
`GridView.bindGridFilteredCharts(scope, adapter)`	Charts with `data_source: grid_filtered`

Requires global echarts.

Simple Table¶

GridView.SimpleTable.initAll(scope);

Usually called automatically from GridView.bootScope().

Search and filters¶

Client matching must stay aligned with Python search modules. Conformance fixtures live under tests/fixtures/; run npm run test:conformance in frontend/ and pytest filter tests after behaviour changes. See Filter semantics.

Gallery¶

GridView.bootScope() calls initGalleryBlocks. Thumbs come from GridViewGallery markup (data-cm-gallery). When lightbox is true, click opens the package overlay (Escape, arrows, prev/next). Overlay DOM is created on first open.

Hosts without gallery markup can open the same overlay:

GridView.openGallery([{ url: "/media/a.jpg", alt: "A" }], 0);
GridView.closeGallery();

Lazy galleries (data-cm-gallery-src) fetch JSON and insert thumbs. Hosts may listen:

document.addEventListener("gridview:gallery-open", function (event) {
  console.log(event.detail.galleryId, event.detail.index);
});

i18n¶

GridView.i18n.t("search.placeholder", "Search…");

Translations ship in grid_view_spec/locale/. The bundle injects window.GridViewI18n before gridviewspec.min.js.

Maintainer build¶

cd frontend && npm ci && npm run build

Commit regenerated files under src/grid_view_spec/static/grid_view_spec/. CI checks for drift.

Generated wire types¶

TypeScript wire/authoring types are generated from schema/grid-view-spec.v2.json (the single source of truth). After editing the schema, regenerate and commit the output:

cd frontend && npm run gen:types   # writes src/types/generated/grid-view-spec.ts

Import them from the frontend/src/types/spec.ts barrel. Drift is enforced by npm run gen:types:check (also in scripts/ci-gate.sh) and tests/test_ts_schema_parity.py.