@disy/cadenza.js 1.6.0 → 1.7.0

package/cadenza.d.ts

@@ -68,6 +68,9 @@ 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 values
+ */
 /**
  * _Notes:_
  * * Most public methods can be aborted using an [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal).
@@ -101,6 +104,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
@@ -112,9 +117,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 +136,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
@@ -142,9 +150,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 +425,10 @@ export type MediaType = string;
  * - A part of a table to export.
  */
 export type TablePart = 'columns' | 'values' | 'totals';
+/**
+ * - Filter variable values
+ */
+export type FilterVariables = Record<string, string | number | Date>;
 /**
  * - A Cadenza `postMessage()` event
  */

package/cadenza.js

@@ -74,6 +74,9 @@ 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 values
+ */
 /**
  * _Notes:_
  * * Most public methods can be aborted using an [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal).
@@ -149,6 +152,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
@@ -160,7 +165,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 +178,7 @@ export class CadenzaClient {
         const params = createParams({
             disabledUiFeatures,
             expandNavigator,
+            filter,
             hideMainHeaderAndFooter,
             hideWorkbookToolBar,
             highlightGlobalId,
@@ -190,6 +196,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
@@ -202,7 +210,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 +218,7 @@ export class CadenzaClient {
         const params = createParams({
             disabledUiFeatures,
             expandNavigator,
+            filter,
             hideMainHeaderAndFooter,
             hideWorkbookToolBar,
             highlightGlobalId,
@@ -475,7 +484,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 +527,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 +587,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]
@@ -593,7 +604,7 @@ 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}`));
     }
@@ -606,6 +617,9 @@ function createParams({ action, expandNavigator, fileName, geometryType, hideMai
     if (parts) {
         parts.forEach((part) => 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 && {
@@ -629,6 +643,11 @@ function createParams({ action, expandNavigator, fileName, geometryType, hideMai
             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),
+            ]))),
     });
 }
 /**

package/package.json

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

package/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">