basic operations docs: init, events, modes

geoman-io · dailyprice · Aug 21, 2024 · Aug 21, 2024 · Aug 21, 2024 · Sep 18, 2024
commit 8b4beddc4fce49e0996c7e3ffe59f85243f33a4f
diff --git a/docs/01-basics.md b/docs/01-basics.md
@@ -0,0 +1,85 @@
+---
+title: "Basic Usage"
+---
+
+# Basic Usage
+
+## Installation
+
+```shell
+# install pro version
+npm install @geoman-io/maplibre-geoman-pro
+
+# or free version
+npm install @geoman-io/maplibre-geoman-free
+```
+
+## Expected HTML Structure
+```html
+<!-- index.html -->
+<html lang="en_US">
+<head>
+  <title>Geoman Maplibre</title>
+  <style>
+    #dev-map {
+      height: 100vh;
+      width: 100vw;
+    }
+  </style>
+</head>
+<body>
+  <div id="dev-map"></div>
+</body>
+</html>
+```
+
+## Maplibre and Geoman initialization
+```typescript
+import ml from 'maplibre-gl';
+import { type GmOptionsPartial } from '@geoman-io/maplibre-geoman-pro';
+
+import 'maplibre-gl/dist/maplibre-gl.css';
+import '@geoman-io/maplibre-geoman-pro/dist/maplibre-geoman.css';
+
+
+const mapStyle: ml.StyleSpecification = {
+  version: 8,
+  glyphs: 'https://demotiles.maplibre.org/font/{fontstack}/{range}.pbf',
+  sources: {
+    'osm-tiles': {
+      type: 'raster',
+      tiles: [
+        'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
+      ],
+      tileSize: 256,
+      attribution: '© OpenStreetMap contributors',
+    },
+  },
+  layers: [
+    {
+      id: 'osm-tiles-layer',
+      type: 'raster',
+      source: 'osm-tiles',
+      minzoom: 0,
+      maxzoom: 19,
+    },
+  ],
+};
+
+const map = new ml.Map({
+  container: 'dev-map',
+  style: mapLibreStyle,
+  center: [0, 51],
+  zoom: 5,
+});
+
+const gmOptions: GmOptionsPartial = {
+  // geoman options here
+};
+
+const geoman = new Geoman(gmOptions);
+geoman.addControl(map).then(() => {
+  // geoman is available here as: "geoman" or "map.gm"  
+  console.log('Geoman Controls added');
+});
+```
diff --git a/docs/02-events.md b/docs/02-events.md
@@ -0,0 +1,27 @@
+---
+title: "Events"
+---
+
+# Events listening
+
+Events listening is avaiable the same way as for Maplibre. You can listen to all events that are fired by Geoman. 
+```typescript
+// example of listening to the create event
+map.on('gm:create', (event: GMEvent) => {
+  log.debug('Event', event);
+});
+```
+
+To debug all events you can use the following code. This way you can see all events that are fired by Geoman in the browser console.
+```typescript
+import { type GlobalEventsListenerParemeters } from '@geoman-io/maplibre-geoman-pro';
+
+map.gm.setGlobalEventsListener((event: GlobalEventsListenerParemeters) => {
+  if (event.type === 'converted') {
+    console.log('Regular event', event);
+  } else if (event.type === 'system') {
+    console.log('System event', event);
+  }
+});
+
+```
diff --git a/docs/03-mode-switching.md b/docs/03-mode-switching.md
@@ -0,0 +1,24 @@
+---
+title: "Modes handing"
+---
+
+# Modes handing
+
+All available modes can be enabled/disabled/toggled by the following methods:
+
+For example to handle `edit:drag` mode:
+```typescript
+// enable mode
+map.gm.options.enableMode('edit', 'drag');
+
+// disable mode
+map.gm.options.disableMode('edit', 'drag');
+
+// toggle mode
+map.gm.options.toggleMode('edit', 'drag');
+
+// check mode state
+map.gm.options.isModeEnabled('edit', 'drag');
+```
+
+Typescript support is available so you can see available options for each method in the Geoman.
diff --git a/docs/draw-modes/00-draw-marker.mdx b/docs/draw-modes/00-draw-marker.mdx
@@ -2,7 +2,7 @@
 title: "Draw Marker"
 ---
 
-## Draw Marker Mode
+# Draw Marker Mode
 
 Draw Marker Mode allows you to add markers to the map by clicking on desired locations.
 

diff --git a/docs/draw-modes/01-draw-circle_marker.mdx b/docs/draw-modes/01-draw-circle_marker.mdx
@@ -2,7 +2,7 @@
 title: "Draw Circle Marker"
 ---
 
-## Draw Circle Marker Mode
+# Draw Circle Marker Mode
 
 Draw Circle Marker Mode allows you to add circle markers to the map. Circle markers are circles with a fixed radius in pixels that maintain their screen size regardless of zoom level.
 

