CADENZA-37480 Feat: Import geojson layers in create and edit geometry

CHANGELOG.md

@@ -6,6 +6,9 @@ This project uses a version scheme based on the Cadenza main version in the form
 
 ## Unreleased
 
+### Added
+- `additionalLayers` option for `CadenzaClient#createGeometry` and `CadenzaClient#editGeometry`
+
 ## 10.2.1 - 2024-10-14
 ### Added
 - `setCustomValidity()` and `ValidationMessageType` to control geometry editor validation state

sandbox.html

@@ -231,7 +231,8 @@
       fullGeometries,
       zoomToGeometry,
       distance,
-      lengthUnit
+      lengthUnit,
+      additionalLayers
     }) {
       return {
         disabledUiFeatures: disabledUiFeatures && disabledUiFeatures.split(','),
@@ -253,7 +254,8 @@
         useMapSrs: useMapSrs === 'on',
         fullGeometries: fullGeometries === 'on',
         zoomTarget: zoomToGeometry === 'on' ? { type: 'geometry' } : undefined,
-        buffer: distance ? { value: Number(distance), lengthUnit: lengthUnit ? lengthUnit : 'm' } : undefined
+        buffer: distance ? { value: Number(distance), lengthUnit: lengthUnit ? lengthUnit : 'm' } : undefined,
+        additionalLayers: additionalLayers && JSON.parse(additionalLayers)
       };
     }
 
@@ -495,6 +497,10 @@
     <label for="embeddingTargetId">Embedding target ID of the map view *</label>
     <input name="embeddingTargetId" id="embeddingTargetId" required>
   </div>
+  <div>
+    <label for="geometry">Additional layers (GeoJSON)</label>
+    <textarea name="additionalLayers" id="additionalLayers" rows="10"></textarea>
+  </div>
   <div>
     <label for="geometryType">Geometry type</label>
     <select name="geometryType" id="geometryType">
@@ -523,6 +529,10 @@
     <label for="embeddingTargetId">Embedding target ID of the map view *</label>
     <input name="embeddingTargetId" id="embeddingTargetId" required>
   </div>
+  <div>
+    <label for="geometry">Additional layers (GeoJSON)</label>
+    <textarea name="additionalLayers" id="additionalLayers" rows="10"></textarea>
+  </div>
   <div>
     <label for="geometry">Geometry (GeoJSON) *</label>
     <textarea name="geometry" id="geometry" rows="5" required></textarea>

src/cadenza.js

@@ -539,6 +539,13 @@ export class CadenzaClient {
     });
   }
 
+  /**
+   * @typedef {Object} LayerDefinition
+   * @property {string} name - The layer's name.
+   * @property {'geojson'} type - The layer's type.
+   * @property {FeatureCollection} content - The layer's content in geojson format.
+   */
+
   /**
    * Create a geometry.
    *
@@ -555,6 +562,7 @@ export class CadenzaClient {
    * @param {boolean} [options.useMapSrs] - Whether the created geometry should use the map's SRS (otherwise EPSG:4326 will be used)
    * @param {OperationMode} [options.operationMode] - The mode in which a workbook should be operated
    * @param {AbortSignal} [options.signal] - A signal to abort the iframe loading
+   * @param {LayerDefinition[]} [options.additionalLayers] - Layer definitions to be imported and shown in the background, as a basis for the drawing.
    * @return {Promise<void>} A `Promise` for when the iframe is loaded
    * @throws For invalid arguments
    * @fires
@@ -563,7 +571,7 @@ export class CadenzaClient {
    * - {@link CadenzaEditGeometryCancelEvent}
    * @embed
    */
-  createGeometry(
+  async createGeometry(
     backgroundMapView,
     geometryType,
     {
@@ -574,6 +582,7 @@ export class CadenzaClient {
       useMapSrs,
       operationMode,
       signal,
+      additionalLayers,
     } = {},
   ) {
     this.#log('CadenzaClient#createGeometry', ...arguments);
@@ -587,7 +596,12 @@ export class CadenzaClient {
       useMapSrs,
       operationMode,
     });
-    return this.#show(resolvePath(backgroundMapView), params, signal);
+    await this.#show(resolvePath(backgroundMapView), params, signal);
+    if (additionalLayers) {
+      additionalLayers.forEach((layer) =>
+        this.#postEvent('importLayer', layer),
+      );
+    }
   }
 
   /**
@@ -604,6 +618,7 @@ export class CadenzaClient {
    * @param {OperationMode} [options.operationMode] - The mode in which a workbook should be operated
    * @param {ZoomTarget} [options.zoomTarget] - A target Cadenza should zoom to
    * @param {AbortSignal} [options.signal] - A signal to abort the iframe loading
+   * @param {Object[]} [options.additionalLayers] - Layer definitions to be imported and shown in the background, as a basis for the drawing. Each is a layer definition, with name, type and content (a Geojson featureCollection).
    * @return {Promise<void>} A `Promise` for when the iframe is loaded
    * @throws For invalid arguments
    * @fires
@@ -624,6 +639,7 @@ export class CadenzaClient {
       zoomTarget,
       operationMode,
       signal,
+      additionalLayers,
     } = {},
   ) {
     this.#log('CadenzaClient#editGeometry', ...arguments);
@@ -647,6 +663,11 @@ export class CadenzaClient {
         zoomToGeometry,
       });
     }
+    if (additionalLayers) {
+      additionalLayers.forEach((layer) =>
+        this.#postEvent('importLayer', layer),
+      );
+    }
   }
 
   /**

src/docs.md

@@ -248,15 +248,31 @@ unsubscribe();
 
 <small>API: [CadenzaClient#createGeometry](./classes/CadenzaClient.html#createGeometry)</small>
 
-Edit a GeoJSON point geometry with a workbook map view in the background. The geometry coordinates are in the map's SRS (`useMapSrs: true`).
+Create a GeoJSON point geometry with a workbook map view in the background. The geometry coordinates are in the map's SRS (`useMapSrs: true`).
 
 ```javascript
 cadenzaClient.createGeometry('<embeddingTargetId>', 'Point', {
   useMapSrs: true,
 });
 
 cadenzaClient.on('editGeometry:ok', (event) => {
-  console.log('Geometry editing was completed', event.detail.geometry);
+  console.log('Geometry creation was completed', event.detail.geometry);
+});
+```
+
+_Note:_ Under the hood, creating a geometry is similar to editing a geometry.
+That's why the events use the `editGeometry` prefix.
+
+#### Additional Background Layers
+
+Create a GeoJSON polygon geometry with a workbook map view and some additional background layers.
+
+```javascript
+cadenzaClient.createGeometry('<embeddingTargetId>', 'Polygon', {
+  additionalLayers: [
+    { "type": "geojson", "name": "Example", "content": <FeatureCollection> },
+    ...
+  ]
 });
 ```