Locations are a custom post type with an address and coordinates. A visitor\ntypes a place, picks a radius, and gets the nearest locations as pins on a map\nand as a list beside it. It ships as a shortcode and as a Bricks Builder\nelement.<\/p>\n\n
window.SLOSM<\/code> namespace on the front end.<\/li>\n- The REST API rather than admin-ajax.<\/strong> Four narrow, read-only routes.<\/li>\n
- Conditional assets.<\/strong> The clustering bundle downloads only when a locator\nactually needs it; a site with twenty branches never sees it.<\/li>\n
- Geocoding through a server-side proxy<\/strong>, with a thirty-day cache and a\none-request-per-second gap, so a visitor's browser never talks to the\ngeocoder itself and a failure is never cached.<\/li>\n
- Leaflet and Leaflet.markercluster are bundled rather than loaded from a CDN.<\/li>\n<\/ul>\n\n
Known limitations in this release<\/h4>\n\n
Worth reading before this goes on a site that matters.<\/p>\n\n
\n- The search button is new in this release, and there is no form around\nit.<\/strong> The address field has a Search button beside it now, running the same\nsearch Enter runs; with the suggestion list open, both take the highlighted\nsuggestion rather than looking the text up again. What this markup\ndeliberately does not have is a
<form><\/code>: that would make Enter submit the\npage for anybody the plugin's JavaScript has not reached yet, and a form\ninside a page builder's own form is discarded by the browser's parser with\nits controls handed to the outer one. If your theme or builder rebuilds the\nfilter bar and drops the button, the field still searches on Enter.<\/li>\n- The styling is two files, and you can switch one of them off.<\/strong> One holds\nthe layout \u2014 the map's box and its height floor, the results list beside or\nunder it, the suggestion popup, the dot marker \u2014 and is always loaded. The\nother is a skin: the spacing of the filter row and a border and padding on\nthe search field, the selects and the buttons, in the site's own font and\ncolour rather than the browser's. Untick \"Default styles\" on the Advanced tab\nto drop the skin and write your own; the map keeps its layout either way, so\nswitching it off cannot leave you with a map of no height, which is the usual\nway this kind of plugin appears broken.<\/li>\n
- The accessibility and translation passes are done; what is left is\nchecking them with real software.<\/strong> The search field is a combobox with a\nlistbox of suggestions, the arrow keys walk it, one status line announces\nwhat happened \u2014 including how many locations a search found \u2014 and opening a\nlocation's bubble moves the keyboard focus into it and gives it back when the\nbubble closes. The map's close button is labelled in your site's language\nrather than in English. None of that has been through NVDA, VoiceOver or\nOrca yet, and that check is listed as open rather than claimed as done.<\/li>\n
- One thing is deliberately left alone: the name inside a location's bubble is\nbold text and not a heading, because a heading needs a level and the right\nlevel depends on the page you drop the locator into.<\/li>\n
- Clustering at scale has not been measured on a real site either.<\/li>\n<\/ul>\n\n
The free services have limits, and a busy shop will meet them<\/h4>\n\n
The public OpenStreetMap geocoding service allows roughly one request a second\nand asks that heavy use go elsewhere. This plugin keeps to that limit and\ncaches hard, but a shop with real traffic needs its own instance or a paid\nprovider. That is a property of a free public service rather than of this\nplugin, and the endpoints are settings so a site can point at its own.<\/p>\n\n
Credits and licences<\/h4>\n\n\n- Leaflet 1.9.4, unmodified, BSD-2-Clause \u2014 https:\/\/leafletjs.com\/<\/li>\n
- Leaflet.markercluster 1.5.3, unmodified, MIT \u2014\nhttps:\/\/github.com\/Leaflet\/Leaflet.markercluster<\/li>\n
- Map data \u00a9 OpenStreetMap contributors \u2014\nhttps:\/\/www.openstreetmap.org\/copyright<\/li>\n<\/ul>\n\n
Both bundled libraries are GPL-compatible, and each ships with its own licence\nfile and a note recording where it came from and what its SHA-512 digest is.<\/p>\n\n
A note on the name<\/h4>\n\n
OpenStreetMap is a trademark of the OpenStreetMap Foundation. This plugin is an\nindependent piece of software that works with OpenStreetMap data and services;\nit is not endorsed by, affiliated with, or an official product of<\/strong> the\nOpenStreetMap Foundation. The name follows the Foundation's trademark policy,\nwhich permits naming software that works specifically with OpenStreetMap data,\nand asks for exactly this disclaimer alongside it.<\/p>\n\nLeaflet and Leaflet.markercluster are bundled here under their own licences and\nare likewise not affiliated with this plugin's author.<\/p>\n\n
External services<\/h3>\n\n
This plugin contacts three external services. Two of them are contacted by\nyour server; the third is contacted by every visitor's browser. None of them\nis contacted until something on the site actually asks for it.<\/p>\n\n
1. Nominatim, the OpenStreetMap geocoding service<\/h4>\n\n
What it is for.<\/strong> Turning an address into coordinates.<\/p>\n\nWhen.<\/strong> When a location is saved with an address and no coordinates, when\nthe bulk geocoder is run from the admin, and when a visitor submits a search.\nA result is cached for thirty days, so the same address is sent once.<\/p>\n\nWhat is sent.<\/strong> The address or search text, normalised; an ISO country code\nwhen the site has set one; and a User-Agent naming this plugin, its version\nand your site's home URL, which the service's usage policy asks for. The\nrequest is made by your server, so the visitor's IP address and cookies are\nnot part of it.<\/p>\n\nWhere.<\/strong> https:\/\/nominatim.openstreetmap.org\/search<\/code> by default. The\nendpoint is a setting: a site may point it at its own instance or at a paid\nprovider instead.<\/p>\n\nTerms and privacy.<\/strong> Nominatim Usage Policy:\nhttps:\/\/operations.osmfoundation.org\/policies\/nominatim\/ . Privacy policy of\nthe OpenStreetMap Foundation, which operates the service:\nhttps:\/\/osmfoundation.org\/wiki\/Privacy_Policy .<\/p>\n\n2. Photon, the address-suggestion service<\/h4>\n\n
What it is for.<\/strong> The suggestions that appear while a visitor types in the\nsearch field.<\/p>\n\nWhen.<\/strong> While typing, after a pause, and only when suggestions are switched\non. A suggestion list is cached for a day.<\/p>\n\nWhat is sent.<\/strong> The text typed so far and a result limit. As above, the\nrequest is made by your server rather than by the visitor's browser.<\/p>\n\nWhere.<\/strong> https:\/\/photon.komoot.io\/api<\/code> by default, and also a setting.<\/p>\n\nTerms and privacy.<\/strong> Photon is run by komoot. Its terms are a fair-use\nparagraph on the service's own page, https:\/\/photon.komoot.io\/ , which reads:\n\"You can use the API for your project, but please be fair - extensive usage\nwill be throttled. We do not guarantee for the availability and usage might be\nsubject of change in the future.\" The service publishes no privacy policy of\nits own, which is said here rather than papered over with a link to something\nelse. A site that needs a documented data-processing agreement for this should\npoint the setting at its own Photon instance, or switch suggestions off.<\/p>\n\n3. The OpenStreetMap tile server<\/h4>\n\n
What it is for.<\/strong> The map images themselves.<\/p>\n\nWhen.<\/strong> Every time a page carrying a map is viewed, from the visitor's own\nbrowser.<\/p>\n\nWhat is sent.<\/strong> What any image request sends: the visitor's IP address, their\nbrowser's User-Agent, and the coordinates of the tiles being looked at. This\nplugin sets no cookie of its own and neither the geocoding nor the suggestion\nrequest carries one.<\/p>\n\nWhere.<\/strong> https:\/\/tile.openstreetmap.org\/{z}\/{x}\/{y}.png<\/code> by default, and a\nsetting, so a site may use any tile provider it has the right to use.<\/p>\n\nTerms and privacy.<\/strong> Map data and attribution:\nhttps:\/\/www.openstreetmap.org\/copyright . Tile Usage Policy:\nhttps:\/\/operations.osmfoundation.org\/policies\/tiles\/ . Privacy policy of the\nOpenStreetMap Foundation: https:\/\/osmfoundation.org\/wiki\/Privacy_Policy .<\/p>\n\nNot a request, but worth saying<\/h4>\n\n
A \"directions\" link opens OpenStreetMap, or Google Maps if the site chose\nthat, in a new tab when a visitor clicks it<\/strong>. Nothing is sent anywhere until\nthey do, and the link can be turned off in the settings.<\/p>\n\n\n\n- Upload the plugin to
wp-content\/plugins\/<\/code>, or install it from the\nPlugins screen, and activate it.<\/li>\n- Add locations under Locations<\/strong>. Enter an address and press the button\nthat geocodes it, or type the coordinates directly.<\/li>\n
- Put a locator on a page: use the shortcode builder under Locations \u2192\nShortcode<\/strong>, or add the Store Locator<\/strong> element in Bricks.<\/li>\n
- Settings live under Locations \u2192 Settings<\/strong>.<\/li>\n<\/ol>\n\n
No API key, no account, and nothing to configure before the first map draws.<\/p>\n\n\n
\nDo I need a Google Maps API key, or a billing account?<\/h3><\/dt>\nNo. The map, the geocoding and the suggestions all use OpenStreetMap services,\nand the plugin works with the defaults it ships with.<\/p><\/dd>\n
Can I use it on a busy shop?<\/h3><\/dt>\nNot on the free public services alone. They allow about one request a second\nand ask that heavy use be moved elsewhere, and a shop with real traffic will\nreach that. The geocoding endpoint, the suggestion endpoint and the tile URL\nare all settings, so the answer is to point them at your own instance or at a\nprovider you pay. Please have that conversation before the traffic arrives\nrather than after.<\/p><\/dd>\n
What happens to my locations when I delete the plugin?<\/h3><\/dt>\nThey stay, unless you have asked for them to go.<\/p>\n\n
By default, deleting the plugin removes its settings, its two cache\ninvalidation counters and its own cached entries, and nothing else. Your\nlocations, their addresses and coordinates, and their categories are posts and\nterms in your database, and removing a plugin is not by itself a decision to\ndelete them.<\/p>\n\n
If you want them gone, the Advanced tab has a checkbox \u2014 \"Delete every\nlocation, category and setting when this plugin is deleted\"<\/em>. It is off by\ndefault<\/strong>, and while it is off, uninstalling keeps every location. Tick it and\ndeleting the plugin also deletes the slosm_store<\/code> posts with their meta,\nincluding any in the trash, and the location categories. Nothing else on the\nsite is touched: other post types, other taxonomies and other plugins' data are\nleft alone.<\/p>\n\nThat deletion cannot be undone from here, so please take a backup first if\nthere is any chance you will want the addresses back.<\/p><\/dd>\n
Does it work with Bricks Builder?<\/h3><\/dt>\nYes. The element registers itself when Bricks is present and does nothing at\nall when it is not, and it renders through the same code the shortcode uses, so\nthe two cannot drift apart. It was built against Bricks 2.4.<\/p><\/dd>\n