From b88002a752d34d44c43e0af7412b9616f8a4dc08 Mon Sep 17 00:00:00 2001 From: dc Date: Wed, 28 Oct 2026 10:47:14 +0000 Subject: [PATCH] docs(embed): document va_parmap, the mapping warnings and the Filter button per mode The SAS Visual Analytics Embed page now covers mapping report parameters to DC columns from the URL, which the name-based match cannot do for two report objects filtering the same column from differently-named parameters. - new "Mapping parameters to columns" section: the `va_parmap` grammar, the lower-case example, what overrides what, and the rules that matter to a report author (last-hyphen split, label-then-name key matching, one parameter to one column, no fallback to the name match) - the warning banner is documented next to it, including that a parameter is ignored rather than filtered on the wrong column - the `?embed=` table now shows the Filter button per mode, so it is explicit that `embed=true` keeps Data Controller's own filter builder while `embed=va` hands filtering to the report --- docs/embed-va.md | 44 +++++++++++++++++++++++++++++++++++++++----- 1 file changed, 39 insertions(+), 5 deletions(-) diff --git a/docs/embed-va.md b/docs/embed-va.md index 5615eea..b276af9 100644 --- a/docs/embed-va.md +++ b/docs/embed-va.md @@ -20,11 +20,13 @@ Open the editor as a DDC by appending `?embed=va` to the editor route: The `?embed=` parameter accepts three values: -| Value | Behaviour | -|---|---| -| `true` | Chrome (header, back button, sub-nav) is hidden. Editor functions normally. | -| `va` | Same chrome-hiding as `true`, **plus** editor becomes "VA-aware" - any report filters are captured, and columns can be displayed / hidden using the Edit Report interface. Filter button is disabled (use VA filters instead)| -| `false` (or omitted) | Standard interactive UI. | +| Value | Chrome | Filter button | +|---|---|---| +| `true` | hidden | **shown** - Data Controller's own filter builder works as usual | +| `va` | hidden | **hidden** - filtering comes from the report instead (see below) | +| `false` (or omitted) | shown | shown | + +Chrome means the header, the back button and the sub-nav. In `va` mode the editor is also VA-aware: the report's filters are captured and applied as you change selections, and the columns the grid shows can be controlled from the report's Edit Report interface. Because the report owns the filter in that mode, Data Controller's own **Filter** button is not offered - use the report's controls instead. ## How VA drives the editor @@ -38,6 +40,38 @@ If VA sends an empty / unmatched message the editor falls back to the unfiltered More logic available in [`va-messaging.service.ts'](https://git.datacontroller.io/dc/dc/src/branch/main/client/src/app/services/va-messaging.service.ts). +## Mapping parameters to columns + +By default each VA `parameter` is matched to a DC column by name: a parameter whose label is a column of the table filters that column. That means two DC instances in the same report can only filter the same column from a parameter of the same name - so two report tabs cannot hold different filters on one column. + +The `va_parmap` URL parameter overrides the name match, one entry per mapping, `-`: + +```text +https://yourserver/DC/#/editor//?embed=va&va_parmap=REGION_TAB1-REGION +``` + +Repeat the parameter to add mappings. A report with two tabs, each holding its own instance of the same table and filtering the same column from its own report parameter: + +| Report tab | DDC URL | +|---|---| +| Tab 1 | `...?embed=va&va_parmap=REGION_TAB1-REGION` | +| Tab 2 | `...?embed=va&va_parmap=REGION_TAB2-REGION` | + +The mapping is per parameter, and additive: + +- a mapped parameter always filters the column it names; that column's type in the table decides how the value is formatted, exactly as for a name match +- a parameter with no mapping keeps the default name match, so a single instance can mix mapped and unmapped parameters +- the key is matched case-insensitively against the parameter's label, then against its internal name (e.g. `pr273`) +- an entry is split at its last `-`, so a label may itself contain hyphens (`Sales-2024-DEPT` maps the label `Sales-2024` to `DEPT`) +- if the named column is not in the table being opened, the parameter is ignored rather than falling back to the name match - a typo cannot silently filter the wrong column +- a column name that is not a plain SAS name is ignored +- the mapping applies to filtering only; which columns the grid displays still follows the columns VA sends + +If an entry cannot be used the editor shows a warning banner above the grid naming the parameter, the column and the table - for example when the column is not in the table being opened, or the entry is not in the `parameter-column` form. The parameter is then ignored rather than falling back to the name match, so a typo never silently filters the wrong column, and the banner is what distinguishes "the mapping is wrong" from a view that simply has no filter. + +!!! note + A parameter label containing `&` must be percent-encoded (`%26`), because `&` separates query parameters. A space may be written as `+` or `%20`. + ## Filter Modes When running in `embed=va` mode, the editor provides two filter modes, controlled by the **Auto-apply** checkbox: