docs(dashboards): document control values in the dashboard URL by mngr · Pull Request #11687 · cube-js/cube

mngr · 2026-08-28T19:12:04Z

What

Documents that a published dashboard's URL carries the viewer's control values — the user-facing half of cubedevinc/cubejs-enterprise#14497 (CUB-4198), which added outbound URL sync for the time granularity switcher.

Two gaps:

docs/explore-analyze/dashboards/widgets/controls.mdx never mentioned the URL at all, so the page described three controls whose selections read as living only in the viewer's browser tab. New Sharing the current selection section covers:

both parameters (f_<view>.<dimension>=<JSON>, tg_<view>.<dimension>=<granularity>), with the internal-name and lowercase-granularity gotchas;
what deliberately does not travel — a static default or a user-attribute default, so a shared link neither pins a default that has since changed nor leaks the sharer's own attribute value onto the recipient;
when an inbound parameter is ignored (no matching control; granularity outside the switcher's allowed list).

embedding/iframe/dashboards.mdx documented only ?f_…, though ?tg_… has worked inbound for as long. Its section now covers both in a table and notes the values travel back out too.

Note on the anchor

The embed heading became "Pre-set dashboard filters and granularities via URL" but keeps its old anchor explicitly ({#pre-set-dashboard-filters-via-url}), so the existing link from embedding/iframe/events.mdx keeps resolving.

Verification

Every claim was checked against the shipped code rather than inferred: the parameter formats and the internal-name/lowercase requirements, the defaults-excluded rules (buildUrlFilterParamsFromState / buildUrlTimeGrainParamsFromState serialize only viewer-overridden widgets), the allowedGrains gate on inbound, and published-only scope. The behavior itself was driven end-to-end on a real published dashboard.

Two gaps, one of them newly closed in the product. `controls.mdx` never said that a published dashboard's URL carries the viewer's control values at all — so the page described three controls whose selections looked, to a reader, like they lived only in that browser tab. It now has a "Sharing the current selection" section covering both parameters, what does and does not travel in a link (a static default and a user-attribute default deliberately stay out, so a shared link neither pins a stale default nor leaks the sharer's own attribute value onto the recipient), and when an inbound parameter is ignored. `embedding/iframe/dashboards.mdx` documented only `?f_…`, though `?tg_…` for time granularity has worked on the way in for as long. Its section now covers both, in a table, and says the values also travel back out. The heading gained "and granularities" with an explicit `{#pre-set-dashboard-filters-via-url}` anchor so the existing link from `events.mdx` keeps resolving. Companion to cubedevinc/cubejs-enterprise#14497 (CUB-4198), which added the outbound half for time granularity — a viewer's granularity pick now reaches the URL the way a filter pick already did.

mintlify · 2026-08-28T19:12:07Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cubed3	🟢 Ready	View Preview	Aug 28, 2026, 7:13 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

claude · 2026-08-28T19:12:20Z

Claude finished @mngr's task in 1m 47s —— View job

Review: docs-only, no blockers — 2 medium, 3 low, all inline

Full review — findings, verification notes, and checklist

Checklist

Gather context (diff vs origin/master, both changed files, root + docs-mintlify CLAUDE.md)
Verify every anchor the new prose links to actually exists
Check the preserved embed anchor against all inbound links
Cross-check claims against the rest of the docs for internal contradictions
Post inline findings
Check for stale prior threads to resolve (none exist — first review on this PR)

What's good

The heading rename keeps its old anchor via Mintlify's explicit {#…} syntax, which is exactly what docs-mintlify/CLAUDE.md prescribes for anchor stability. I verified the one inbound link — embedding/iframe/events.mdx:426 — still resolves, and that no other file references it.
All six intra-page anchors used by the new section resolve to real headings in controls.mdx (#filter, #time-granularity-switcher, #parent, #default-granularity, #user-attribute-default, #allowed-granularities).
The two pages are now genuinely bidirectional, and the "what does not travel" framing is the useful half — the user-attribute bullet in particular documents a privacy-relevant behavior that a reader would otherwise have to guess at.
No docs.json change needed (no new pages), and the changes land only in /docs-mintlify per repo policy.

Findings

#	Sev	File	Issue
1	Medium	`controls.mdx:170-173` (and `dashboards.mdx:74-75`)	Granularity list omits `second`/`minute`/`hour`, contradicting Allowed granularities on the same page
2	Medium	`controls.mdx:192-193`	"Published dashboards only" reads as scoping the whole feature; the embed page says it works on both. Both true (outbound vs inbound) but the direction isn't stated
3	Low	`controls.mdx:190-191`	Parent controls: silent on what the recipient's parent dropdown shows, since there's no `p_…` parameter
4	Low	`controls.mdx:176`	Link text no longer matches the heading this PR renames
5	Low	`dashboards.mdx:79-81`	Percent-encoding of the JSON filter value is undocumented — pre-existing, but this section is now the canonical hand-written-URL reference

Nit not worth an inline comment: the new section hard-wraps at ~80 columns while the surrounding prose in controls.mdx uses one long line per paragraph. Harmless, but it makes future diffs in this file inconsistent.

Scope note

The behavioral claims (which values get serialized, the allowedGrains gate) originate in cubedevinc/cubejs-enterprise#14497, which isn't in this repo — I could not verify them against source. The PR description says they were checked against the shipped code and driven end-to-end, so I've reviewed them for internal consistency and reader-facing clarity rather than re-deriving them. Finding #3 is the one place I'd want that confirmation before the wording lands.

· branch [`docs/dashboard-control-url-state`](https://github.com/cube-js/cube/tree/docs/dashboard-control-url-state)

Follow-up to #11687, which I merged on green checks before reading the review that had landed two minutes earlier. All five findings hold; four are mine, one is pre-existing. - The granularity list said `day`…`year`, contradicting *Allowed granularities* on the same page: `second`, `minute` and `hour` are offered for `TIMESTAMP` / `DATETIME` dimensions, so a reader building an hourly `tg_` link would have concluded the parameter couldn't express it. Both pages now name the sub-day grains and point at the switcher's allowed list as the authority. - "Published dashboards only" read as scoping the whole feature, contradicting the embed page's "works on both regular and published dashboards". Both are true — the restriction is on the outbound write, not the inbound read — so the bullet now says which direction it constrains. - The section said the children's values travel but not what the recipient's PARENT dropdown shows. Confirmed against the implementation: a parent's selection is runtime-only state and never serialized, so it falls back to the widget's saved `defaultOptionId`. Documented, because a recipient seeing the children set while the parent reads something else looks like a bug. - The link text still said "Pre-set dashboard filters via URL" after this work renamed that heading to include granularities. - The embed example carries raw `{`, `"` and `}`. Pre-existing, but that section is now the canonical reference for hand-written links, so it says to percent-encode when building the URL programmatically. Also unwrapped the new prose to one paragraph per line, matching the rest of `controls.mdx` (the hard-wrapped block would have made every later diff there noisier).

* docs(dashboards): address the review on the control-URL section Follow-up to #11687, which I merged on green checks before reading the review that had landed two minutes earlier. All five findings hold; four are mine, one is pre-existing. - The granularity list said `day`…`year`, contradicting *Allowed granularities* on the same page: `second`, `minute` and `hour` are offered for `TIMESTAMP` / `DATETIME` dimensions, so a reader building an hourly `tg_` link would have concluded the parameter couldn't express it. Both pages now name the sub-day grains and point at the switcher's allowed list as the authority. - "Published dashboards only" read as scoping the whole feature, contradicting the embed page's "works on both regular and published dashboards". Both are true — the restriction is on the outbound write, not the inbound read — so the bullet now says which direction it constrains. - The section said the children's values travel but not what the recipient's PARENT dropdown shows. Confirmed against the implementation: a parent's selection is runtime-only state and never serialized, so it falls back to the widget's saved `defaultOptionId`. Documented, because a recipient seeing the children set while the parent reads something else looks like a bug. - The link text still said "Pre-set dashboard filters via URL" after this work renamed that heading to include granularities. - The embed example carries raw `{`, `"` and `}`. Pre-existing, but that section is now the canonical reference for hand-written links, so it says to percent-encode when building the URL programmatically. Also unwrapped the new prose to one paragraph per line, matching the rest of `controls.mdx` (the hard-wrapped block would have made every later diff there noisier). * docs(embedding): finish the direction, encoding and link fixes Three low-severity follow-ups from the review of the previous commit, all on the embed page and all in text this work already touched: - The "reverse direction works too" paragraph still claimed write-back without the published-only qualifier — the same contradiction the controls page just had fixed on its read side, surviving here on the write side. - The percent-encoding note pointed at "constructing the URL programmatically", but the failure a reader will actually hit is pasting the example into the `src="…"` of the iframe snippet directly above it, where the raw quote closes the attribute and truncates the URL. Says that instead. - "the switcher's allowed granularities" is now a link, as it already is in the parallel sentence on the controls page; a reader here had no way to reach the list. --------- Co-authored-by: Gleb <gleb@unknownd2d4c7120595.localdomain>

mngr requested a review from keydunov as a code owner August 28, 2026 19:12

github-actions Bot added the pr:community Contribution from Cube.js community members. label Aug 28, 2026

mintlify Bot deployed to staging - docs-mintlify August 28, 2026 19:13 View deployment