DisyInformationssysteme · Tobias43 · Nov 21, 2023 · Nov 16, 2023
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
+### Added
+- `filter` option for `CadenzaClient#show` and `CadenzaClient#showMap`
 
 ## 1.6.0 - 2023-11-17
 ### Changed

diff --git a/README.md b/README.md
@@ -71,14 +71,17 @@ const cadenza = window.cadenza.noConflict();
 
 <small>API: [CadenzaClient#show](./classes/CadenzaClient.html#show)</small>
 
-Show an embedding target in an iframe and hide Cadenza's main header and footer as well as the workbook toolbar. Additionally, enable simplified operation mode and disable the designer.
+Show an embedding target in an iframe and hide Cadenza's main header and footer as well as the workbook toolbar. Additionally, enable simplified operation mode, disable the designer and set the filter variable "var1" to "foo".
 
 ```javascript
 cadenzaClient.show('{embeddingTargetId}', {
   hideMainHeaderAndFooter: true,
   hideWorkbookToolBar: true,
   operationMode: 'simplified',
-  disabledUiFeatures: ['workbook-design']
+  disabledUiFeatures: ['workbook-design'],
+  filter: {
+    var1: 'foo'
+  }
 });
 ```
 

diff --git a/sandbox.html b/sandbox.html
@@ -129,7 +129,8 @@
       minScale,
       parts,
       simplifiedOperationMode,
-      useMapSrs
+      useMapSrs,
+      filter
     }) {
       return {
         disabledUiFeatures: disabledUiFeatures && disabledUiFeatures.split(','),
@@ -145,9 +146,22 @@
         minScale,
         parts: parts && parts.split(','),
         ...(simplifiedOperationMode === 'on' && { operationMode: 'simplified' }),
-        useMapSrs: useMapSrs === 'on'
+        useMapSrs: useMapSrs === 'on',
+        filter: filter && parseFilterVariables(filter)
       };
     }
+
+    function parseFilterVariables (filterString) {
+      return JSON.parse(filterString, (_, value) => {
+        if (value === '{{currentDate}}') { // convenience for current date
+          return new Date();
+        }
+        if (value.match?.(/....-..-..T..:..:..\....Z/)) {
+          return new Date(value);
+        }
+        return value;
+      });
+    }
   </script>
 </head>
 <body>
@@ -212,6 +226,10 @@
     <label for="disabledUiFeatures">Disabled UI features</label>
     <input name="disabledUiFeatures" id="disabledUiFeatures" placeholder="feature1,feature2...">
   </div>
+  <div>
+    <label for="filter">Filter</label>
+    <input name="filter" id="filter" placeholder='{ "textvar": "foo", "numbervar": 42.0, "datevar1": "2000-01-01T00.000Z", "datevar2": "{{currentDate}}" }'>
+  </div>
 </template>
 
 <template id="common-map">

