@disy/cadenza.js 1.6.0 → 1.8.0

package/cadenza.d.ts

@@ -68,6 +68,7 @@ export function cadenza(baseUrl: string, options?: {
  * See {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types}
  */
 /** @typedef {'columns' | 'values' | 'totals'} TablePart - A part of a table to export. */
+/** @typedef {Record<string, string | number | Date>} FilterVariables - Filter variable names and values */
 /**
  * _Notes:_
  * * Most public methods can be aborted using an [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal).
@@ -101,6 +102,7 @@ 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
      * @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
@@ -112,9 +114,10 @@ export class CadenzaClient {
      * @return {Promise<void>} A Promise for when the iframe is loaded
      * @throws For invalid arguments
      */
-    show(source: PageSource | WorkbookSource | WorksheetSource | WorkbookViewSource, { disabledUiFeatures, expandNavigator, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, labelSet, mediaType, operationMode, signal, }?: {
+    show(source: PageSource | WorkbookSource | WorksheetSource | WorkbookViewSource, { disabledUiFeatures, expandNavigator, filter, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, labelSet, mediaType, operationMode, signal, }?: {
         disabledUiFeatures?: UiFeature[] | undefined;
         expandNavigator?: boolean | undefined;
+        filter?: FilterVariables | undefined;
         hideMainHeaderAndFooter?: boolean | undefined;
         hideWorkbookToolBar?: boolean | undefined;
         highlightGlobalId?: string | undefined;
@@ -130,6 +133,7 @@ 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
      * @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
@@ -142,9 +146,10 @@ export class CadenzaClient {
      * @return {Promise<void>} A Promise for when the iframe is loaded
      * @throws For invalid arguments
      */
-    showMap(mapView: WorkbookViewSource, { disabledUiFeatures, expandNavigator, geometry, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, locationFinder, mapExtent, operationMode, useMapSrs, signal, }?: {
+    showMap(mapView: WorkbookViewSource, { disabledUiFeatures, expandNavigator, filter, geometry, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, locationFinder, mapExtent, operationMode, useMapSrs, signal, }?: {
         disabledUiFeatures?: UiFeature[] | undefined;
         expandNavigator?: boolean | undefined;
+        filter?: FilterVariables | undefined;
         geometry?: Geometry | undefined;
         hideMainHeaderAndFooter?: boolean | undefined;
         hideWorkbookToolBar?: boolean | undefined;
@@ -416,6 +421,10 @@ export type MediaType = string;
  * - A part of a table to export.
  */
 export type TablePart = 'columns' | 'values' | 'totals';
+/**
+ * - Filter variable names and values
+ */
+export type FilterVariables = Record<string, string | number | Date>;
 /**
  * - A Cadenza `postMessage()` event
  */

package/cadenza.js

@@ -74,6 +74,7 @@ globalThis.cadenza = Object.assign((/** @type Parameters<cadenza> */ ...args) =>
  * See {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types}
  */
 /** @typedef {'columns' | 'values' | 'totals'} TablePart - A part of a table to export. */
+/** @typedef {Record<string, string | number | Date>} FilterVariables - Filter variable names and values */
 /**
  * _Notes:_
  * * Most public methods can be aborted using an [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal).
@@ -149,6 +150,7 @@ 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
      * @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
@@ -160,7 +162,7 @@ export class CadenzaClient {
      * @return {Promise<void>} A Promise for when the iframe is loaded
      * @throws For invalid arguments
      */
-    show(source, { disabledUiFeatures, expandNavigator, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, labelSet, mediaType, operationMode, signal, } = {}) {
+    show(source, { disabledUiFeatures, expandNavigator, filter, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, labelSet, mediaType, operationMode, signal, } = {}) {
         this.#log('CadenzaClient#show', source);
         if (mediaType) {
             assertSupportedMediaType(mediaType, [MediaType.PDF]);
@@ -173,6 +175,7 @@ export class CadenzaClient {
         const params = createParams({
             disabledUiFeatures,
             expandNavigator,
+            filter,
             hideMainHeaderAndFooter,
             hideWorkbookToolBar,
             highlightGlobalId,
@@ -190,6 +193,7 @@ 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
      * @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
@@ -202,7 +206,7 @@ export class CadenzaClient {
      * @return {Promise<void>} A Promise for when the iframe is loaded
      * @throws For invalid arguments
      */
-    async showMap(mapView, { disabledUiFeatures, expandNavigator, geometry, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, locationFinder, mapExtent, operationMode, useMapSrs, signal, } = {}) {
+    async showMap(mapView, { disabledUiFeatures, expandNavigator, filter, geometry, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, locationFinder, mapExtent, operationMode, useMapSrs, signal, } = {}) {
         this.#log('CadenzaClient#showMap', mapView, geometry);
         if (geometry) {
             assertValidGeometryType(geometry.type);
@@ -210,6 +214,7 @@ export class CadenzaClient {
         const params = createParams({
             disabledUiFeatures,
             expandNavigator,
+            filter,
             hideMainHeaderAndFooter,
             hideWorkbookToolBar,
             highlightGlobalId,
@@ -475,7 +480,7 @@ export class CadenzaClient {
 function resolvePath(
 /** @type PageSource | WorkbookSource | WorksheetSource | WorkbookViewSource */ source) {
     if (typeof source === 'string') {
-        assert(validEmbeddingTargetId(source), `Invalid embedding target ID: ${source}`);
+        assert(validKebabCaseString(source), `Invalid embedding target ID: ${source}`);
         return `/w/${source}`;
     }
     else if ('page' in source) {
@@ -518,7 +523,7 @@ function validUrl(/** @type string */ value) {
 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);
 }
 function validRepositoryName(/** @type string */ value) {
@@ -578,6 +583,7 @@ function assertSupportedMediaType(
  * @param {UiFeature[]} [params.disabledUiFeatures]
  * @param {boolean} [params.expandNavigator]
  * @param {string} [params.fileName]
+ * @param {FilterVariables} [params.filter]
  * @param {GeometryType} [params.geometryType]
  * @param {boolean} [params.hideMainHeaderAndFooter]
  * @param {boolean} [params.hideWorkbookToolBar]
@@ -593,10 +599,13 @@ function assertSupportedMediaType(
  * @param {ExternalLinkKey} [params.webApplication]
  * @return {URLSearchParams}
  */
-function createParams({ action, expandNavigator, fileName, geometryType, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, labelSet, locationFinder, mapExtent, mediaType, minScale, parts, useMapSrs, webApplication, operationMode, disabledUiFeatures, }) {
+function createParams({ action, disabledUiFeatures, expandNavigator, fileName, filter, geometryType, hideMainHeaderAndFooter, hideWorkbookToolBar, highlightGlobalId, labelSet, locationFinder, mapExtent, mediaType, minScale, parts, useMapSrs, webApplication, operationMode, }) {
     if (disabledUiFeatures) {
         disabledUiFeatures.forEach((feature) => assert(validUiFeature(feature), `Invalid UI feature: ${feature}`));
     }
+    if (filter) {
+        Object.keys(filter).forEach((varName) => assert(validKebabCaseString(varName), `Invalid filter variable name: ${varName}`));
+    }
     if (geometryType) {
         assertValidGeometryType(geometryType);
     }
@@ -613,6 +622,11 @@ function createParams({ action, expandNavigator, fileName, geometryType, hideMai
         }),
         ...(expandNavigator && { expandNavigator: 'true' }),
         ...(fileName && { fileName }),
+        ...(filter &&
+            Object.fromEntries(Object.entries(filter).map(([variable, value]) => [
+                `filter.${variable}`,
+                JSON.stringify(value instanceof Date ? value.toISOString() : value),
+            ]))),
         ...(geometryType && { geometryType }),
         ...(hideMainHeaderAndFooter && { hideMainHeaderAndFooter: 'true' }),
         ...(hideWorkbookToolBar && { hideWorkbookToolBar: 'true' }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@disy/cadenza.js",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "license": "Apache-2.0",
   "repository": "github:DisyInformationssysteme/cadenza.js",
   "type": "module",

package/sandbox.html

@@ -28,7 +28,21 @@
     form, fieldset {
       display: flex;
       flex-direction: column;
-      gap: 16px;
+      gap: 12px;
+    }
+    fieldset > div {
+      display: flex;
+      flex-direction: column;
+      gap: 4px;
+    }
+    fieldset small {
+      display: flex;
+      flex-direction: column;
+      gap: 4px;
+
+      & > * {
+        margin-block: 0;
+      }
     }
     main {
       flex: 1;
@@ -57,11 +71,13 @@
       const action = actionSelect.value;
       const settingsTemplate = document.querySelector(`[data-action=${action}]`);
       settingsContainer.append(settingsTemplate.content.cloneNode(true));
-      const commonSettingsTemplate = document.getElementById(`common-${settingsTemplate.dataset.common}`);
-      if (commonSettingsTemplate) {
-        settingsContainer.append(
-          document.createElement('hr'),
-          commonSettingsTemplate.content.cloneNode(true));
+      if (settingsTemplate.dataset.common) {
+        settingsTemplate.dataset.common.split(',').forEach(commonId => {
+          const commonSettingsTemplate = document.getElementById(`common-${commonId}`);
+          settingsContainer.append(
+            document.createElement('hr'),
+            commonSettingsTemplate.content.cloneNode(true));
+        })
       }
 
       const data = localStorage.getItem(`cadenzajs-sandbox-${action}`);
@@ -118,6 +134,7 @@
     function getOptions ({
       disabledUiFeatures,
       expandNavigator,
+      filter,
       geometry,
       hideMainHeaderAndFooter,
       hideWorkbookToolBar,
@@ -134,6 +151,7 @@
       return {
         disabledUiFeatures: disabledUiFeatures && disabledUiFeatures.split(','),
         expandNavigator: (expandNavigator === 'on'),
+        filter: filter && parseFilterVariables(filter),
         geometry: geometry && JSON.parse(geometry),
         hideMainHeaderAndFooter: (hideMainHeaderAndFooter === 'on'),
         hideWorkbookToolBar: (hideWorkbookToolBar === 'on'),
@@ -148,6 +166,18 @@
         useMapSrs: useMapSrs === 'on'
       };
     }
+
+    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>
@@ -210,7 +240,25 @@
   </div>
   <div>
     <label for="disabledUiFeatures">Disabled UI features</label>
-    <input name="disabledUiFeatures" id="disabledUiFeatures" placeholder="feature1,feature2...">
+    <input name="disabledUiFeatures" id="disabledUiFeatures" placeholder="feature1,feature2,...">
+
+    <small>
+      <p>Comma-separated list of features</p>
+
+      Supported features:
+      <ul>
+        <li>workbook-design</li>
+        <li>workbook-view-management</li>
+      </ul>
+    </small>
+  </div>
+  <div>
+    <label for="filter">Filter</label>
+    <textarea name="filter" id="filter" rows="3"></textarea>
+    <small>
+      <p>A JSON object with filter variable names and values</p>
+      <p>Dates need to be ISO strings<br>(e.g. <code>"2023-11-17T17:12:06.175Z"</code>).<br>Use <code>"{{currentDate}}"</code> for the current date.</p>
+    </small>
   </div>
 </template>
 
@@ -283,7 +331,7 @@
   </div>
 </template>
 
-<template data-action="showMap" data-common="show">
+<template data-action="showMap" data-common="map,show">
   <div>
     <label for="embeddingTargetId">Embedding target ID of the map view *</label>
     <input name="embeddingTargetId" id="embeddingTargetId" required>