Merge pull request 'docs(va): in-report screenshots for the mapping and the banner' (#30) from docs/va-in-report-images into main

Reviewed-on: #30

docs/deploy-viya.md

@@ -175,4 +175,4 @@ It is possible to embed a Data Controller table within SAS Visual Analytics by s
 
 To make the portlet more visually appealing, the Data Controller title bar can be removed by adding `?embed=true` to the URL.  When opening in a new window, the title bar will be gone.
 
-For a deeper VA integration - where report row selections drive filters and column visibility in the Data Controller editor - append `?embed=va` instead.  See the [SAS Visual Analytics Embed](/embed-va/) page for details on filter modes, configuration, and debugging.
+For a deeper VA integration - where report row selections drive filters and column visibility in the Data Controller editor - append `?embed=va` instead.  See the [SAS Visual Analytics Embed](/visual-analytics/) page for details on filter modes, configuration, and debugging.

docs/filter.md

@@ -7,7 +7,7 @@ og_image:  https://docs.datacontroller.io/img/filter_dynamic_on.png
 
 # Filtering
 
-Data Controller for SAS® enables you to create complex table filters. The "dynamic" setting enables the dropdown values to be pre-filtered by previous filter clauses.  Filtered views are shareable!  They are also used when [embedded in VA.](/embed-va)
+Data Controller for SAS® enables you to create complex table filters. The "dynamic" setting enables the dropdown values to be pre-filtered by previous filter clauses.  Filtered views are shareable!  They are also used when [embedded in VA.](/visual-analytics/)
 
 The clause shown above the grid is the resolved WHERE clause that was applied, so it uses SAS syntax - a date, datetime or time filter reads as a SAS literal, eg `SOME_DATE = '20APR2042'd`, rather than the internal day or second count.
 

docs/index.md

@@ -42,7 +42,7 @@ Data Controller is regularly updated with new features.  If you see something th
 * [Row Level Security](/row-level-security)
 * Excel [formula support](excel)
 * Dynamic [cell dropdown](/dynamic-cell-dropdown)
-* [SAS Visual Analytics embed](/embed-va/) - drive the editor from VA report selections
+* [SAS Visual Analytics embed](/visual-analytics/) - drive the editor from VA report selections
 * Works on ALL flavours of SAS (Base, EBI, Viya)
 
 

docs/visual-analytics.md

@@ -1,7 +1,9 @@
 ---
 layout: article
 title: SAS Visual Analytics Embed
-description: Embed the Data Controller editor inside a SAS VA report as a data-driven content object.  Row selections in the VA report drive filters and column visibility in the editor.
+description: Embed the Data Controller editor inside a SAS Visual Analytics report as a data-driven content object, so report selections drive filters and column visibility in the editor.
+og_title: Embedding Data Controller in SAS Visual Analytics
+og_image: https://docs.datacontroller.io/img/va-embed-og.png
 ---
 
 # Embedding inside SAS Visual Analytics
@@ -48,6 +50,10 @@ VA pushes a JSON payload to the iframe via `window.postMessage` whenever the sel
 
 If VA sends an empty / unmatched message the editor falls back to the unfiltered view but stays in VA mode.
 
+In the report below, two report parameters - `SOME_DROPDOWN` and `SOME_DATE` - reach one Data Controller object, and the editor shows both the combined filter and the rows it matches:
+
+![A value and a date parameter filtering the embedded editor](img/va-report-filters.png)
+
 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
@@ -67,7 +73,7 @@ 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:
+The applied filter is visible in the editor, above the grid - here the parameter `DROPDOWN_TAB1` filtering `SOME_DROPDOWN`, which is not its name (the date parameter beside it is name-matched, which is the default):
 
 ![A va_parmap mapping filtering a column](img/va-parmap-filtered.png)
 
@@ -114,11 +120,7 @@ A mapping can resolve the parameter value through a **named date anchor** before
 https://yourserver/DC/#/editor/<library>/<table>?embed=va&va_parmap=SELECTED_DATE-D_DATE:ADD(QUARTER_START,-1)
 ```
 
-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)
+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.
 
 The clause carries both values, so the row for the selected date and the row for the previous quarter are both included.
 
@@ -166,6 +168,10 @@ The mapping lives entirely in the URL of the report object, so the job is to get
 
     Everything before the `#` is the normal deployment URL; the `#/editor/...` part is the DC route, and `?embed=va` plus the `va_parmap` entries are what this page describes.  One object per report tab, each with its own entry, is what lets two tabs filter the same column differently.
 
+    The URL is a property of the object, not a data source: it lives in **Options > Web Content > URL**, and the object needs no data assigned for Data Controller to open its own table.  In the designer that section looks like this (the field is scrolled to the end of a long URL):
+
+    ![The Web Content URL property on a Data-driven content object](img/va-report-object-options.png)
+
 3. **Make the parameter reach the object.**  VA sends an object only the parameters its query uses.  A report parameter that the object's data does not reference never arrives, and the mapping then has nothing to map - DC reports it as `VA is not sending ...` in the banner.  So bind the parameter into the object (assign it as a source on the object's query, as you would for any other visual), rather than only defining it at report level.
 
 4. **Save the report**, then open it.  DC shows the applied filter above the grid, so a correct mapping is visible without opening the editor:
