design: name the URL parameters once - a dc_ prefix, and flags instead of the embed enum #384

New Issue

2026-10-28T10:56:45Z

hermes commented

2026-10-28 10:56:45 +00:00

Context

The URL parameters Data Controller reads from the hash query have grown by accretion, and two of them now encode decisions that will be hard to change later. This issue proposes naming them once, before more are added.

Measured from the code (client, main as of this issue):

Parameter	Parsed in	Values	What it does
`embed`	`parse-embed-param.ts`, `app.component.ts`	`true` / `va` / `false`	hides the Data Controller header and navigation; `va` additionally switches on report-driven filtering and column visibility
`labels`	`parse-labels-param.ts` (editor + viewer)	`true` / `false`	shows column labels instead of names
`va_parmap`	`parse-va-parmap.ts`	repeated `<param>-<column>`	maps report parameters to DC columns (dc#383)
`viewboxes`	`viewboxes.component.ts`	id	opens a saved viewbox
`max_depth`	`lineage.component.ts`	number	lineage depth
`force`	`licensing.guard.ts`	presence	bypasses the licence gate

Two naming styles are already in use (labels, viewboxes; max_depth, va_parmap), and three of the names are generic enough to collide with anything else living in the same hash (force, labels, error/details are the licence page's). va_parmap picked up a prefix by accident of provenance rather than by policy.

Problem 1 - `embed` is an enum of two independent decisions

embed currently answers two questions at once:

header and navigation:   hidden | shown
who filters:             Data Controller | the report

true describes neither (it reads as "embed: yes"), and va names a product rather than a behaviour. The combination matrix the code supports today is only two of the four cells:

	DC filters	report filters
header hidden	`embed=true`	`embed=va`
header shown	(default, no param)	not expressible

The missing cell - header visible but the report drives filtering - is the one a report author is most likely to want next (they get report-driven filtering without losing Data Controller's own navigation).

Problem 2 - unprefixed, generic names

Everything DC reads comes from the same hash query as the hosting page, so a generic name is a future collision. va_parmap was prefixed; labels and force were not.

Proposal A - separate flags, with defaults that preserve today's behaviour

Two flags rather than one enum:

Parameter	Values	Default	Effect
`dc_header`	`true` / `false`	hidden when `embed` is truthy	title bar, user menu, sub-nav, and the header's own back arrow
`dc_filter`	`va` / `dc`	`va` when `embed=va`, else `dc`	whether the report drives filtering, or Data Controller does

With those defaults, ?embed=va resolves to dc_header=false&dc_filter=va and ?embed=true to dc_header=false&dc_filter=dc, so every existing URL keeps working unchanged and only URLs that use the new flags get new behaviour.

Two deliberate non-goals in that shape:

no showback flag. "Back" already exists in two places: an arrow inside the header (so it follows dc_header) and the "Back to Edit table" bar, which exists precisely because the stage/approve/review pages have no header in embed mode. A third flag would have to define what dc_header=true&showback=false looks like (a header with a hole in it). If control over the bar itself is wanted, dc_backbar is the honest name for that bar only.
no dc_filter=none. "No filtering at all" is a third value with no current use case; dc_filter=dc already means the report's parameters are ignored.

The one genuinely new behaviour

dc_filter=dc inside a report means Data Controller ignores the report entirely: no postMessage listener, no deferred first load, no mapping banner, and va_parmap inert. That is a small change (three entry points in editor.component.ts) but it is the risky part: a listener left running would keep replacing whatever filter the user applied, which is exactly the failure mode dc#383 spent four review rounds closing.

Proposal B - prefix every URL variable

dc_embed, dc_labels, dc_parmap, dc_viewboxes, dc_max_depth, dc_force - with the unprefixed names kept as permanent aliases (parsers accept both, docs prefer the prefixed form). No deprecation window, no URL breakage.

This also settles the style: _ separator, lower case, always dc_.

va_parmap becomes dc_parmap (accepting va_parmap as an alias), which is more accurate anyway - the mapping is a Data Controller feature that happens to be configured from a report URL.

Test matrix (mocked estate, no VA instance needed)

The DDC message is just a postMessage, so every row is coverable in Cypress against the mocks:

embed=true - header hidden, DC filters (today's behaviour)
embed=va - header hidden, report filters, back bar on a stage page (today's behaviour)
dc_header=true&dc_filter=va - header visible, report still filters
dc_filter=dc with a pushed message - grid stays unfiltered, no banner
dc_backbar=false - no bar on the stage page
prefixed and unprefixed forms of each var produce identical behaviour

Ordering

Proposal B is mechanical and testable and can land on its own. Proposal A changes the URL contract and touches the VA entry points, so it should not ride along with a release that is mid-flight.

Open questions

Is the missing cell (header visible + report filters) actually wanted, or is it a shape nobody will use?
Should the alias set include bare / ddc for readability (embed=ddc reads better than embed=va for a report author who knows the term "data-driven content")?
Is force meant to be user-typed at all, or an internal/testing hook that should stop being a public URL var?

## Context The URL parameters Data Controller reads from the hash query have grown by accretion, and two of them now encode decisions that will be hard to change later. This issue proposes naming them once, before more are added. Measured from the code (client, `main` as of this issue): | Parameter | Parsed in | Values | What it does | |---|---|---|---| | `embed` | `parse-embed-param.ts`, `app.component.ts` | `true` / `va` / `false` | hides the Data Controller header and navigation; `va` additionally switches on report-driven filtering and column visibility | | `labels` | `parse-labels-param.ts` (editor + viewer) | `true` / `false` | shows column labels instead of names | | `va_parmap` | `parse-va-parmap.ts` | repeated `<param>-<column>` | maps report parameters to DC columns (dc#383) | | `viewboxes` | `viewboxes.component.ts` | id | opens a saved viewbox | | `max_depth` | `lineage.component.ts` | number | lineage depth | | `force` | `licensing.guard.ts` | presence | bypasses the licence gate | Two naming styles are already in use (`labels`, `viewboxes`; `max_depth`, `va_parmap`), and three of the names are generic enough to collide with anything else living in the same hash (`force`, `labels`, `error`/`details` are the licence page's). `va_parmap` picked up a prefix by accident of provenance rather than by policy. ## Problem 1 - `embed` is an enum of two independent decisions `embed` currently answers two questions at once: ``` header and navigation: hidden | shown who filters: Data Controller | the report ``` `true` describes neither (it reads as "embed: yes"), and `va` names a product rather than a behaviour. The combination matrix the code supports today is only two of the four cells: | | DC filters | report filters | |---|---|---| | header hidden | `embed=true` | `embed=va` | | header shown | (default, no param) | not expressible | The missing cell - header visible but the report drives filtering - is the one a report author is most likely to want next (they get report-driven filtering without losing Data Controller's own navigation). ## Problem 2 - unprefixed, generic names Everything DC reads comes from the same hash query as the hosting page, so a generic name is a future collision. `va_parmap` was prefixed; `labels` and `force` were not. ## Proposal A - separate flags, with defaults that preserve today's behaviour Two flags rather than one enum: | Parameter | Values | Default | Effect | |---|---|---|---| | `dc_header` | `true` / `false` | hidden when `embed` is truthy | title bar, user menu, sub-nav, and the header's own back arrow | | `dc_filter` | `va` / `dc` | `va` when `embed=va`, else `dc` | whether the report drives filtering, or Data Controller does | With those defaults, `?embed=va` resolves to `dc_header=false&dc_filter=va` and `?embed=true` to `dc_header=false&dc_filter=dc`, so every existing URL keeps working unchanged and only URLs that use the new flags get new behaviour. Two deliberate non-goals in that shape: - **no `showback` flag.** "Back" already exists in two places: an arrow inside the header (so it follows `dc_header`) and the "Back to Edit table" bar, which exists precisely because the stage/approve/review pages have no header in embed mode. A third flag would have to define what `dc_header=true&showback=false` looks like (a header with a hole in it). If control over the bar itself is wanted, `dc_backbar` is the honest name for that bar only. - **no `dc_filter=none`.** "No filtering at all" is a third value with no current use case; `dc_filter=dc` already means the report's parameters are ignored. ### The one genuinely new behaviour `dc_filter=dc` inside a report means Data Controller ignores the report entirely: no postMessage listener, no deferred first load, no mapping banner, and `va_parmap` inert. That is a small change (three entry points in `editor.component.ts`) but it is the risky part: a listener left running would keep replacing whatever filter the user applied, which is exactly the failure mode dc#383 spent four review rounds closing. ## Proposal B - prefix every URL variable `dc_embed`, `dc_labels`, `dc_parmap`, `dc_viewboxes`, `dc_max_depth`, `dc_force` - with the unprefixed names kept as permanent aliases (parsers accept both, docs prefer the prefixed form). No deprecation window, no URL breakage. This also settles the style: `_` separator, lower case, always `dc_`. `va_parmap` becomes `dc_parmap` (accepting `va_parmap` as an alias), which is more accurate anyway - the mapping is a Data Controller feature that happens to be configured from a report URL. ## Test matrix (mocked estate, no VA instance needed) The DDC message is just a `postMessage`, so every row is coverable in Cypress against the mocks: 1. `embed=true` - header hidden, DC filters (today's behaviour) 2. `embed=va` - header hidden, report filters, back bar on a stage page (today's behaviour) 3. `dc_header=true&dc_filter=va` - header visible, report still filters 4. `dc_filter=dc` with a pushed message - grid stays unfiltered, no banner 5. `dc_backbar=false` - no bar on the stage page 6. prefixed and unprefixed forms of each var produce identical behaviour ## Ordering Proposal B is mechanical and testable and can land on its own. Proposal A changes the URL contract and touches the VA entry points, so it should not ride along with a release that is mid-flight. ## Open questions - Is the missing cell (`header visible` + `report filters`) actually wanted, or is it a shape nobody will use? - Should the alias set include `bare` / `ddc` for readability (`embed=ddc` reads better than `embed=va` for a report author who knows the term "data-driven content")? - Is `force` meant to be user-typed at all, or an internal/testing hook that should stop being a public URL var?

hermes commented

2026-10-28 11:21:35 +00:00

Decision on the prefix (Proposal B): not doing it

The variables are scoped to Data Controller's own application - they live in the hash route (#/editor/LIB.TABLE?embed=va), which belongs to this app, not in the query string that SAS Job Execution (or any other host) also uses. So there is no shared namespace to prefix against, and va_parmap keeps its existing name.

Consequences, so this issue does not contradict itself:

the dc_-prefixed names in the body above are superseded - if flags are added they are header / filter, not dc_header / dc_filter
va_parmap ships as-is in dc#383 rather than being renamed while it is still unreleased

Still open from this issue:

the embed enum split (Proposal A): header / filter flags, with defaults reproducing today's URLs exactly. The one new display state is "the report drives filtering while the header stays visible"; the one new behaviour is filter=dc, i.e. the report's parameters are ignored entirely
whether embed should accept readable aliases at all (bare / ddc)
whether force is a public URL variable or an internal hook

## Decision on the prefix (Proposal B): not doing it The variables are scoped to Data Controller's own application - they live in the hash route (`#/editor/LIB.TABLE?embed=va`), which belongs to this app, not in the query string that SAS Job Execution (or any other host) also uses. So there is no shared namespace to prefix against, and `va_parmap` keeps its existing name. Consequences, so this issue does not contradict itself: - the `dc_`-prefixed names in the body above are superseded - if flags are added they are `header` / `filter`, not `dc_header` / `dc_filter` - `va_parmap` ships as-is in dc#383 rather than being renamed while it is still unreleased Still open from this issue: - the `embed` enum split (Proposal A): `header` / `filter` flags, with defaults reproducing today's URLs exactly. The one new display state is "the report drives filtering while the header stays visible"; the one new behaviour is `filter=dc`, i.e. the report's parameters are ignored entirely - whether `embed` should accept readable aliases at all (`bare` / `ddc`) - whether `force` is a public URL variable or an internal hook

allan closed this issue

2026-11-03 13:11:13 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: dc/dc#384

design: name the URL parameters once - a dc_ prefix, and flags instead of the embed enum #384