=== My Store Locator – Store Finder & Dealer Map ===
Contributors: mystorelocator
Tags: store locator, store finder, dealer locator, map, locations
Requires at least: 6.3
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Show your stores, dealers or branches on a searchable map. Connects to the My Store Locator service (hosted in Germany). Block, shortcode, Elementor.

== Description ==

My Store Locator puts a store finder on your WordPress site: a map with a searchable list of your stores, dealers, branches, partners or service points – with opening hours, categories, filters, "use my location" and directions.

**This plugin is a connector for the My Store Locator service.** You manage locations, opening hours and the look of the map in the web app at [my-store-locator.com](https://my-store-locator.com/en/?utm_source=wordpress&utm_medium=integration&utm_campaign=wordpress-plugin). The plugin embeds that map on your pages. You need an account – the Free plan (25 locations, one map) costs nothing. Paid plans add more locations, maps and templates.

= What the plugin does =

* **Block** "My Store Locator" for the block editor, with all options in the sidebar and a live preview.
* **Shortcode** `[my_store_locator]` for classic content, page builders and theme templates.
* **Elementor widget** (only loaded when Elementor is active).
* **Widget areas:** use the block or the classic widget.
* **Settings → My Store Locator:** connect your account with one click or paste a map token, save several maps, choose defaults.
* **Strict consent mode (on by default):** visitors first see a short notice and a "Load map" button. Before that click the browser makes no request to the service at all – the map script is only loaded after the click. Consent tools can unlock the maps through a small JavaScript API.
* **Automatic height:** the map grows with its content, no scrollbar inside a scrollbar. A sticky header offset keeps the map's search below your fixed header.
* **Lazy loading**, German and English map language (follows your site language by default).
* **"Create a store locator page"** helper: one click creates a draft page with the block.
* The map script is only loaded on pages that contain a map.

= What the service offers =

* 10 map templates (list + map, finder, full-screen explorer, single location and more – depending on the plan). Changing the template never changes your embed.
* Your brand colour, marker colour, fonts and corner style.
* Search by name, city or postcode, "near me", categories, statuses, "open now", custom field filters.
* Opening hours with two time slots per day and special days.
* CSV import (up to 5,000 rows per run) and export.
* Contact form on the map with an enquiry inbox in the app.
* Statistics as aggregated daily counters – no cookies, no stored IP addresses.
* Maps are OpenStreetMap based; map tiles and address search run through the service's own servers, so your visitors' browsers do not contact OpenStreetMap directly.
* Hosted in Germany. A data processing agreement (Art. 28 GDPR) is available in the app.

= Shortcode =

`[my_store_locator]` – the default map from the settings.

`[my_store_locator map="YOUR-TOKEN" height="auto" lang="de" consent="true"]`

Attributes (all optional, empty = value from the settings):

* `map` – map token, the name of a saved map, or a saved map ID.
* `height` – `auto` or a height such as `640px` or `80vh`.
* `lang` – `de` or `en`.
* `consent` – `true` or `false` (click to load).
* `lazy` – `true` or `false`.
* `offset` – height of a sticky header in pixels.
* `layout` – `split` for list and map side by side (Finder template with automatic height).

== External services ==

This plugin embeds maps from **My Store Locator**, a service operated by Internet am Dornbusch, Inh. Sajjad Hanifa, Eschersheimer Landstraße 297, 60320 Frankfurt am Main, Germany. The servers are located in Germany. Without the service the plugin cannot show a map.

**When a visitor views a page with a map** (with consent mode: only after the visitor clicks the "Load map" button or your consent tool gives consent – before that, no request is made to the service), the visitor's browser loads the script `https://app.my-store-locator.com/widget.js` and the map from `https://app.my-store-locator.com`. The service receives the usual connection data of the browser (IP address, user agent, the page that embeds the map) and the map token. When the visitor uses the map, the service also receives what is needed for that function: search terms, the location when "use my location" is allowed, the start point of a route, and the content of an enquiry when the contact form is sent. The service counts map views and interactions as aggregated daily numbers without cookies and without storing IP addresses.

**When an administrator clicks "Connect with My Store Locator"** in Settings → My Store Locator, the browser opens `https://app.my-store-locator.com/connect` with the address of the settings page (to return to) and a random one-time value. After login the browser comes back with the public map token and the map name. No password or API key is stored in WordPress.

The plugin itself sends no data to any server, does not track visitors or administrators and does not "phone home". Links to my-store-locator.com in the admin area carry campaign parameters (utm) so the service knows a sign-up came from the plugin.

* Terms of service: [German](https://my-store-locator.com/agb/), [English](https://my-store-locator.com/en/terms/)
* Privacy policy: [German](https://my-store-locator.com/datenschutz/), [English](https://my-store-locator.com/en/privacy/)

== Installation ==

1. Install the plugin from Plugins → Add New (search for "My Store Locator") and activate it.
2. Go to Settings → My Store Locator.
3. Click "Connect with My Store Locator", log in and pick a map – or paste a map token, the embed code or the public map link from the app (Maps → your map → Embed) into "Add a map manually".
4. Add the block "My Store Locator" to a page (or use the shortcode `[my_store_locator]`, the Elementor widget or a widget area). Or click "Create a store locator page".

No account yet? [Create a free account](https://app.my-store-locator.com/#/register?utm_source=wordpress).

== Frequently Asked Questions ==

= Do I need an account? =

Yes. Your locations and the map live in the My Store Locator web app. The Free plan is free of charge (25 locations, one map, templates 1–3). Paid plans: Starter $20 per month, Pro $50 per month, Business on request (prices plus VAT; yearly billing is 20 % cheaper). New accounts start with a 14-day trial of the Pro features.

= Where do I find my map token? =

In the app, open Maps, choose your map and go to Embed. You can paste the token, the complete embed code or the public map link – the plugin extracts the token itself.

= Is it GDPR compliant? =

The service is hosted in Germany and offers a data processing agreement (Art. 28 GDPR) in the app. Consent mode is on by default: visitors see a notice and load the map with a click, so no data is transmitted before that. Please mention the map in your privacy policy. Whether your whole site is compliant depends on your setup – this is not legal advice.

= What exactly happens in consent mode? =

The page contains only a placeholder with a notice and a "Load map" button, and a small script that ships with the plugin. No request goes to app.my-store-locator.com – not even for the map script. After the click, the plugin loads `https://app.my-store-locator.com/widget.js` and shows the map. The choice is not stored; each page view starts with the placeholder unless a consent tool unlocks the maps (see next question).

= I already use a cookie / consent tool (Borlabs Cookie, Complianz, Real Cookie Banner …). =

You have two options:

1. **Keep the plugin's placeholder and let your consent tool unlock it.** Create a service "My Store Locator" in your tool (provider: Internet am Dornbusch, host `app.my-store-locator.com`, privacy policy https://my-store-locator.com/datenschutz/) and add this as the opt-in code that runs when the visitor accepts it:
   `<script>window.myStoreLocatorConsentGranted = true; window.MyStoreLocatorConsent && window.MyStoreLocatorConsent.grant();</script>`
   * Borlabs Cookie: Services (Cookies) → add a service → "Opt-in Code".
   * Real Cookie Banner: Services → add a service → "Code on opt-in".
   * Complianz: Integrations → Script Center → add a script (without the script tags) in the matching category, so Complianz runs it after consent.
   The menu names differ between versions of these tools.
   Any other tool: call `window.MyStoreLocatorConsent.grant()` or dispatch the event `mystorelocator:consent` on `document`.
2. **Let your consent tool block the map instead.** Turn off consent mode (settings, or `consent="false"` per map) and add the URL `app.my-store-locator.com` (script `widget.js`) to your tool's script/content blocker. Developers can also use the filter `mystorelocator_consent_required`.

Check the result in a private window: before consent there must be no request to app.my-store-locator.com (browser developer tools → Network).

= Does it work with WooCommerce? =

Yes. WooCommerce needs nothing special: put the block or the shortcode on any page, for example a "Find a store" or "Dealers" page, and link it from your menu, product pages or footer. Your locations are managed in My Store Locator, not as WooCommerce products.

= Does it work with Elementor, Divi, other page builders or my theme? =

The Elementor widget is built in. Every other builder can use the shortcode `[my_store_locator]` (usually in a "shortcode" or "text" element). The map works with any theme.

= Can I show more than one map? =

Yes. Save several maps in the settings and pick one per block, widget or shortcode (`map="name of the saved map"`). Your plan decides how many maps you can create in the app.

= The "Connect" button does not work. =

You can always paste the map token instead – it is the same thing. The token is public (it is part of every embed code), so it is safe to paste.

= Does the plugin slow down my site? =

The map script is only loaded on pages that contain a map, asynchronously and in the footer. With lazy loading the map loads when it scrolls into view; with consent mode the script and the map load only after the click (the page itself only gets a tiny local script).

= Can I change the look of the map? =

Yes, in the app: template, colours, fonts, corners, map style and which fields are shown. Changes apply on your site immediately – no need to touch WordPress.

== Screenshots ==

1. Store finder on a page (Finder template, automatic height).
2. Consent mode: nothing is loaded from the service until the visitor clicks "Load map".
3. The block in the editor with its settings in the sidebar.
4. Settings → My Store Locator: connect, saved maps and display defaults.
5. The Elementor widget.

== Changelog ==

= 1.0.0 =
* First release: strict click-to-load consent mode (no request to the service before the click, consent tool API), block, shortcode, Elementor widget, classic widget, settings page with connect button and manual token, several saved maps, consent mode, automatic height, sticky header offset, lazy loading, split layout, "create a store locator page" helper, German translation.

== Upgrade Notice ==

= 1.0.0 =
First release.
