PluginProbe
Leaflet Map / trunk
Leaflet Map vtrunk
3.4.7 3.4.6 trunk 2.10.0 2.10.1 2.11.0 2.11.1 2.11.2 2.11.3 2.11.4 2.11.5 2.12.0 2.13.0 2.14.0 2.15.0 2.16.0 2.16.1 2.16.2 2.17.0 2.17.1 2.17.2 2.17.3 2.18.0 2.19.0 2.19.1 All 49 releases
leaflet-map / README.md

README.md in Leaflet Map trunk, at README.md

442 lines 22.4 KB
No matching file
Up and down to move Enter to open Esc to close
Raw Download Zip
1 # Leaflet Map WordPress Plugin
2
3 ![Leaflet](https://img.shields.io/badge/leaflet-1.7.1-green.svg?style=flat)
4 ![WordPress](https://img.shields.io/badge/wordpress-5.6.1-green.svg?style=flat)
5
6 ![Header Image](https://ps.w.org/leaflet-map/assets/banner-1544x500.png?rev=1693083)
7
8 Add a map generated with [](http://leafletjs.com/LeafletJS](http://leafletjs.com/](http://leafletjs.com/): an open-source JavaScript library for mobile-friendly interactive maps. Map tiles are provided by default through [](http://www.openstreetmap.org/OpenStreetMap](http://www.openstreetmap.org/](http://www.openstreetmap.org/), or [](https://www.mapquest.ca/MapQuest](https://www.mapquest.ca/](https://www.mapquest.ca/) (with an app key). Can be set per map with shortcode attributes or through the dashboard settings.
9
10 ![Admin Screenshot](https://imgur.com/W4BGTif.jpg)
11
12 ## Table of Contents
13
14 - [](#leaflet-map-wordpress-pluginLeaflet Map WordPress Plugin](#leaflet-map-wordpress-plugin](#leaflet-map-wordpress-plugin)
15 - [](#table-of-contentsTable of Contents](#table-of-contents](#table-of-contents)
16 - [](#installationInstallation](#installation](#installation)
17 - [](#general-usageGeneral Usage](#general-usage](#general-usage)
18 - [](#developingDeveloping](#developing](#developing)
19 - [](#available-shortcodesAvailable Shortcodes](#available-shortcodes](#available-shortcodes)
20 - [](#leaflet-map[leaflet-map]](#leaflet-map](#leaflet-map)
21 - [](#leaflet-map-options[leaflet-map] Options:](#leaflet-map-options](#leaflet-map-options)
22 - [](#leaflet-image[leaflet-image]](#leaflet-image](#leaflet-image)
23 - [](#leaflet-image-options[leaflet-image] Options:](#leaflet-image-options](#leaflet-image-options)
24 - [](#leaflet-wms[leaflet-wms]](#leaflet-wms](#leaflet-wms)
25 - [](#leaflet-wms-options[leaflet-wms] Options:](#leaflet-wms-options](#leaflet-wms-options)
26 - [](#leaflet-marker[leaflet-marker]](#leaflet-marker](#leaflet-marker)
27 - [](#leaflet-marker-options[leaflet-marker] Options:](#leaflet-marker-options](#leaflet-marker-options)
28 - [](#leaflet-line[leaflet-line]](#leaflet-line](#leaflet-line)
29 - [](#leaflet-line-options[leaflet-line] Options](#leaflet-line-options](#leaflet-line-options)
30 - [](#leaflet-polygon[leaflet-polygon]](#leaflet-polygon](#leaflet-polygon)
31 - [](#leaflet-circle[leaflet-circle]](#leaflet-circle](#leaflet-circle)
32 - [](#leaflet-circle-options[leaflet-circle] Options](#leaflet-circle-options](#leaflet-circle-options)
33 - [](#leaflet-geojson[leaflet-geojson]](#leaflet-geojson](#leaflet-geojson)
34 - [](#leaflet-geojson-options[leaflet-geojson] Options](#leaflet-geojson-options](#leaflet-geojson-options)
35 - [](#leaflet-kml[leaflet-kml]](#leaflet-kml](#leaflet-kml)
36 - [](#leaflet-gpx[leaflet-gpx]](#leaflet-gpx](#leaflet-gpx)
37 - [](#leaflet-scale[leaflet-scale]](#leaflet-scale](#leaflet-scale)
38 - [](#leaflet-image-overlay[leaflet-image-overlay]](#leaflet-image-overlay](#leaflet-image-overlay)
39 - [](#leaflet-video-overlay[leaflet-video-overlay]](#leaflet-video-overlay](#leaflet-video-overlay)
40 - [](#frequently-asked-questionsFrequently Asked Questions](#frequently-asked-questions](#frequently-asked-questions)
41 - [](#how-can-i-add-another-leaflet-pluginHow Can I Add another Leaflet Plugin?](#how-can-i-add-another-leaflet-plugin](#how-can-i-add-another-leaflet-plugin)
42 - [](#contributingContributing](#contributing](#contributing)
43 - [](#wish-listWish List](#wish-list](#wish-list)
44
45 ## Installation
46
47 - Install via the WordPress plugins page on your WordPress site: `/wp-admin/plugin-install.php` (search Leaflet)
48
49 ## General Usage
50
51 ```
52 [leaflet-map address="Manhattan, New York"]
53 [leaflet-marker]
54 ```
55
56 The above shortcode will produce a map centered at Manhattan, New York (thanks to geocoding), and also drop a marker in the center.
57
58 It's also useful to add popups to the markers:
59
60 ```
61 [leaflet-map address="Las Vegas"]
62 [leaflet-marker]Hey! This is where I got married![/leaflet-marker]
63 ```
64
65 You can have SVG markers, add shapes, geojson, kml, images, and more! See available shortcodes below.
66
67 ## Developing
68
69 This plugin uses Docker for development. Simply:
70
71 1. [](https://www.docker.com/get-startedinstall Docker](https://www.docker.com/get-started](https://www.docker.com/get-started)
72 1. fork/clone the repo, and
73 1. execute this command from the repo's root directory in your terminal:
74
75 ```bash
76 docker compose up
77 ```
78
79 You can also use NPM scripts to interact with Docker, if you make changes to Docker-related files:
80
81 To start:
82
83 ```bash
84 npm start
85 ```
86
87 To completely remove:
88
89 ```bash
90 npm run destroy
91 ```
92
93 That's all for now! Thanks!
94
95 ## Available Shortcodes
96
97 ### [leaflet-map]
98
99 ![Alternate map tiles](https://imgur.com/oURcNiX.jpg)
100
101 Height, width, latitude, longitude and zoom are the basic attributes:
102
103 ```
104 [leaflet-map height=250 width=250 lat=44.67 lng=-63.61 zoom=5]
105 ```
106
107 However, you can also just give it an address, and the chosen geocoder (default: Nominatum) will look it up for you:
108
109 ```
110 [leaflet-map address="Oslo, Norway"]
111 ```
112
113 When using the OpenStreetMap Nominatim geocoder, the plugin sends a contact email in the request user agent. By default this uses the site admin email, but you can override it in the plugin settings with `Nominatim Contact Email (optional)` or in code with the `leaflet_map_nominatim_contact_email` filter.
114
115 ```php
116 add_filter('leaflet_map_nominatim_contact_email', function ($email) {
117 return 'maps@example.com';
118 });
119 ```
120
121 #### [leaflet-map] Options:
122
123 | Option | Default |
124 | ---------------------------- | ---------------------------------------------------- |
125 | `lat` and `lng` or `address` | lat: 44.67, lng: -63.61 |
126 | `zoom` | 12 |
127 | `height` | 250 |
128 | `width` | 100% |
129 | `fitbounds` | 0 (false) |
130 | `zoomcontrol` | 0 (false) |
131 | `scrollwheel` | 0 (false) |
132 | `doubleclickzoom` | 0 (false) |
133 | `min_zoom` | 0 |
134 | `max_zoom` | 20 |
135 | `subdomains` | abc |
136 | `attribution` | ©Leaflet ©OpenStreetMap |
137 | `closepopuponclick` | false |
138 | `trackresize` | false |
139 | `boxZoom` | true |
140 | `dragging` | true |
141 | `keyboard` | true |
142 | `maxbounds` | null |
143 | `detect-retina` | 0 (false) |
144 | `tileurl` | 'https://tile.openstreetmap.org/{z}/{x}/{y}.png' |
145 | `subdomains` | 'abc' |
146 | `tap` | true |
147 | `tilesize` | 256 |
148 | `mapid` | null |
149 | `accesstoken` | null |
150 | `zoomoffset` | 0 |
151 | `nowrap` | false |
152
153 ---
154
155 ### [leaflet-image]
156
157 Much the same as leaflet-map above, but uses `src` for the source image.
158
159 TBH, it's a huge mess, and probably shouldn't be used. It might make a good image viewer with optional marker highlight points. It requires far too much manual work at the moment. Recommended usage:
160
161 ```
162 [leaflet-image src="path/to/img.jpg" zoom=1]
163 [leaflet-marker draggable]
164 ```
165
166 Then in the console, check the coordinates when you move the marker (should only work at that zoom level).
167
168 #### [leaflet-image] Options:
169
170 | Option | Default |
171 | ----------------- | -------------------------------- |
172 | `src` | https://picsum.photos/1000/1000/ |
173 | `zoom` | 12 |
174 | `height` | 250 |
175 | `width` | 100% |
176 | `fitbounds` | 0 (false) |
177 | `zoomcontrol` | 0 (false) |
178 | `scrollwheel` | 0 (false) |
179 | `doubleclickzoom` | 0 (false) |
180 | `min_zoom` | 0 |
181 | `max_zoom` | 20 |
182 | `attribution` | ©Leaflet ©OpenStreetMap |
183 | `x` | 0 |
184 | `y` | 0 |
185
186 ---
187
188 ### [leaflet-wms]
189
190 Much the same as leaflet-map above, but for wms services and uses `src` for the service url,
191 `layer` for the layer name and `crs` for the coordination system (only supported by
192 leaflet: EPSG:3857 and EPSG:4326).
193 ```
194 [leaflet-wms source="https://your/wms/service?" layer="yourLayer" crs="EPSG:3857" zoom=1]
195 ```
196
197 #### [leaflet-wms] Options:
198
199 | Option | Default |
200 | ----------------- | ----------------------------------------- |
201 | `src` | https://ows.mundialis.de/services/service? |
202 | `layer ` | TOPO-OSM-WMS |
203 | `crs ` | EPSG:3857 |
204 | `zoom` | 12 |
205 | `height` | 250 |
206 | `width` | 100% |
207 | `fitbounds` | 0 (false) |
208 | `zoomcontrol` | 0 (false) |
209 | `scrollwheel` | 0 (false) |
210 | `doubleclickzoom` | 0 (false) |
211 | `min_zoom` | 0 |
212 | `max_zoom` | 20 |
213 | `attribution` | ©Leaflet ©OpenStreetMap |
214 | `lat` | 0 |
215 | `lng` | 0 |
216
217 ---
218
219 ### [leaflet-marker]
220
221 ![Markers with HTML within a popup](https://imgur.com/ap38lwe.jpg)
222
223 Add a marker to any map by adding `[leaflet-marker]` after any `[leaflet-map]` shortcode. You can adjust the lat/lng in the same way, as well as some other basic functionality (popup message, draggable, visible on load). Also, if you want to add a link to a marker popup, use `[leaflet-marker]Message here: click here[/leaflet-marker]` and add a link like you normally would with the WordPress editor.
224
225 #### [leaflet-marker] Options:
226
227 | Option | Usage |
228 | ---------------------------- | ------------------------------------------------------------------------------------------ |
229 | `lat` and `lng` or `address` | Location on the map; defaults to map center; `lat`/`lng` are floats, `address` is a string |
230 | `draggable` | Make a marker draggable (`boolean`); default `false` |
231 | `title` | Add a hover-over message to your marker (different than popup) |
232 | `alt` | Add an alt text to the marker image |
233 | `zindexoffset` | Define the z-index for the marker image |
234 | `opacity` | Define the css opacity for the marker image |
235 | `iconurl` | Give a url for the marker image file |
236 | `iconsize` | Set the size of the icon: e.g. "80,50" for 80px width 50px height |
237 | `iconanchor` | Set the anchor position of the icon: e.g. "40,60" for 40px left 60px top |
238 | `shadowurl` | Give a url for the marker shadow image file |
239 | `shadowsize` | Set the size of the shadow: e.g. "80,50" for 80px width 50px height |
240 | `shadowanchor` | Set the anchor position of the shadow: e.g. "40,60" for 40px left 60px top |
241 | `popupanchor` | Set the anchor position of the popup: e.g. "40,60" for 40px left 60px top |
242 | `tooltipanchor` | Set the anchor position of the tooltip: e.g. "40,60" for 40px left 60px top |
243 | `svg` | Boolean for whether the marker should be created as an svg: default `false` |
244 | `background` | Background color for an SVG marker (above) |
245 | `color` | color of the SVG marker (above) |
246 | `iconclass` | className for the marker image |
247
248 ---
249
250 ### [leaflet-line]
251
252 ![Fitted Colored Line](https://imgur.com/dixNDtF.jpg)
253
254 Add a line to the map by adding `[leaflet-line]`. You can specify the postions with a list separated by semi-colon `;` or bar `|` using lat/lng: `[leaflet-line latlngs="41, 29; 44, 18"]` or addresses: `[leaflet-line addresses="Istanbul; Sarajevo"]`, or x/y coordinates for image maps.
255
256 Add a popup to the line by adding text to the content of the shortcode:
257
258 `[leaflet-line addresses="new york; chicago"]New York to Chicago[/leaflet-line]`
259
260 #### [leaflet-line] Options
261
262 | Option | Usage |
263 | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
264 | `addresses`, `latlngs`, or `coordinates` | For geocoded addresses, latitude/longitude, or x/y coordinates for Image Maps; ex: `[leaflet-line latlngs="41, 29; 44, 18"]` or addresses: `[leaflet-line addresses="Istanbul; Sarajevo"]` |
265 | `fitbounds` | Fit the map to the bounds of the line (instead of whatever center you gave the map originally) |
266
267 And the following Shape Options. See https://leafletjs.com/reference.html#path for details.
268 'stroke', 'color', 'weight', 'opacity',
269 'lineCap', 'lineJoin', 'dashArray', 'dashOffset'
270 'fill', 'fillColor', 'fillOpacity', 'fillRule', 'className'
271
272 ---
273
274 ### [leaflet-polygon]
275
276 Virtually the same as [](aboveleaflet-line](above](above)
277
278 ---
279
280 ### [leaflet-circle]
281
282 ![Circle](https://i.imgur.com/rVHH6Zm.png?1234)
283
284 Add a circle to the map by adding `[leaflet-circle]`. You can specify the position using `lat` and `lng` and the radius in meters using `radius`. You can also customize the style using [](https://leafletjs.com/reference.html#pathLeaflet's Path options](https://leafletjs.com/reference.html#path](https://leafletjs.com/reference.html#path). Example: `[leaflet-circle message="max distance" lng=5.1179 lat=52.0979 radius=17500 color="#0DC143" fillOpacity=0.1]`.
285
286 #### [leaflet-circle] Options
287
288 | Options | Usage |
289 | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
290 | `address`, `lat/lng`, or `x/y` | For geocoded addresses, latitude/longitude, or x/y coordinates for Image Maps (see [leaflet-image]); ex: `[leaflet-circle lat=52 lng=5]` or addresses: `[leaflet-circle address="Amsterdam"]` |
291 | `fitbounds` | Fit the map to the bounds of the circle (instead of whatever center you gave the map originally) |
292 | radius | Radius of the circle in meters |
293
294 Includes all style options: See https://leafletjs.com/reference.html#path
295
296 ---
297
298 ### [leaflet-geojson]
299
300 [](https://gist.github.com/bozdoz/064a7101b95a324e8852fe9381ab9a18![Random GeoJSON created by me](https://imgur.com/fJktgtI.jpg)](https://gist.github.com/bozdoz/064a7101b95a324e8852fe9381ab9a18](https://gist.github.com/bozdoz/064a7101b95a324e8852fe9381ab9a18)
301
302 Or you can add a geojson shape via a url:
303
304 ```
305 [leaflet-geojson src="https://gist.githubusercontent.com/bozdoz/064a7101b95a324e8852fe9381ab9a18/raw/03f4f54b13a3a7e256732760a8b679818d9d36fc/map.geojson"]
306 ```
307
308 #### [leaflet-geojson] Options
309
310 | Option | Usage |
311 | ---------------- | ------------------------------------------------------------------------------------------------ |
312 | `src` | Source of the geojson file |
313 | `popup_text` | Text for any popups when shapes are clicked |
314 | `popup_property` | Name of the geojson property that contains popup content |
315 | `fitbounds` | Fit the map to the bounds of all shapes (instead of whatever center you gave the map originally) |
316 | `circleMarker` | Display circles instead of markers. Vastly improves performance on maps with a lot of points. |
317 | `radius` | Radius of the circles, when `circleMarkers` is set |
318 | `table-view` | Show all properties on each feature when clicked |
319 | `iconurl` | Give a url for the marker image file |
320 | `iconsize` | Set the size of the icon: e.g. "80,50" for 80px width 50px height |
321 | `iconanchor` | Set the anchor position of the icon: e.g. "40,60" for 40px left 60px top |
322 | `popupanchor` | Set the anchor position of the popup: e.g. "40,60" for 40px left 60px top |
323 | `tooltipanchor` | Set the anchor position of the tooltip: e.g. "40,60" for 40px left 60px top |
324
325 Includes all style options: See https://leafletjs.com/reference.html#path. Also, if you want to add feature
326 properties to the popups, use the inner content and curly brackets to substitute the values:
327 `[leaflet-geojson]Field A = {field_a}[/leaflet-geojson]`.
328
329 ### [leaflet-kml]
330
331 Same idea as geojson (above), but takes KML files and loads [](https://github.com/mapbox/togeojsonMapbox's togeojson library](https://github.com/mapbox/togeojson](https://github.com/mapbox/togeojson)
332
333 ### [leaflet-gpx]
334
335 Same idea as geojson and KML (above), but takes GPX files and also loads [](https://github.com/mapbox/togeojsonMapbox's togeojson library](https://github.com/mapbox/togeojson](https://github.com/mapbox/togeojson)
336
337 ### [leaflet-scale]
338
339 Can be added after any map, or enabled for all maps in the admin. If you want to extend it, you can extend window.WPLeafletMapPlugin.createScale with custom JavaScript.
340
341 | Option | Default |
342 | ---------------- | --------- |
343 | `maxWidth` | 100 |
344 | `metric` | 1 (true) |
345 | `imperial` | 1 (true) |
346 | `updateWhenIdle` | 0 (false) |
347 | `position` | topright |
348
349 ### [leaflet-image-overlay]
350
351 ```
352 [leaflet-image-overlay src="https://www.lib.utexas.edu/maps/historical/newark_nj_1922.jpg" bounds="40.799311,-74.118464;40.68202047785919,-74.33"]
353 ```
354
355 #### [leaflet-image-overlay] Options
356
357 | Option | Usage |
358 | ----------------- | ----------------------------------------------------------------------------- |
359 | `src` | Source of the image file |
360 | `bounds` | coordinates for south-west, and north-east coordinates |
361 | `interactive` | triggers mouse events (not recommended) |
362 | `opacity` | 0 - 1 for opaciity of the image |
363 | `alt` | alt attribute for the image |
364 | `crossOrigin` | Whether the crossOrigin attribute will be added to the image |
365 | `errorOverlayUrl` | URL to the overlay image to show in place of the overlay that failed to load. |
366 | `zIndex` | The explicit zIndex of the overlay layer |
367 | `className` | The className attribute for the image |
368 | `attribution` | String to be shown in the attribution control |
369
370 ### [leaflet-video-overlay]
371
372 Same options as [leaflet-image-overlay]
373
374 ```
375 [leaflet-video-overlay src="https://www.mapbox.com/bites/00188/patricia_nasa.webm" bounds="32,-130;13,-100"]
376 ```
377
378 ## Frequently Asked Questions
379
380 ### How Can I Add another Leaflet Plugin?
381
382 There are some steps you can take, currently, to add another Leaflet Plugin to enhance this WordPress plugin. In general, you can add an action to trigger when Leaflet is loaded, and add custom JavaScript and any dependencies your plugin needs:
383
384 Here's an example with MapBox Fullscreen plugin:
385
386 functions.php
387
388 ```php
389 add_action('leaflet_map_loaded', 'fs_leaflet_loaded');
390 function fs_leaflet_loaded() {
391 wp_enqueue_script('full_screen_leaflet', 'https://api.mapbox.com/mapbox.js/plugins/leaflet-fullscreen/v1.0.1/Leaflet.fullscreen.min.js', Array('wp_leaflet_map'), '1.0', true);
392 wp_enqueue_style('full_screen_leaflet_styles', 'https://api.mapbox.com/mapbox.js/plugins/leaflet-fullscreen/v1.0.1/leaflet.fullscreen.css');
393
394 // custom js
395 wp_enqueue_script('full_screen_custom', get_theme_file_uri( '/js/full-screen.js' ), Array('full_screen_leaflet'), '1.0', true);
396 }
397 ```
398
399 /js/full-screen.js
400
401 ```js
402 (function () {
403 function main() {
404 if (!window.WPLeafletMapPlugin) {
405 console.log('no plugin found!');
406 return;
407 }
408
409 // iterate any of these arrays: `maps`, `markers`, `lines`, `circles`, `geojsons`
410 var maps = window.WPLeafletMapPlugin.maps;
411
412 // Note: `markergroups` is an *object*. If you'd like to iterate it, you can do it like this:
413 // var markergroups = window.WPLeafletMapPlugin.markergroups;
414 // var keys = Object.keys(markergroups);
415 // for (var i = 0, len = keys.length; i < len; i++) {
416 // var markergroup = markergroups[keys[i]];
417 // }
418
419 for (var i = 0, len = maps.length; i < len; i++) {
420 var map = maps[i];
421 map.whenReady(function () {
422 this.addControl(new L.Control.Fullscreen());
423 });
424 }
425 }
426
427 window.addEventListener('load', main);
428 })();
429 ```
430
431 ### Are there some examples for adding a Leaflet Plugin and other functions?
432
433 Take a look at the functions of [](https://wordpress.org/plugins/extensions-leaflet-map/Extensions for Leaflet Map](https://wordpress.org/plugins/extensions-leaflet-map/](https://wordpress.org/plugins/extensions-leaflet-map/).
434
435 ## Contributing
436
437 [](https://github.com/bozdoz/wp-plugin-leaflet-map/blob/master/CONTRIBUTING.mdView Contribution guidelines](https://github.com/bozdoz/wp-plugin-leaflet-map/blob/master/CONTRIBUTING.md](https://github.com/bozdoz/wp-plugin-leaflet-map/blob/master/CONTRIBUTING.md)
438
439 ## Wish List
440
441 - A map editor/shortcode generator (so users can see what they're adding to the page)
442