diff --git a/docs/draw-modes/02-draw-text_marker.mdx b/docs/draw-modes/02-draw-text_marker.mdx
@@ -2,7 +2,7 @@
 title: "Draw Text Marker"
 ---
 
-## Draw Text Marker Mode
+# Draw Text Marker Mode
 
 Draw Text Marker Mode allows you to add text labels to the map by clicking on desired locations and entering custom text.
 

diff --git a/docs/draw-modes/03-draw-circle.mdx b/docs/draw-modes/03-draw-circle.mdx
@@ -2,7 +2,7 @@
 title: "Draw Circle"
 ---
 
-## Draw Circle Mode
+# Draw Circle Mode
 
 Draw Circle Mode allows you to add circles to the map by defining a center point and radius.
 

diff --git a/docs/draw-modes/04-draw-line.mdx b/docs/draw-modes/04-draw-line.mdx
@@ -2,7 +2,7 @@
 title: "Draw Line"
 ---
 
-## Draw Line Mode
+# Draw Line Mode
 
 Draw Line Mode allows you to create lines on the map by clicking to add vertices.
 

diff --git a/docs/draw-modes/05-draw-rectangle.mdx b/docs/draw-modes/05-draw-rectangle.mdx
@@ -2,7 +2,7 @@
 title: "Draw Rectangle"
 ---
 
-## Draw Rectangle Mode
+# Draw Rectangle Mode
 
 Draw Rectangle Mode allows you to create rectangles on the map by clicking and dragging to define opposite corners.
 

diff --git a/docs/draw-modes/06-draw-polygon.mdx b/docs/draw-modes/06-draw-polygon.mdx
@@ -2,7 +2,7 @@
 title: "Draw Polygon"
 ---
 
-## Draw Polygon Mode
+# Draw Polygon Mode
 
 Draw Polygon Mode allows you to create polygons on the map by clicking to add vertices and closing the shape.
 

