@vidro/map-handler 1.2.10 → 1.2.19

package/README.md

@@ -1,6 +1,6 @@
 # Map Handler
 
-#### Version 1.1.197 - Sep 2023
+#### Version 1.2.180 - February 2025
 
 Tool to achieve the easiest way of communication with the map iframe.
 
@@ -99,22 +99,51 @@ setDebug(0);
 
 ### Available events
 
+### Available Events
+
 ##### onZoomChange
 
-Notifies zoom level changed
+The `onZoomChange` event is triggered whenever the zoom level of the map changes. This event provides detailed metadata about the new zoom state, including the current zoom level, map extent, resolution, and scale.
 
-##### geomAdded
 
-Notifies geometry added to map, as string
 
-> E.G.
+The event returns an object with the following properties:
+
+| Property     | Type    | Description |
+|-------------|--------|-------------|
+| `type`      | string  | The event type, always `"onZoomChange"`. |
+| `zoom`      | number  | The current zoom level after the change. |
+| `maxZoom`   | number  | The maximum zoom level allowed in the map. |
+| `minZoom`   | number  | The minimum zoom level allowed in the map. |
+| `extent`    | array   | The map extent after zooming, represented as `[minX, minY, maxX, maxY]`. |
+| `resolution` | number | The resolution of the map at the current zoom level. |
+| `scale`     | string  | The approximate scale of the map in the format `"1:xxxx"`. |
 
+
+```
+{
+  "type": "onZoomChange",
+  "zoom": 15.035190437015496,
+  "maxZoom": 25,
+  "minZoom": 0,
+  "extent": [448455.99940588913, 4595273.644846473, 456909.8853950997, 4602082.14362973],
+  "resolution": 4.656975911940399,
+  "scale": "1:17600"
+}
 ```
-POINT(418925 4577135)
 
-POLYGON((418391.8715694032 4576832.484383419,418721.82301488414 4577299.667608328,418727.18131229794 4576947.724919814,418391.8715694032 4576832.484383419))
+##### geomAdded
+
+Notifies geometry added to map and featureId
 
-MULTILINESTRING((419268.8979576373 4577019.482027252,419146.6929889547 4577457.250226778,418798.40365705814 4577415.776056751))
+When this tool is used, NO geom is added when drawing finishes. In case you want to add it, use `Highlight` tool
+
+> E.G.
+
+```
+geom_astext: "POLYGON((418391.8715694032 4576832.484383419,418721.82301488414 4577299.667608328,418727.18131229794 4576947.724919814,418391.8715694032 4576832.484383419))"
+featureId: "uuid of geometry added'
+srid: 'EPSG:25831'
 ```
 
 ##### loaded
@@ -125,8 +154,10 @@ There're two types of events:
 
 - `map` is dispatched when map (with background) is loaded.
 - `layer` is dispatched when a layer is loaded
+	- `zIndex`: layer z-index 
 - `tiled` is dispatched when a tiled is loaded
 
+
 > `map` E.G:
 
 ```
@@ -137,7 +168,8 @@ There're two types of events:
 
 ```
 {what:'layer'
-name:'Arc'}
+name:'Arc'
+zIndex:998}
 ```
 
 ##### unloaded
@@ -182,14 +214,19 @@ Formatted Layers TOC (table of contents)
 
 ##### coordinates
 
-Notifies clicked coordinates (x,y)
+Notifies clicked coordinates (x,y), a BBOX in WKT and map srid
+
+BBOX by default is a 20m box. You can customize this value with method `setBboxSize`
 
 First coordinate is X value.
 
 > E.G:
 
 ```
