CADENZA-33335 [Workbook Embedding] Extend folder in navigator

.gitignore

@@ -3,3 +3,5 @@ node_modules
 /apidoc
 /cadenza.js
 /cadenza.d.ts
+
+.idea/

CHANGELOG.md

@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `mediaType` option for `CadenzaClient#show`
 - `CadenzaClient#fetchData`
 - `CadenzaClient#downloadData`
+- `highlightGlobalId` option for `CadenzaClient#show` and `CadenzaClient#showMap` 
 
 ## 1.0.0 - 2023-09-07
 

sandbox.html

@@ -70,19 +70,21 @@
 
     const cadenzaClient = cadenza(location.origin + '/trunk', { iframe: 'iframe', debug: true });
     const actionHandlers = {
-      show ({ embeddingTargetId, hideMainHeaderAndFooter, hideWorkbookToolBar, jasperReportAsPdf }) {
+      show ({ embeddingTargetId, hideMainHeaderAndFooter, hideWorkbookToolBar, jasperReportAsPdf, highlightGlobalId }) {
         cadenzaClient.show(embeddingTargetId, {
           hideMainHeaderAndFooter: (hideMainHeaderAndFooter === 'on'),
           hideWorkbookToolBar: (hideWorkbookToolBar === 'on'),
-          ...(jasperReportAsPdf === 'on' && { mediaType: 'application/pdf' })
+          highlightGlobalId,
+          ...(jasperReportAsPdf === 'on' && { mediaType: 'application/pdf' }),
         });
       },
-      showMap ({ embeddingTargetId, useMapSrs, geometry, mapExtent, locationFinder }) {
+      showMap ({ embeddingTargetId, useMapSrs, geometry, mapExtent, locationFinder, highlightGlobalId }) {
         cadenzaClient.showMap(embeddingTargetId, {
           useMapSrs: useMapSrs === 'on',
           geometry: geometry && JSON.parse(geometry),
           mapExtent: mapExtent && mapExtent.split(','),
-          locationFinder
+          locationFinder,
+          highlightGlobalId
         });
       },
       createGeometry ({ embeddingTargetId, geometryType, useMapSrs, minScale, mapExtent, locationFinder }) {
@@ -182,6 +184,10 @@
       Hide workbook toolbar
     </label>
   </div>
+  <div>
+    <label for="highlightGlobalId">Highlighted Global ID</label>
+    <input name="highlightGlobalId" id="highlightGlobalId">
+  </div>
 </template>
 
 <template data-action="showMap">
@@ -211,6 +217,10 @@
     <label for="locationFinder">Location finder search query</label>
     <input name="locationFinder" id="locationFinder">
   </div>
+  <div>
+    <label for="highlightGlobalId">Highlighted Global ID</label>
+    <input name="highlightGlobalId" id="highlightGlobalId">
+  </div>
 </template>
 
 <template data-action="createGeometry">

src/cadenza.js

@@ -27,6 +27,8 @@ globalThis.cadenza = Object.assign(
 
 /** @typedef {string} EmbeddingTargetId - The ID of an embedding target */
 
+/** @typedef {string} GlobalId - The ID of a navigator tree item */
+
 /**
  * @typedef ExternalLinkKey - A tuple qualifying a Cadenza external link
  * @property {string} repositoryName - The name of the link's repository
@@ -164,13 +166,20 @@ export class CadenzaClient {
    * @param {boolean} [options.hideWorkbookToolBar] - Whether to hide the workbook toolbar.
    * @param {string} [options.mediaType] - Set to "application/pdf" for Jasper Report views
    *     to show the PDF directly, without any Cadenza headers or footers.
+   * @param {GlobalId} [options.highlightGlobalId] - The id of the item to highlight and expand in the navigator tree.
    * @param {AbortSignal} [options.signal] - A signal to abort the iframe loading
    * @return {Promise<void>} A Promise for when the iframe is loaded
    * @throws For an invalid source
    */
   show(
     source,
-    { hideMainHeaderAndFooter, hideWorkbookToolBar, signal, mediaType } = {},
+    {
+      hideMainHeaderAndFooter,
+      hideWorkbookToolBar,
+      signal,
+      mediaType,
+      highlightGlobalId,
+    } = {},
   ) {
     this.#log('CadenzaClient#show', source);
     if (mediaType) {
@@ -179,6 +188,7 @@ export class CadenzaClient {
     const params = createParams({
       hideMainHeaderAndFooter,
       hideWorkbookToolBar,
+      highlightGlobalId,
       webApplication: this.#webApplication,
       mediaType,
     });
@@ -196,6 +206,7 @@ export class CadenzaClient {
    * @param {string} [options.locationFinder] - A search query for the location finder
    * @param {Extent} [options.mapExtent] - A map extent to set
    * @param {boolean} [options.useMapSrs] -  Whether the geometry and the extent are in the map's SRS (otherwise EPSG:4326 is assumed)
+   * @param {GlobalId} [options.highlightGlobalId] - The id of the item to highlight and expand in the navigator tree.
    * @param {AbortSignal} [options.signal] - A signal to abort the iframe loading
    * @return {Promise<void>} A Promise for when the iframe is loaded
    * @throws For an invalid workbook view source or geometry type
@@ -209,6 +220,7 @@ export class CadenzaClient {
       locationFinder,
       mapExtent,
       useMapSrs,
+      highlightGlobalId,
       signal,
     } = {},
   ) {
@@ -222,6 +234,7 @@ export class CadenzaClient {
       locationFinder,
       mapExtent,
       useMapSrs,
+      highlightGlobalId,
       webApplication: this.#webApplication,
     });
     return this.#show(resolvePath(mapView), { params, signal }).then(() =>
@@ -665,6 +678,7 @@ function assertSupportedMediaType(type, supportedTypes) {
  * @param {string} [params.mediaType]
  * @param {number} [params.minScale]
  * @param {boolean} [params.useMapSrs]
+ * @param {GlobalId} [params.highlightGlobalId]
  * @param {ExternalLinkKey} [params.webApplication]
  * @return {URLSearchParams}
  */
@@ -679,6 +693,7 @@ function createParams({
   mediaType,
   minScale,
   useMapSrs,
+  highlightGlobalId,
   webApplication,
 }) {
   if (geometryType) {
@@ -695,6 +710,7 @@ function createParams({
     ...(mediaType && { mediaType }),
     ...(minScale && { minScale: String(minScale) }),
     ...(useMapSrs && { useMapSrs: 'true' }),
+    ...(highlightGlobalId && { highlightGlobalId }),
     ...(webApplication && {
       webApplicationLink: webApplication.externalLinkId,
       webApplicationLinkRepository: webApplication.repositoryName,

src/cadenza.test.ts

@@ -106,9 +106,10 @@ describe('Given a Cadenza JS client instance', () => {
       cadenza(BASE_URL, { iframe }).show(EMBEDDING_TARGET_ID, {
         hideMainHeaderAndFooter: true,
         hideWorkbookToolBar: true,
+        highlightGlobalId: 'ROOT.MyFolder',
       });
       expect(cad.iframe!.src).toBe(
-        `${BASE_URL}/w/${EMBEDDING_TARGET_ID}?hideMainHeaderAndFooter=true&hideWorkbookToolBar=true`,
+        `${BASE_URL}/w/${EMBEDDING_TARGET_ID}?hideMainHeaderAndFooter=true&hideWorkbookToolBar=true&highlightGlobalId=ROOT.MyFolder`,
       );
     });