@@ -174,6 +180,12 @@ The mapping lives entirely in the URL of the report object, so the job is to get
     FILTER : ( ( REGION = 'Europe' ) )
     ```
 
+    A date parameter arrives as a display date and is rendered as a SAS date literal, the same as a date filter built inside Data Controller:
+
+    ```text
+    FILTER : ( ( SOME_DROPDOWN = 'Option 1' AND SOME_DATE BETWEEN '01JAN1960'd AND '31MAR1960'd ) )
+    ```
+
     Something wrong shows the banner instead, with the cause and the fix - see [When a mapping cannot be used](#when-a-mapping-cannot-be-used) above.
 
 !!! note
@@ -183,7 +195,9 @@ The mapping lives entirely in the URL of the report object, so the job is to get
 
 The object runs as the person **viewing** the report, using their SAS identity - there is no service account behind it. That person must therefore be a registered Data Controller user: if they are not, DC shows its login card inside the object instead of the editor, which looks like a broken embed rather than a permissions matter.
 
-Register everyone who will open the report before you ship it (Users in DC), and test the report as one of them rather than as the person who built it - the author is usually an administrator, so a report that works for them can fail for everyone else.
+Register everyone who will open the report before you ship it (Users in DC), and test the report as one of them rather than as the person who built it - the author often has elevated permissions, so a report that works for them can fail for everyone else.
+
+The deployment itself has to be licensed and past its End User License Agreement before it is embedded, for the same reason: an unlicensed instance shows the licensing screen (the agreement, then the free tier until a key is uploaded) inside the object, which reads as a broken embed rather than as setup that was never finished.  Accept the agreement and register the key by opening the deployment directly, then reload the report.
 
 ## Debugging
 
@@ -194,3 +208,5 @@ The following snippet can be used in console to dump the values being provided t
 ```
 console.log(JSON.stringify(window.__vaLastMessage?.data, null, 2))
 ```
+
+Each entry in its `parameters` array carries a `label`, and that label is what a `va_parmap` entry has to match (and what the name match uses when there is no entry).  When a mapping appears to do nothing, compare the labels in this dump with the left-hand side of the entries in the object's URL - a parameter that VA labels differently from what was typed in the URL is silently a different parameter.

mkdocs.yml

@@ -73,7 +73,7 @@ nav:
     - Selectboxes: dcc-selectbox.md
     - Tables: dcc-tables.md
     - Validations: dcc-validations.md
-    - Visual Analytics: embed-va.md
+    - Visual Analytics: visual-analytics.md
 - Macros: macros.md
 - Installation:
     - System Requirements: dci-requirements.md
@@ -113,6 +113,7 @@ plugins:
       redirect_maps:
           'dci-evaluation.md': 'dci-deploysas9.md'
           'dcu-fileupload.md': 'files.md'
+          'embed-va.md': 'visual-analytics.md'
 
 # Repository
 repo_name: 'dc/docs.datacontroller.io'