Mendix Vega Charts

Vega-Lite charts in Mendix

What this is

A pluggable widget, roughly 150 lines of TSX, with two properties that matter:

The widget folds the data into the spec under the name given by datasetName and hands the result to vega-embed, which picks Vega or Vega-Lite from the spec's own $schema. Nothing else happens at runtime.

The split is the whole point. The model emits a table of facts; the specification decides what that table looks like. A microflow that concatenates a chart payload — series, axes, colours — is a microflow that has to be edited every time the chart changes, and it cannot be checked without running the app. A microflow that emits [{"cat":"Groceries","m":"2026-06-01","v":697.70}, ...] can be checked against the database with a SQL query, and the spec beside it can be compiled and measured without a browser at all (see Verifying).

Who this is for

An agent. The tradeoff is deliberate: a hand-authored Vega-Lite spec is a large piece of JSON, which is uncomfortable to maintain in Studio Pro's property editor and comfortable for a coding agent that can compile it, render it headless, and measure the result. If a human will maintain the chart by hand in Studio Pro, use Studio Pro's chart widgets instead.

What makes this usable without deep Vega-Lite knowledge is specs/ — working specifications for the common shapes, each with a sample data file, each of which compiles and renders. Start from the closest one and change fields, not structure.

Getting the widget into a project

See references/install.md. Summary: copy the widget source, npm ci, npm run build, put the built .mpk in the project's widgets/ folder, and commit it — a gitignored widgets/ makes every other clone unbuildable.

Re-namespace it away from whoever built it first (ledger.widget.web.… here) with three edits, listed in that file. Verified: after the three edits the built package carries the new namespace throughout, including the widget id inside VegaChart.xml.

Using it from MDL

pluggablewidget 'acme.widget.web.vegachart.VegaChart' chartSpend (
  chartData: ChartData,
  datasetName: 'table',
  chartHeight: 0,
  renderer: 'svg',
  showActions: false,
  spec: '{ ... }')

It needs an entity context — put it in a dataview over the object whose attribute holds the data. The full property table, the escaping rules for putting JSON inside an MDL string, and the click-back path are in references/properties.md.

Two rules worth carrying in your head:

• chartHeight: 0 means "as tall as it renders". A chart whose height is decided by its data — a facet row per category, a legend entry per series — has no height the page can be told in advance, and a fixed container silently stops matching the moment the data grows.
• Single quotes inside the spec must be doubled. MDL strings are single-quoted, so a Vega expression like ['Jan','Feb'][datum.m-1] is written [''Jan'',''Feb''][datum.m-1]. It is stored unescaped.

Two ways to get data in

As an attribute (the default). A microflow builds a JSON array into a string attribute, chartData binds to it, and the widget folds it into the spec. Nothing is fetched; the payload arrives with the page.

As a URL. Leave chartData unbound and put the address in the spec:

"data": {
  "url": "/odata/chartapi/v1/MonthCategory?$filter=Yr eq 2026",
  "format": {"type": "json", "property": "value"}
}

The spec needs no change for this — with no data bound the widget passes it through untouched and Vega's own loader does the fetch. Verified end to end against an endpoint served by the app itself: one 200, six marks, no error, and format.property unwrapping the {"value": […]} envelope OData returns.

A session-authenticated endpoint needs X-Csrf-Token

Same-origin requests carry the session cookie, and the cookie alone is not enough. Mendix refuses a session-authenticated request without the session's CSRF token — on a read, not just a write, and on /odata/ as well as /xas/. Measured on 11.14.0 against one URL, four requests:

Vega reports the 401 body as an empty dataset, so the chart draws its axes and a full legend with no marks and no error — measured through this widget's own loader: 0 marks and 3 axes without the token, 1 mark with it.

The widget shipped here supplies the header (widget/src/csrf.ts), reading the token from mx.session.getConfig("csrftoken") — it is not a cookie and cannot ride along by itself. A widget built from an earlier copy of this pack does not, and needs that loader added:

const instance = vegaLoader();
const fetchHttp = instance.http.bind(instance);
instance.http = (uri, options) => fetchHttp(uri, withCsrfHeader(uri, options, location.href, token));

Same-origin only, and the check is a resolution rather than a string test: the token authenticates this session against this app, so sending it to a third-party host hands that host a working credential. Resolving the URI against the page settles the two cases a /^[a-z][a-z0-9+.-]*:\/\//i test on the raw string gets wrong — a protocol-relative //elsewhere.example/rows.json carries no scheme and goes to another host, and an absolute URL naming the app's own origin is the app.

Two things that send a diagnosis the wrong way:

• document.cookie shows only originURI=/login.html. That reads like a missing session cookie and starts a hunt for a cookie problem that does not exist — XASSESSIONID and xasid are httpOnly, so the browser sends them and JavaScript cannot see them.
• Basic auth on the same URL returns the data, which looks like proof the endpoint is fine and the chart is broken. Both are fine; the header is missing.

The wider rule, and what each authentication method costs, is in .claude/skills/mendix/odata-data-sharing/reference/errors-and-auth.md.