-{coordinates: (2) [419463.63262834214, 4577166.970846243]
+{
+coordinates: (2) [419463.63262834214, 4577166.970846243],
+bbox: "POLYGON((452249.04604797193 4599115.704682493,452254.04604797193 4599115.704682493,452254.04604797193 4599120.704682493,452249.04604797193 4599120.704682493,452249.04604797193 4599115.704682493))",
+srid: "EPSG:25831",
 type: "coordinates"}
 ```
 
@@ -266,6 +303,32 @@ Notifies errors
 
 Notifies map status, as tiled loaded, background visible, etc..
 
+##### hover
+
+When user puts mouse pointer over a feauture for more than 1 second, a `hover` event is dispatched.
+
+If is no hover any feature event is dispatched with `feature:null` 
+
+
+> E.G
+
+```
+
+{type: "hover", feature: {'property':'somevalue',...}
+```
+
+##### screenshot <a id="screenshot-event"></a>
+
+This feature provides screenshot data, encoded as a PNG in Base64 format.
+
+
+> E.G
+
+```
+
+{type: "screenshot", content: 'png in base64'
+```
+
 ## Methods
 
 ##### ZoomIn()
@@ -290,7 +353,26 @@ Zooms to given coordinates
 zoomToCoordinates(419006.12985785044, 4576698.8136144625,18);
 
 ```
-##### CenterMap(lat,long)
+
+##### zoomToGeometry
+
+Zooms to a given geometry
+
+> Params
+
+- geom `<string>` WKT geometry
+- limits `<json>` max/min zoom level
+  - max `<integer>`
+  - min `<integer>`
+
+  > E.G.
+
+```
+zoomToCoordinates(419006.12985785044, 4576698.8136144625,18);
+
+```
+
+##### zoomToGeometry(lat,long)
 
 center map to given coordinates
 
@@ -305,6 +387,34 @@ center map to given coordinates
 CenterMap(419006.12985785044, 4576698.8136144625,18);
 
 ```
+##### zoomToScale(scale)
+
+Sets the zoom level to a specified scale.
+
+
+
+> **Allowed Scales:**
+
+- `1:100`
+- `1:200`
+- `1:400`
+- `1:500`
+- `1:1000`
+- `1:2000`
+- `1:5000`
+- `1:10000`
+- `1:50000`
+
+> Params
+
+- **`scale`** `<string>` - The scale to set the zoom level.
+
+
+E.G:
+
+```javascript
+zoomToScale('1:100');
+```
 
 
 ##### AddGeom(string)
@@ -315,6 +425,32 @@ Launches drawing tools with the geometry type
 
 - geom `<string>` - geometry type `Point` | `Line` | `Polygon`
 
+Optional parameters
+
+- `texts` (`object`): Texts to be displayed with draw tools.
+  - `start` (`string`): E.G. "Click to start drawing"
+  - `continnue`:(`string`): E.G. "Click to to continue drawing"
+- `center` (`object`): Center options.
+- `style` (`object`):
+  - `fill` (`string`): The fill color for the drawn geometry.
+  - `stroke` (`string`): The stroke color for the drawn geometry.
+- `drawOnEnd` (`boolean`): Is is set to `false` geometry will not be added on end drawing. The event with the drawn geometry will still be emitted
+- `showConfirm` (`boolean`): show or hide component for end drawing. If is set to false, `CancelAddGeom()` must be handled by the user.
+
+Confirm component:
+![](doc/confirmComponent.png)
+
+#### CancelAddGeom
+
+Cancels draw geometry
+
+> E.G.
+
+```
+CancelAddGeom();
+
+```
+
 > E.G.
 
 ```
@@ -323,17 +459,56 @@ AddGeom('Point');
 AddGeom('Line');
 
 AddGeom('Polygon');
+
+//Draw polygon with no showConfirm
+AddGeom('Polygon', {showConfirm: false});
 ```
 
 An `geomAdded` event will be received after calling the method.
 
+##### addIcon(icon,coordinates)
+
+Add an icon on a given coordinates
+
+> Params
+
+- icon `<ArrayBuffer>` - The binary data of the icon image, typically obtained by converting an image file (e.g., PNG) to an `ArrayBuffer`. This should represent the visual marker to be displayed on the map.
+- coordintes `<array>` - An array specifying the location where the icon should be added. Format: `[longitude, latitude]`. Ensure the coordinates are in the same SRID (Spatial Reference Identifier) as the map being used (e.g., EPSG:4326 for geographic coordinates). Transform the coordinates if necessary before passing them to this method.
+
+```
+
+// Fetch and process the image as binary data
+const iconBinaryData =  convert to binary method (`path/images/icons/anIcon.png`);
+    
+addIcon(iconBinaryData, [2, 4.6]);
+
+```
+[ArrayBuffer conversion examples](helpers.md)
+
+
+##### setBboxSize
+
+Set the BBOX size of clicked coordinates. When the receives a click events, calculates an bounding box of bboxsize meters.
+
+> E.G.
+
+```
+setBboxSize(5);  //set a bbox of 5 meters
+```
+
 ##### clear()
 
 Clears drawn geometries
 
 ##### toggleLayer
 
-Shows/hides a layer
+Shows/hides a layer.
+
+**\*Important**
+
+This method loads a single layer. If you need to load multiple layers, use `loadMultipleLayers()` method
+
+If ypu need to load multiple layers
 
 > Params
 
@@ -342,6 +517,7 @@ Shows/hides a layer
   - gutter `<integer>` - The size in pixels of the gutter around image tiles to ignore, only applies for multitile layer
   - singletile `<boolean>` - SingleTile Layer
   - transparent `<boolean>` - Transparent Layer
+  - type `<string>` - layer type (wms, geojson...)
 
 By default, layer properties will be:
 
@@ -365,6 +541,20 @@ With properties
 toggleLayer('somelayer_name', {gutter: 10, transparent: false, singletile: false);
 ```
 
+##### toggleGroup
+
+Toggles (show/hide) a list of layers. Layers must be loaded before with `loadMultipleLayers`
+
+- ## layers `<array>`:
+
+##### loadMultipleLayers()
+
+Loads multiple layers. Use this method if you want to load multiple layers.
+
+> Params
+
+- layers `<array>`: array of layers, each layer with same proerties than `toggleLayer` method.
+
 ##### setActiveLayer()
 
 Sets a layer as acticve layer, used for infos
@@ -375,6 +565,27 @@ Sets a layer as acticve layer, used for infos
 setActiveLayer('somelayer_name');
 ```
 
+##### removeLayer(layer_name)
+
+Removes a layer
+
+> E.G.
+
+```
+removeLayer('somelayer_name');
+```
+
+##### displayLayer(layer_name)
+
+Displays a layer
+
+> E.G.
+
+```
+displayLayer('somelayer_name');
+```
+
+
 ##### reloadDisplayedLayers
 
 Reloads displayed layers
@@ -397,6 +608,34 @@ loadWMSAvailableLayers();
 
 An `availableWMSLayers ` event will be received after calling the method.
 
+##### bringLayerToTop
+
+> Params
+
+- layer_name `<string>`: layer name
+
+Brings layer to top.
+
+> E.G.
+
+```
+bringLayerToTop('somelayer_name');
+```
+
+##### bringLayerToBottom
+
+> Params
+
+- layer_name `<string>`: layer name
+
+Brings layer to bottom.
+
+> E.G.
+
+```
+bringLayerToBottom('somelayer_name');
+```
+
 ##### getToc
 
 Gets a formatted Layers TOC (Table of contents)
@@ -466,12 +705,15 @@ Geolocalizes user. Will dispatch `geolocation` event .
 > Params
 
 - toggle `<Boolean>` - starts or cancels geolocation
+- options `<json>` - optional
+	- track `<Boolean>` - will track user position or geolocalize only once 
 
 > E.G.
 
 ```
 //start
 Geolocalize(true)
+Geolocalize(true, {track:true})
 
 //cancel
 Geolocalize(false)
@@ -481,23 +723,38 @@ Geolocalize(false)
 
 ##### Higlight
 
-Highlights a geometry
+Highlights & draws a geometry. Allows animation and zoom to element.
+If you want to draw a geom, just use `DrawGeometries` method
 
 Params
 
-- options `<object>` highlight options
-
-  - geom `<string>` - geometry string
-
-  - zoom `<object>`
-
-    - zoom.type `<string>` - `level | element`
-
-      _level_ will zoom to zoomLevel
-
-      _element_ geometry center
-
-    - zoom.zoomLevel `<integer>` 1 to 28
+- `geom` (`string`): The geometry string in WKT to highlight.
+
+Optional parameters
+
+- `zoom` (`object`): Zoom options.
+  - `type` (`string`): The type of zoom (`level` or `element`).
+    - `level`: Zoom to a specific zoom level.
+    - `element`: Zoom to the center of the geometry.
+  - `zoomLevel` (`number`, optional): The zoom level (1 to 28). Required if `type` is set to `level`.
+- `center` (`object`): Center options.
+	- `false` will not center map to element
+	- `1` will center always map to element
+	- `2` will center element only if is outside current view extent 
+- `data` (`object`): Additional data associated with the highlight.
+  - `feautureId` (`string`): The ID of the feature.
+  - `name` (`string`): The name of the feature.
+  - ... any extra data will be added to feature
+- style (`object`): geometry styling options
+  - `fill` (`string`): The fill color for the highlighted geometry.
+  - `stroke` (`string`): The stroke color for the highlighted geometry.
+- `animate` (`boolean`): Indicates whether to animate the highlight.
+  - `duration`: time of the animation in milliseconds
+  - `repeat`: true/false for repeteating animation
+
+Example of animation
+
+![](doc/animation.png)
 
 > E.G.
 
@@ -526,6 +783,120 @@ let options = {
 Highlight(options);
 ```
 
+##### DrawGeometry - DEPRECATED
+
+**use `DrawGeometries`**
+
+Draws a single geometry, in case you want to draw multiple geometries simultaneusly use `DrawGeometries ` method
+
+> E.G.
+
+```
+//Draw a geometry with yellow stroke
+
+const geom = 'MULTILINESTRING((418596.62555076234 4577083.383681167,419026.2319996517 4577216.795306675))'
+
+const style = {
+		stroke_color: "rgb(233, 244, 75)"
+	}
+}
+
+DrawGeometry(geom,style,'sampleName','mockId');
+
+```
+
+##### DrawGeometries
+
+Draws geometries
+
+> Params
+
+- geoms `<array>`:
+  - item `<object>`:
+    - geom `<string>` - geometry string
+    - style `<object>`
+      - stroke_color `<string>`
+      - fill_color `<string>`
+      - geom_radius `<integer>`
+      - stroke_width `<integer>`
+      - font_color `<string>`
+      - font `<string>`
+      - placement `<string>`
+      - fontFillColor `<string>`
+        - fontStrokeColor `<string>`
+      - display `<string>`
+      - fontStrokeWidth `<integer>`
+      - offsetY `<integer>`
+      - baseline `<string>`
+      - align `<string>`
+    - name `<string>` feauture name
+    - id `<string>` feauture id
+
+> E.G.
+
+```
+//Draw a geometry with yellow stroke
+
+const geom = 'MULTILINESTRING((418596.62555076234 4577083.383681167,419026.2319996517 4577216.795306675))'
+
+const style = {
+		stroke_color: "rgb(233, 244, 75)"
+	}
+}
+const item = {geom,style,'sampleName','mockId'};
+DrawGeometries([item]);
+```
+
+##### RemoveGeometry
+
+Removes a geometry by ID
+
+Params
+
+- id `<string>` - rendered geometry unique
+- layer `<string>` - layer name, optional
+
+> E.G.
+
+```
+RemoveGeometry('25', 'somlayer')
+```
+
+##### RemoveGeometriesByProperty
+
+Removes geometries by property value
+
+Params
+
+- layer `<string>` - layer name, optional
+- property `<string>` - property name
+- value - property value
+
+> E.G.
+
+```
+RemoveGeometriesByProperty( 'somlayer','type','something')
+```
+
+##### UpdateGeometriesByProperty
+
+Update geometry style based on property value
+
+Params
+
+- layer `<string>` - layer name, optional
+- property `<string>` - property name
+- value - property value
+- style `<object>` - stroke_color `<string>` - fill_color `<string>` - geom_radius `<integer>` - stroke_width `<integer>` - font_color `<string>` - font `<string>` - placement `<string>` - fontFillColor `<string>` - fontStrokeColor `<string>` - display `<string>` - fontStrokeWidth `<integer>` - offsetY `<integer>` - baseline `<string>` - align `<string>`
+
+> E.G.
+
+```
+UpdateGeometriesByProperty( 'somlayer','type','something',{
+stroke_color: "rgb(255, 0, 0)"}
+)
+```
+
 ##### toggleTiled
 
 Deprecated `toggleGiswaterTiled`
@@ -546,14 +917,12 @@ toggleTiled(true);
 
 ##### toggleSecondaryBackground
 
-
 Toggles secondary background (in case secondary background is configured)
 
 Params
 
 - toggle `<boolean>` shows/hides secondary background
 
-
 > E.G.
 
 ```
@@ -561,7 +930,6 @@ toggleSecondaryBackground(true);
 
 ```
 
-
 ##### addGeoJSON
 
 Adds geoJSON layer
@@ -615,13 +983,23 @@ clearGeoJSON();
 ```
 
 ##### setFilters
-Deprecated `setGiswaterFilters`
 
+Deprecated `setGiswaterFilters`
 
 Set filters for displayed layers
 
 Filters must be a JSON with valid fields. On Giswater/QGIS projects, available layer filters can be obtained with method `getGiswaterLayerAvailableFilters`
 
+Each filter must have this format:
+
+- layer_id <integer>
+- layer*name <string> - *`qgis_name` property\_
+- filters: <array>
+  - name <string>: field name
+  - condition <string>: `=`,`!=`,`<`,`>`,`<=`,`>=`,`in`,`between`
+  - value: value to be filtered
+  - value2: second value, only for `between` conditions
+
 ```
 setFilters(JSON);
 ```
@@ -629,7 +1007,32 @@ setFilters(JSON);
 > E.G.
 
 ```
-setFilters({"expl_id":[1,2,3]});
+setFilters([
+  {
+    layer_id: 1,
+    layer_name: "mylayer",
+    filters: [
+      {
+        name: 'exp_id',
+        condition: 'in',
+        value: "'1','4'",
+        value2: null
+      },
+      {
+        name: 'status',
+        condition: '=',
+        value: 'active',
+        value2: null
+      },
+      {
+        name: 'anotherField',
+        condition: 'between',
+        value: '100',
+        value2: '200'
+      }
+    ]
+  }
+]);
 ```
 
 ##### getGiswaterLayerAvailableFilters
@@ -715,6 +1118,13 @@ Stop measure tools
 cancelMeasure();
 ```
 
+##### screenshot
+
+Will do an screenshot of the current map encoded as a PNG in Base64 format. Result will be encapsulated [`screenshot`](#screenshot-event)
+
+```
+screenshot({});
+```
 ### Multiple iframes
 
 Is possible to use multiple iframe on a single page, follow this steps.