diff --git a/src/cadenza.js b/src/cadenza.js
@@ -85,6 +85,9 @@ globalThis.cadenza = Object.assign(
  */
 /** @typedef {'columns' | 'values' | 'totals'} TablePart - A part of a table to export. */
 
+/**
+ * @typedef {Record<string, string | number | Date>} FilterVariables - Filter variable values
+ */
 /**
  * _Notes:_
  * * Most public methods can be aborted using an [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal).
@@ -182,6 +185,8 @@ export class CadenzaClient {
    * @param {object} [options]
    * @param {UiFeature[]} [options.disabledUiFeatures] - Cadenza UI features to disable
    * @param {boolean} [options.expandNavigator] - Indicates if the navigator should be expanded.
+   * @param {FilterVariables} [options.filter] - Filter variables. The keys should contain the
+   *     filter variable names and the values the filter variable values.
    * @param {boolean} [options.hideMainHeaderAndFooter] - Whether to hide the main Cadenza header and footer
    * @param {boolean} [options.hideWorkbookToolBar] - Whether to hide the workbook toolbar
    * @param {GlobalId} [options.highlightGlobalId] - The ID of an item to highlight / expand in the navigator
@@ -198,6 +203,7 @@ export class CadenzaClient {
     {
       disabledUiFeatures,
       expandNavigator,
+      filter,
       hideMainHeaderAndFooter,
       hideWorkbookToolBar,
       highlightGlobalId,
@@ -222,6 +228,7 @@ export class CadenzaClient {
     const params = createParams({
       disabledUiFeatures,
       expandNavigator,
+      filter,
       hideMainHeaderAndFooter,
       hideWorkbookToolBar,
       highlightGlobalId,
@@ -240,6 +247,8 @@ export class CadenzaClient {
    * @param {object} [options] - Options
    * @param {UiFeature[]} [options.disabledUiFeatures] - Cadenza UI features to disable
    * @param {boolean} [options.expandNavigator] - Indicates if the navigator should be expanded.
+   * @param {FilterVariables} [options.filter] - Filter variables. The keys should contain the
+   *     filter variable names and the values the filter variable values.
    * @param {Geometry} [options.geometry] - A geometry to show on the map
    * @param {boolean} [options.hideMainHeaderAndFooter] - Whether to hide the main Cadenza header and footer
    * @param {boolean} [options.hideWorkbookToolBar] - Whether to hide the workbook toolbar
@@ -257,6 +266,7 @@ export class CadenzaClient {
     {
       disabledUiFeatures,
       expandNavigator,
+      filter,
       geometry,
       hideMainHeaderAndFooter,
       hideWorkbookToolBar,
@@ -275,6 +285,7 @@ export class CadenzaClient {
     const params = createParams({
       disabledUiFeatures,
       expandNavigator,
+      filter,
       hideMainHeaderAndFooter,
       hideWorkbookToolBar,
       highlightGlobalId,
@@ -584,7 +595,7 @@ function resolvePath(
 ) {
   if (typeof source === 'string') {
     assert(
-      validEmbeddingTargetId(source),
+      validKebabCaseString(source),
       `Invalid embedding target ID: ${source}`,
     );
     return `/w/${source}`;
@@ -636,7 +647,7 @@ function validPageName(/** @type string */ value) {
   return ['welcome'].includes(value);
 }
 
-function validEmbeddingTargetId(/** @type string */ value) {
+function validKebabCaseString(/** @type string */ value) {
   return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value);
 }
 
@@ -709,6 +720,8 @@ function assertSupportedMediaType(
  * @param {UiFeature[]} [params.disabledUiFeatures]
  * @param {boolean} [params.expandNavigator]
  * @param {string} [params.fileName]
+ * @param {FilterVariables} [params.filter] - Filter variables. The keys should contain the filter
+ *     variable names and the values the filter variable values.
  * @param {GeometryType} [params.geometryType]
  * @param {boolean} [params.hideMainHeaderAndFooter]
  * @param {boolean} [params.hideWorkbookToolBar]
@@ -726,8 +739,10 @@ function assertSupportedMediaType(
  */
 function createParams({
   action,
+  disabledUiFeatures,
   expandNavigator,
   fileName,
+  filter,
   geometryType,
   hideMainHeaderAndFooter,
   hideWorkbookToolBar,
@@ -741,7 +756,6 @@ function createParams({
   useMapSrs,
   webApplication,
   operationMode,
-  disabledUiFeatures,
 }) {
   if (disabledUiFeatures) {
     disabledUiFeatures.forEach((feature) =>
@@ -762,6 +776,14 @@ function createParams({
       assert(validTablePart(part), `Invalid table part: ${part}`),
     );
   }
+  if (filter) {
+    Object.keys(filter).forEach((varName) =>
+      assert(
+        validKebabCaseString(varName),
+        `Invalid filter variable name: ${varName}`,
+      ),
+    );
+  }
   return new URLSearchParams({
     ...(action && { action }),
     ...(disabledUiFeatures && {
@@ -785,6 +807,13 @@ function createParams({
       webApplicationLink: webApplication.externalLinkId,
       webApplicationLinkRepository: webApplication.repositoryName,
     }),
+    ...(filter &&
+      Object.fromEntries(
+        Object.entries(filter).map(([variable, value]) => [
+          `filter.${variable}`,
+          JSON.stringify(value instanceof Date ? value.toISOString() : value),
+        ]),
+      )),
   });
 }