Skip to content

Commit cd9a60d

Browse files
dannyleechdannyleech
authored
Plugin docs updated (#173)
1 parent 81391bd commit cd9a60d

3 files changed

Lines changed: 447 additions & 125 deletions

File tree

‎docs/plugins/interact.md‎

Lines changed: 176 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,19 @@
11
# Interact Plugin
22

3-
Select features or place markers on the map. The interact plugin provides a unified way to handle user interactions for selecting map features or placing location markers.
3+
The interact plugin provides a unified way to handle user interactions for selecting map features or placing location markers.
44

55
## Usage
66

77
```js
88
import createInteractPlugin from '@defra/interactive-map/plugins/interact'
99

10-
const interactPlugin = createInteractPlugin()
10+
const interactPlugin = createInteractPlugin({
11+
interactionMode: 'auto',
12+
multiSelect: true,
13+
dataLayers: [
14+
{ layerId: 'my-layer', idProperty: 'id' }
15+
]
16+
})
1117

1218
const interactiveMap = new InteractiveMap({
1319
plugins: [interactPlugin]
@@ -34,20 +40,136 @@ Array of mode identifiers. When set, the plugin does not render when the app is
3440

3541
---
3642

43+
### `interactionMode`
44+
**Type:** `'marker' | 'select' | 'auto'`
45+
**Default:** `'marker'`
46+
47+
Controls how user clicks are interpreted.
48+
49+
- `'marker'` — clicking always places a location marker at the clicked coordinates
50+
- `'select'` — clicking attempts to match a feature from `dataLayers`; click outside clears selection (unless `deselectOnClickOutside` is `false`)
51+
- `'auto'` — attempts feature matching first, falls back to placing a marker if no feature is found
52+
53+
---
54+
55+
### `dataLayers`
56+
**Type:** `Array<DataLayer>`
57+
**Default:** `[]`
58+
59+
Array of map layer configurations that are selectable. Each entry specifies which layer to watch and how to identify features.
60+
61+
```js
62+
dataLayers: [
63+
{ layerId: 'my-polygons', idProperty: 'id' },
64+
{ layerId: 'my-lines' }
65+
]
66+
```
67+
68+
#### `DataLayer` properties
69+
70+
| Property | Type | Description |
71+
|----------|------|-------------|
72+
| `layerId` | `string` | **Required.** The map layer identifier to enable selection on |
73+
| `idProperty` | `string` | Property name used as the feature's unique identifier. If omitted, features are matched by index |
74+
| `selectedStroke` | `string` | Overrides the global `selectedStroke` for this layer |
75+
| `selectedFill` | `string` | Overrides the global `selectedFill` for this layer |
76+
| `selectedStrokeWidth` | `number` | Overrides the global `selectedStrokeWidth` for this layer |
77+
78+
---
79+
80+
### `multiSelect`
81+
**Type:** `boolean`
82+
**Default:** `false`
83+
84+
When `true`, clicking additional features adds them to the selection rather than replacing it.
85+
86+
---
87+
88+
### `contiguous`
89+
**Type:** `boolean`
90+
**Default:** `false`
91+
92+
When `true`, only features that touch or overlap the existing selection can be added. Uses spatial intersection to determine contiguity. Works with polygons, lines, and points.
93+
94+
---
95+
96+
### `deselectOnClickOutside`
97+
**Type:** `boolean`
98+
**Default:** `false`
99+
100+
When `true`, clicking outside any selectable layer clears the current selection.
101+
102+
---
103+
104+
### `tolerance`
105+
**Type:** `number`
106+
**Default:** `10`
107+
108+
Click detection radius in pixels. Increases the hit area around the cursor when matching features, which is useful for lines and points.
109+
110+
---
111+
112+
### `closeOnAction`
113+
**Type:** `boolean`
114+
**Default:** `true`
115+
116+
When `true`, the app closes after the user clicks "Done" or "Cancel".
117+
118+
---
119+
120+
### `markerColor`
121+
**Type:** `string`
122+
**Default:** `'rgba(212,53,28,1)'`
123+
124+
Color of the location marker placed on the map.
125+
126+
---
127+
128+
### `selectedStroke`
129+
**Type:** `string`
130+
**Default:** `'rgba(212,53,28,1)'`
131+
132+
Stroke color used to highlight selected features. Can be overridden per layer via `dataLayers`.
133+
134+
---
135+
136+
### `selectedFill`
137+
**Type:** `string`
138+
**Default:** `'rgba(255, 0, 0, 0.1)'`
139+
140+
Fill color used to highlight selected features. Can be overridden per layer via `dataLayers`.
141+
142+
---
143+
144+
### `selectedStrokeWidth`
145+
**Type:** `number`
146+
**Default:** `2`
147+
148+
Stroke width used to highlight selected features. Can be overridden per layer via `dataLayers`.
149+
150+
---
151+
37152
## Methods
38153

39154
Methods are called on the plugin instance after the map is ready.
40155

41156
---
42157

43-
### `enable()`
158+
### `enable(options?)`
159+
160+
Enable interaction mode. Shows action buttons and enables feature selection or marker placement. Accepts an optional options object to override any of the factory options at runtime.
44161

45-
Enable interaction mode. Shows action buttons and enables feature selection or marker placement.
162+
| Parameter | Type | Description |
163+
|-----------|------|-------------|
164+
| `options` | `Object` | Optional. Any factory options to apply for this session |
46165

47166
```js
48167
interactiveMap.on('map:ready', () => {
49168
interactPlugin.enable()
50169
})
170+
171+
// Override options at runtime
172+
interactPlugin.enable({ multiSelect: true, interactionMode: 'select' })
51173
```
52174

53175
---
@@ -72,26 +194,42 @@ interactPlugin.clear()
72194

73195
---
74196

75-
### `selectFeature(feature)`
197+
### `selectFeature(featureInfo)`
76198

77199
Programmatically select a feature.
78200

79201
| Parameter | Type | Description |
80202
|-----------|------|-------------|
81-
| `feature` | `Object` | Feature object to select |
203+
| `featureInfo.featureId` | `string` | The feature's identifier value |
204+
| `featureInfo.layerId` | `string` | Optional. The layer the feature belongs to |
205+
| `featureInfo.idProperty` | `string` | Optional. The property name used as the identifier |
82206

83207
```js
84-
interactPlugin.selectFeature({ id: 'feature-1', bounds: [...] })
208+
interactPlugin.selectFeature({
209+
featureId: 'abc123',
210+
layerId: 'my-layer',
211+
idProperty: 'id'
212+
})
85213
```
86214

215+
Respects the current `multiSelect` setting — if `multiSelect` is `false`, the new feature replaces the existing selection.
216+
87217
---
88218

89-
### `unselectFeature()`
219+
### `unselectFeature(featureInfo)`
90220

91-
Clear the currently selected feature.
221+
Programmatically unselect a specific feature.
222+
223+
| Parameter | Type | Description |
224+
|-----------|------|-------------|
225+
| `featureInfo.featureId` | `string` | The feature's identifier value |
226+
| `featureInfo.layerId` | `string` | Optional. The layer the feature belongs to |
227+
| `featureInfo.idProperty` | `string` | Optional. The property name used as the identifier |
92228

93229
```js
94-
interactPlugin.unselectFeature()
230+
interactPlugin.unselectFeature({
231+
featureId: 'abc123'
232+
})
95233
```
96234

97235
---
@@ -109,18 +247,22 @@ Emitted when the user confirms their selection (clicks "Done").
109247
**Payload:**
110248
```js
111249
{
112-
marker: { coords: [lng, lat] } | null,
113-
selection: { bounds: [...], feature: {...} } | null
250+
// If a marker was placed:
251+
coords: [lng, lat],
252+
253+
// If features were selected:
254+
selectedFeatures: [...],
255+
selectionBounds: [west, south, east, north]
114256
}
115257
```
116258

117259
```js
118-
interactiveMap.on('interact:done', ({ marker, selection }) => {
119-
if (marker) {
120-
console.log('Location selected:', marker.coords)
260+
interactiveMap.on('interact:done', (e) => {
261+
if (e.coords) {
262+
console.log('Location selected:', e.coords)
121263
}
122-
if (selection) {
123-
console.log('Feature selected:', selection.feature)
264+
if (e.selectedFeatures) {
265+
console.log('Features selected:', e.selectedFeatures)
124266
}
125267
})
126268
```
@@ -129,7 +271,7 @@ interactiveMap.on('interact:done', ({ marker, selection }) => {
129271

130272
### `interact:cancel`
131273

132-
Emitted when the user cancels the interaction.
274+
Emitted when the user cancels the interaction (clicks "Back").
133275

134276
**Payload:** None
135277

@@ -141,65 +283,44 @@ interactiveMap.on('interact:cancel', () => {
141283

142284
---
143285

144-
### `interact:markerchange`
145-
146-
Emitted when the marker position changes.
147-
148-
**Payload:**
149-
```js
150-
{
151-
coords: [lng, lat]
152-
}
153-
```
154-
155-
```js
156-
interactiveMap.on('interact:markerchange', ({ coords }) => {
157-
console.log('Marker moved to:', coords)
158-
})
159-
```
160-
161-
---
162-
163286
### `interact:selectionchange`
164287

165-
Emitted when the feature selection changes.
288+
Emitted whenever the feature selection changes.
166289

167290
**Payload:**
168291
```js
169292
{
170-
bounds: [west, south, east, north],
171-
feature: { ... }
293+
selectedFeatures: [
294+
{ featureId: '...', layerId: '...', properties: {...}, geometry: {...} }
295+
],
296+
selectionBounds: [west, south, east, north] | null,
297+
canMerge: boolean, // true when all selected features are contiguous
298+
canSplit: boolean // true when exactly one Polygon or MultiPolygon is selected
172299
}
173300
```
174301

175302
```js
176-
interactiveMap.on('interact:selectionchange', ({ bounds, feature }) => {
177-
console.log('Selection changed:', feature)
303+
interactiveMap.on('interact:selectionchange', (e) => {
304+
console.log('Selected features:', e.selectedFeatures)
305+
console.log('Bounds:', e.selectionBounds)
178306
})
179307
```
180308

181309
---
182310

183-
### `interact:selectFeature`
311+
### `interact:markerchange`
184312

185-
Emitted when a feature is programmatically selected via the API.
313+
Emitted when a location marker is placed or moved.
186314

187315
**Payload:**
188316
```js
189317
{
190-
feature: { ... }
318+
coords: [lng, lat]
191319
}
192320
```
193321

194-
---
195-
196-
### `interact:unselectFeature`
197-
198-
Emitted when a feature is programmatically unselected via the API.
199-
200-
**Payload:**
201322
```js
202-
{
203-
feature: { ... }
204-
}
323+
interactiveMap.on('interact:markerchange', ({ coords }) => {
324+
console.log('Marker moved to:', coords)
325+
})
205326
```

0 commit comments

Comments
 (0)