diff --git a/docs/embed-va.md b/docs/embed-va.md index 5739327..5e73a86 100644 --- a/docs/embed-va.md +++ b/docs/embed-va.md @@ -69,6 +69,10 @@ Repeat the parameter to add mappings. A report with two tabs, each holding its | Tab 1 | `...?embed=va&va_parmap=REGION_TAB1-REGION` | | Tab 2 | `...?embed=va&va_parmap=REGION_TAB2-REGION` | +The applied filter is visible in the editor, above the grid - here the parameter `DROPDOWN_TAB1` filtering `SOME_DROPDOWN`, which is not its name: + +![A va_parmap mapping filtering a column](img/va-parmap-filtered.png) + 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 @@ -79,7 +83,25 @@ The mapping is per parameter, and additive: - 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. +## When a mapping cannot be used + +A wrong mapping would otherwise look like a working filter over the whole table, so the editor puts a banner above the grid naming the parameter, the column, the table, and what to change: + +![The va_parmap warning banner](img/va-parmap-banner.png) + +Each line names one cause, and the parameter it concerns is skipped rather than falling back to the name match - a typo never silently filters the wrong column: + +| What the banner says | What it means | +|---|---| +| `is not a column of .` | the mapped column does not exist in the table being opened | +| `is not a date or datetime column` | a date anchor (`ADD`/`RANGE`) was applied to a column that holds something else | +| `VA is not sending` | no message has named that parameter - usually a spelling mistake in the parameter side of the entry | +| `all filter ... different values will show no rows` | two parameters map to one column with different values, so the AND can never match | +| `a range needs one value` | a `RANGE` mapping was sent several values - one `BETWEEN` carries one period | +| `N of its M values was not a date` | part of a multi-value parameter could not be read as a date, so only the rest is applied | +| `was ignored: it needs a "-"` / `is not a transform` | the entry itself is malformed | + +The banner is shown to the report author, inside the report, because that is where the entry is edited: the only fix available from the editor is to change the `va_parmap` entries in the URL of the Data Controller object. !!! note A parameter label containing `&` must be percent-encoded (`%26`), because `&` separates query parameters. A space may be written as `+` or `%20`. @@ -92,7 +114,13 @@ A mapping can resolve the parameter value through a **named date anchor** before https://yourserver/DC/#/editor//
?embed=va&va_parmap=SELECTED_DATE-D_DATE:ADD(QUARTER_START,-1) ``` -A report that sends `SELECTED_DATE = 01OCT2026` then filters `D_DATE` on 2026-10-01 **and** 2026-07-01 - the selected date's quarter, plus the same point one quarter earlier. +A report that sends `SELECTED_DATE = 27FEB1961` then filters `D_DATE` on 1961-02-27 **and** 1960-10-01 - the selected date, plus the same point one quarter earlier: + +In the screenshot below the mapping is `SELECTED_DATE-SOME_DATE:ADD(QUARTER_START,-1)` against the demo table, and the parameter sends 27FEB1961: + +![A date anchor applied to the filter](img/va-parmap-transform.png) + +The clause carries both values, so the row for the selected date and the row for the previous quarter are both included. | Transform | Result | Filter | |---|---|---| diff --git a/docs/img/va-parmap-banner.png b/docs/img/va-parmap-banner.png new file mode 100644 index 0000000..da8420a Binary files /dev/null and b/docs/img/va-parmap-banner.png differ diff --git a/docs/img/va-parmap-filtered.png b/docs/img/va-parmap-filtered.png new file mode 100644 index 0000000..03f5965 Binary files /dev/null and b/docs/img/va-parmap-filtered.png differ diff --git a/docs/img/va-parmap-transform.png b/docs/img/va-parmap-transform.png new file mode 100644 index 0000000..be4421b Binary files /dev/null and b/docs/img/va-parmap-transform.png differ