From 17bdecff897076a6bc842a6039d2e310e5f59ba0 Mon Sep 17 00:00:00 2001 From: dc Date: Wed, 28 Oct 2026 10:51:37 +0000 Subject: [PATCH] docs(embed): describe everything va mode changes, not just the Filter button --- docs/embed-va.md | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/docs/embed-va.md b/docs/embed-va.md index c77dfb4..26fee23 100644 --- a/docs/embed-va.md +++ b/docs/embed-va.md @@ -20,15 +20,25 @@ Open the editor as a DDC by appending `?embed=va` to the editor route: The `?embed=` parameter accepts three values: -| 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 | +| Value | Chrome | Filter button | Report drives filtering and columns | +|---|---|---|---| +| `true` | hidden | **shown** - Data Controller's own filter builder works as usual | no | +| `va` | hidden | **hidden** - filtering comes from the report instead | yes | +| `false` (or omitted) | shown | shown | no | -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. +Chrome means the header, the back button and the sub-nav. -The two are not combined. A filter built inside Data Controller and a filter driven by the report are alternatives, not layers: applying one replaces the other, and in `va` mode the report's filter is re-applied the next time the selection changes. Showing the button there would offer a filter that silently stops applying as soon as the report is touched, which is why it is hidden rather than disabled. If you need Data Controller's own filtering, embed with `embed=true` (or with no `embed` parameter) and leave the report's parameters unassigned. +`embed=true` hides the chrome and nothing else: the editor behaves exactly as it does outside a report, including the Filter button, Add Record, and any filtering you apply yourself. + +`embed=va` hides the same chrome **and** hands these over to the report: + +- **filtering** - the report's filters are captured and applied as selections change, in either live mode or confirm mode (see Filter Modes below). The first table load is already filtered, so there is no unfiltered flash. +- **column visibility** - the grid shows the columns the report sends, controlled from the report's Edit Report interface; primary-key columns are always kept visible. +- **the Filter button is not offered** - filtering belongs to the report in this mode. +- **Add Record is not offered** - rows are still added from Edit mode's "Add Row". +- **a "Back to Edit table" bar** appears on the stage, approve and review pages, so a user who follows the review workflow can return to the editor without knowing Data Controller's page paths. + +The two filters are not combined. A filter built inside Data Controller and a filter driven by the report are alternatives, not layers: applying one replaces the other, and in `va` mode the report's filter is re-applied the next time the selection changes. Showing the button there would offer a filter that silently stops applying as soon as the report is touched, which is why it is hidden rather than disabled. ## How VA drives the editor