diff --git a/docs/draw-modes/_category_.json b/docs/draw-modes/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Draw Modes",
-  "position": 2,
+  "position": 102,
   "collapsible": true,
   "link": {
     "type": "generated-index"

diff --git a/docs/edit-modes/00-edit-drag.mdx b/docs/edit-modes/00-edit-drag.mdx
@@ -2,7 +2,7 @@
 title: "Drag"
 ---
 
-## Drag Mode
+# Drag Mode
 
 You can enable Drag Mode for all layers on a map like this:
 

diff --git a/docs/edit-modes/01-edit-change.mdx b/docs/edit-modes/01-edit-change.mdx
@@ -2,7 +2,7 @@
 title: "Edit"
 ---
 
-## Edit Mode
+# Edit Mode
 
 You can enable Edit Mode for all layers on a map like this:
 

diff --git a/docs/edit-modes/02-edit-rotate.mdx b/docs/edit-modes/02-edit-rotate.mdx
@@ -2,7 +2,7 @@
 title: "Rotate"
 ---
 
-## Rotate Mode
+# Rotate Mode
 
 You can enable Rotate Mode for all layers on a map like this:
 

diff --git a/docs/edit-modes/03-edit-scale.mdx b/docs/edit-modes/03-edit-scale.mdx
@@ -1,8 +1,8 @@
 ---
-title: "Scale"
+title: "Scale ⭐"
 ---
 
-## Scale Mode
+# Scale Mode
 
 You can enable Scale Mode for all layers on a map like this:
 

diff --git a/docs/edit-modes/04-edit-copy.mdx b/docs/edit-modes/04-edit-copy.mdx
@@ -1,8 +1,8 @@
 ---
-title: "Copy"
+title: "Copy ⭐"
 ---
 
-## Copy Mode
+# Copy Mode
 
 You can enable Copy Mode for all layers on a map like this:
 

diff --git a/docs/edit-modes/05-edit-cut.mdx b/docs/edit-modes/05-edit-cut.mdx
@@ -2,7 +2,7 @@
 title: "Cut"
 ---
 
-## Cut Mode
+# Cut Mode
 
 Cut mode allows you to cut holes in existing shapes or remove parts of them. You can enable Cut Mode for all layers on a map like this:
 

diff --git a/docs/edit-modes/06-edit-split.mdx b/docs/edit-modes/06-edit-split.mdx
@@ -1,8 +1,8 @@
 ---
-title: "Split"
+title: "Split ⭐"
 ---
 
-## Split Mode
+# Split Mode
 
 Split Mode allows you to draw a line that splits all underlying Polygons and Lines. When a feature is split, the original feature will be replaced with the resulting split features.
 

diff --git a/docs/edit-modes/07-edit-union.mdx b/docs/edit-modes/07-edit-union.mdx
@@ -1,8 +1,8 @@
 ---
-title: "Union"
+title: "Union ⭐"
 ---
 
-## Union Mode
+# Union Mode
 
 Union Mode allows you to merge multiple polygons into a single polygon. The original features will be replaced with the resulting union feature.
 

diff --git a/docs/edit-modes/08-edit-difference.mdx b/docs/edit-modes/08-edit-difference.mdx
@@ -1,8 +1,8 @@
 ---
-title: "Difference"
+title: "Difference ⭐"
 ---
 
-## Difference Mode
+# Difference Mode
 
 Difference Mode allows you to subtract one polygon from another. The original feature will be replaced with the resulting difference feature.
 

diff --git a/docs/edit-modes/09-edit-line_simplification.mdx b/docs/edit-modes/09-edit-line_simplification.mdx
@@ -1,8 +1,8 @@
 ---
-title: "Line Simplification"
+title: "Line Simplification ⭐"
 ---
 
-## Line Simplification Mode
+# Line Simplification Mode
 
 Line Simplification Mode allows you to simplify line geometry by removing vertices. This is useful for smoothing complex lines or reducing the number of points in a line.
 

diff --git a/docs/edit-modes/10-edit-lasso.mdx b/docs/edit-modes/10-edit-lasso.mdx
@@ -1,8 +1,8 @@
 ---
-title: "Lasso"
+title: "Lasso ⭐"
 ---
 
-## Lasso Mode
+# Lasso Mode
 
 Lasso Mode allows you to select multiple features by drawing a polygon around them. The selection behavior can be configured to either select features that intersect with or are contained within the lasso polygon.
 

diff --git a/docs/edit-modes/11-edit-delete.mdx b/docs/edit-modes/11-edit-delete.mdx
@@ -2,7 +2,7 @@
 title: "Remove"
 ---
 
-## Remove Mode
+# Remove Mode
 
 Remove Mode allows you to delete features from the map by clicking on them.
 

diff --git a/docs/edit-modes/_category_.json b/docs/edit-modes/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Edit Modes",
-  "position": 1,
+  "position": 101,
   "collapsible": true,
   "link": {
     "type": "generated-index"

diff --git a/docs/helper-modes/00-helper-snapping.mdx b/docs/helper-modes/00-helper-snapping.mdx
@@ -1,8 +1,8 @@
 ---
-title: "Snapping Helper"
+title: "Snapping"
 ---
 
-## Snapping Helper Mode
+# Snapping Helper Mode
 
 The Snapping Helper Mode enables alignment of features by "snapping" them to nearby elements on the map. This mode provides tools to control, activate, or deactivate snapping for layers or shapes during editing.
 

diff --git a/docs/helper-modes/01-helper-snap_guides.mdx b/docs/helper-modes/01-helper-snap_guides.mdx
@@ -1,8 +1,8 @@
 ---
-title: "Snap Guides Helper"
+title: "Snap Guides ⭐"
 ---
 
-## Snap Guides Helper Mode
+# Snap Guides Helper Mode
 
 The Snap Guides Helper Mode adds visual guidelines that assist in snapping features to specific angles or points during map editing. This mode is useful when precise alignment is necessary while creating or modifying shapes.
 

diff --git a/docs/helper-modes/02-helper-measurements.mdx b/docs/helper-modes/02-helper-measurements.mdx
@@ -1,8 +1,8 @@
 ---
-title: "Measurements Helper"
+title: "Measurements ⭐"
 ---
 
-## Measurements Helper Mode
+# Measurements Helper Mode
 
 The Measurements Helper Mode provides tools to display live measurements such as distance, area, and perimeter for various shapes during map editing. This mode works with different shape types to dynamically calculate and display measurements as users draw or modify features.
 

diff --git a/docs/helper-modes/03-helper-pin.mdx b/docs/helper-modes/03-helper-pin.mdx
@@ -1,8 +1,8 @@
 ---
-title: "Pin Helper"
+title: "Pin ⭐"
 ---
 
-## Pin Helper Mode
+# Pin Helper Mode
 
 The Pin Helper Mode allows you to "pin" markers or vertices together, enabling synchronized movement of all connected points when any one of them is dragged. This mode is useful for maintaining alignment across features that share the same coordinates.
 

diff --git a/docs/helper-modes/04-helper-auto_trace.mdx b/docs/helper-modes/04-helper-auto_trace.mdx
@@ -1,8 +1,8 @@
 ---
-title: "Auto Trace Helper"
+title: "Auto Trace ⭐"
 ---
 
-## Auto Trace Helper Mode
+# Auto Trace Helper Mode
 
 The Auto Trace Helper Mode assists users in drawing and connecting shapes by automatically tracing the shortest path between selected points. This mode can be applied to create or complete shapes like lines and polygons by tracing along existing paths.