=== Cliq Store Locator ===
Contributors: cliqthemes
Tags: store locator, store finder, google maps, map, geolocation
Requires at least: 6.7
Tested up to: 7.0
Requires PHP: 8.1
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Show your stores on a searchable map. Visitors search by address and see the nearest locations, with distances.

== Description ==

Cliq Store Locator turns a list of addresses into a store finder your visitors can actually use. Add your locations in the WordPress admin, drop a block or shortcode on a page, and visitors type an address to see the nearest stores ranked by distance, plotted on an interactive map.

It works on activation. There is no account to create, no key to paste, and no trial clock. The default map is Leaflet with OpenStreetMap tiles and the default address lookup is Nominatim, both of which run without an API key. Google Maps is there if you would rather use it.

Whether you run one shop or a few hundred branches, the aim is the same: a fast, readable locator that fits your theme without writing code.

= Locations and content =

* Unlimited stores, each with address, phone, email, website, description and photo.
* Opening hours per store, shown on the store card and its own page.
* Categories and brands to group locations, with a category filter on the search form.
* Your own custom fields for anything the built-in fields do not cover.
* A dedicated page for every store, with a clean URL.

= Search =

* Address search with a distance radius, results sorted nearest-first.
* Distances in kilometres or miles, following your setting.
* "Use my location" for visitors who would rather not type an address.
* Category filtering alongside the address search.

= Maps =

* Leaflet with OpenStreetMap by default — no API key, no billing account.
* Google Maps as an alternative when you have a key.
* Marker clustering, so a dense city stays readable as visitors zoom out.
* Driving directions and a map popup for each location.
* Four bundled marker styles.

= Appearance =

* Five colour schemes — Indigo, Ocean, Forest, Ember and Midnight — plus a palette editor if none of them fit.
* Map on the right, on the left, or no map at all.
* Map height, default zoom, and how many results load at a time.
* Choose which fields appear on a store card, in a map popup, and on a store page.
* Rewrite the labels on buttons and fields to match your own wording.

= Findable and translatable =

* A title, description and Schema.org LocalBusiness data for each store page.
* Translated store content through WPML and Polylang.
* Right-to-left layouts supported.

= Privacy by default =

* No visitor submissions are stored and no analytics are recorded.
* External services are contacted only when the feature that needs them is used, and each one is listed under External Services below.
* Deleting the plugin removes everything it created, unless you ask it to keep your data.

= See it in action =

The demo site runs this plugin on one shared set of sample stores, so what changes between demos is the layout, not the data.

* [All demos](https://store-locator.cliqthemes.com/)
* [Documentation](https://store-locator.cliqthemes.com/docs/)

A few to start with:

* [Nordic Minimal](https://store-locator.cliqthemes.com/nordic-minimal/) — list beside a paper-style map
* [Corporate Trust](https://store-locator.cliqthemes.com/corporate-trust/) — results grouped into collapsible city sections
* [Coastal Airy](https://store-locator.cliqthemes.com/coastal-airy/) — category tiles that drill down into stores
* [Atlas Fullscreen](https://store-locator.cliqthemes.com/atlas-fullscreen/) — full-bleed map with the search floating over it
* [Monochrome Grid](https://store-locator.cliqthemes.com/monochrome-grid/) — a three-up card grid with no map
* [Accordion Directory](https://store-locator.cliqthemes.com/accordion-directory/) — a name-only list that expands in place
* [Harbour Teal](https://store-locator.cliqthemes.com/harbour-teal/) — photo markers and a map-led layout
* [Midnight Luxe](https://store-locator.cliqthemes.com/midnight-luxe/) — a dark kit with a scrolling list

This plugin gives you the list-and-map layout with the settings described above. The demos that rearrange the card, the search form or the map popup are built with the separate Pro plugin's layout builder.

= How it works =

1. **Install and activate.** A setup panel offers to create 20 sample stores so you can see the shape of it; skip it if you would rather start with your own.
2. **Add your stores.** Under **Store Locator → Store**, fill in the address, then use the **Pin Location** map to look up coordinates from that address or drag the pin to place it exactly.
3. **Put it on a page.** Add the **Store Locator** block, or use `[cliq_store_locator]` in any page, post or widget.
4. **Make it yours.** Set the layout, colour scheme, map height and visible fields under **Store Locator → Locator settings**.

= Who it suits =

Any business whose customers need to find a physical place:

* Retail chains and single shops
* Dealer and distributor networks
* Bank, insurance and agency branches
* Service and repair centres
* Restaurants, cafés and takeaways
* Clinics, pharmacies and healthcare providers
* Hotels and venues
* Gyms, studios and clubs
* Schools, campuses and training centres
* Franchise networks of any size

= Cliq Store Locator Pro =

Everything above is free and stays free. A separate Pro plugin, sold on our site, adds:

* A drag-and-drop layout builder for the card, search form, map popup and store page, with sixteen ready-made layouts to start from.
* A custom marker editor, plus per-category markers.
* CSV import and export for bulk store management.
* Lead-capture and store-registration forms with administrator approval.
* Visitor analytics — searches, store views and direction requests.

Details: [cliqthemes.com/store-locator](https://cliqthemes.com/store-locator/)

== Installation ==

1. Install and activate the plugin.
2. Open **Store Locator** in the admin menu. A setup panel offers to create 20 sample stores so you can see how it looks; skip it if you would rather start with your own.
3. Add your stores under **Store Locator → Store**. On a store's **Location** tab, fill in the address and use the **Pin Location** map to look up its coordinates from that address, or drag the pin to place it exactly.
4. Create a page and add the **Store Locator** block, or put `[cliq_store_locator]` in any page, post or widget.
5. Adjust how it looks under **Store Locator → Locator settings**.

== Frequently Asked Questions ==

= Do I need an API key? =

No. The default map is Leaflet with OpenStreetMap tiles, and the default address lookup is Nominatim. Neither needs a key. An API key is only needed if you switch the map or the address lookup to Google under **Store Locator → Locator settings**.

= Is any feature limited, trial-based, or unlocked by a licence? =

No. Every feature in this plugin is available immediately and permanently, with no licence check anywhere in its code.

= How many stores can I add? =

There is no limit in the plugin. Stores live in their own database tables and the locator loads results a page at a time, so a large list stays responsive.

= Does it work with my page builder? =

Yes. The locator is a block and a shortcode, so it works in the block editor and in builders that accept shortcodes, including Elementor, Divi and WPBakery, as well as classic themes.

= How much of the locator's appearance can I change? =

Under **Store Locator → Locator settings** you can set the layout (list and map side by side, list on either side, or list only), map height and default zoom, the colour scheme or your own palette, how many results load at a time, which fields appear on a store card, in a map popup and on a store page, the labels on buttons and fields, and which of the four bundled markers to use. Rearranging the card itself needs CSS, or the separate Pro plugin's layout builder.

= Why is "use my location" not working? =

Browsers only give a page the visitor's location over HTTPS. On an unencrypted site the browser blocks it before the plugin is involved. Address search is unaffected.

= The map is empty or the addresses have no pins. =

A store is only plotted once it has coordinates. Open the store's **Location** tab and use **Pin Location** to look them up from the address, or drag the pin. Stores imported without coordinates will not appear until they have them.

= Does it support marker clustering? =

Yes, on both Leaflet and Google maps. Nearby pins collapse into a single count as visitors zoom out, and separate again as they zoom in.

= Can I show the locator in more than one language? =

Yes. Store content is translatable through WPML and Polylang, the interface strings go through WordPress translation, and right-to-left layouts are supported.

= Where does the plugin store my stores? =

In its own database tables, each named with a `cliq_sl_` prefix, so it never reads or writes another plugin's data. Stores are not posts, so they do not appear under Posts or Pages.

= What happens if I delete the plugin? =

Deleting it removes its database tables, its settings, and the capability it added — everything it created. To keep your stores for a later reinstall, switch on **Keep data on uninstall** in the settings before deleting. Deactivating alone never removes anything.

= Where is the documentation? =

[store-locator.cliqthemes.com/docs](https://store-locator.cliqthemes.com/docs/)

== Screenshots ==

1. The locator on the front end — search form, result list and a map with clustered markers.
2. Selecting a store opens its info window on the map, with a directions link.
3. The Store Locator dashboard: directory overview, launch checklist and the shortcode to publish it.
4. Store list, with search, filters and configurable columns.
5. Editing a store — address fields and the map you drop the pin on.
6. Locator settings, Appearance — layout, map/store width, columns and map height.
7. Locator settings, Theme — palettes and colour tokens with a live preview.
8. Locator settings, Template — choose and reorder the fields on the store card, map info window and detail page.
9. Locator settings, Map & Search — map provider, map theme, distance unit and search defaults.
10. Locator settings, Details Page — enable per-store pages and build their URLs.
11. Categories, with icons and colours.
12. Brands, with logos and websites.
13. Custom fields, added to every store.

== External Services ==

The plugin communicates with an external service only when the related feature is used or configured.

= OpenStreetMap tile service =

When Leaflet is selected, the visitor's browser requests map tiles from OpenStreetMap. Tile coordinates, the visitor's IP address, and normal browser request information are sent to the service.

* Service: [https://www.openstreetmap.org/](https://www.openstreetmap.org/)
* Tile usage policy: [https://operations.osmfoundation.org/policies/tiles/](https://operations.osmfoundation.org/policies/tiles/)
* Privacy policy: [https://osmfoundation.org/wiki/Privacy_Policy](https://osmfoundation.org/wiki/Privacy_Policy)

= Nominatim =

Nominatim is the default geocoder. The address or coordinates being looked up, the requester's IP address, and normal request information are sent when a visitor searches for a location or an administrator geocodes a store.

* Service: [https://nominatim.openstreetmap.org/](https://nominatim.openstreetmap.org/)
* Usage policy: [https://operations.osmfoundation.org/policies/nominatim/](https://operations.osmfoundation.org/policies/nominatim/)
* Privacy policy: [https://osmfoundation.org/wiki/Privacy_Policy](https://osmfoundation.org/wiki/Privacy_Policy)

= Google Maps Platform =

When an administrator selects Google Maps or Google geocoding and supplies the required key, the plugin loads Google Maps JavaScript and Places in the browser and/or sends addresses and coordinates to the Google Geocoding API. Google receives normal request information such as the visitor's IP address and browser details.

* Service and terms: [https://cloud.google.com/maps-platform/terms](https://cloud.google.com/maps-platform/terms)
* Privacy policy: [https://policies.google.com/privacy](https://policies.google.com/privacy)

= OSRM routing =

When a visitor requests driving directions on a Leaflet map, the origin and destination coordinates are sent to the public OSRM routing service to calculate the route. The visitor's IP address and normal request information are also sent. Directions on a Google map use the Google service described above instead.

* Service: [https://project-osrm.org/](https://project-osrm.org/)
* Usage policy: [https://github.com/Project-OSRM/osrm-backend/wiki/Api-usage-policy](https://github.com/Project-OSRM/osrm-backend/wiki/Api-usage-policy)

= GeoJS approximate location =

If the administrator enables IP-based location fallback, and a visitor opens the locator without sharing a browser location, the visitor's browser requests approximate coordinates from GeoJS based on their IP address. The request is sent without cookies and without a referrer, and the result is only used to centre the map near the visitor.

* Service: [https://www.geojs.io/](https://www.geojs.io/)
* Privacy policy: [https://www.geojs.io/](https://www.geojs.io/)

= Google Fonts =

When an administrator selects a non-system font for the locator, the visitor's browser requests that stylesheet and its font files from Google Fonts. Google receives the visitor's IP address and normal browser request information. The default is a system font, which contacts nothing.

* Service: [https://fonts.google.com/](https://fonts.google.com/)
* Terms: [https://developers.google.com/fonts/terms](https://developers.google.com/fonts/terms)
* Privacy policy: [https://policies.google.com/privacy](https://policies.google.com/privacy)

= CliqThemes support email =

The support form on the plugin's own admin screen sends the name, email address, message, section, and site URL an administrator types into it to support@cliqthemes.com, using this site's configured WordPress mail system. Nothing is sent unless an administrator submits that form.

* Service operator: [https://cliqthemes.com/](https://cliqthemes.com/)

== Privacy ==

Store, category, brand, and settings data are stored in this site's WordPress database. The plugin keeps no visitor submissions and records no analytics, so it registers no personal-data exporter or eraser. It does supply suggested text for the WordPress Privacy Policy Guide describing the external services listed above.

Deleting the plugin removes its database tables, its options, and the capability it added, unless **Keep data on uninstall** is enabled in its settings. It schedules no recurring tasks.

== Third-Party Libraries ==

The plugin bundles the following open-source libraries, each unmodified, at the version shown, and each GPL-compatible.

* Leaflet 1.9.4 (BSD-2-Clause) — [https://leafletjs.com/](https://leafletjs.com/) — `resources/frontend/vendor/leaflet/`
* Leaflet.markercluster 1.5.3 (MIT) — [https://github.com/Leaflet/Leaflet.markercluster](https://github.com/Leaflet/Leaflet.markercluster) — `resources/frontend/vendor/leaflet.markercluster/`
* @googlemaps/markerclusterer 2.5.3 (Apache-2.0) — [https://github.com/googlemaps/js-markerclusterer](https://github.com/googlemaps/js-markerclusterer) — `resources/frontend/vendor/googlemaps-markerclusterer/`, shipped unminified
* @cliqthemes/glide-dropdown 0.3.0 (MIT) — [https://www.npmjs.com/package/@cliqthemes/glide-dropdown](https://www.npmjs.com/package/@cliqthemes/glide-dropdown) — `resources/frontend/vendor/glide-dropdown/`, shipped with its source map
* Preact 10.29.3 (MIT) — [https://preactjs.com/](https://preactjs.com/) — compiled into `resources/frontend/build/`
* Lucide React 0.378.0 (ISC) — [https://lucide.dev/](https://lucide.dev/) — compiled into the admin bundles
* enshrined/svg-sanitize (GPL-2.0-or-later) — [https://github.com/darylldoyle/svg-sanitizer](https://github.com/darylldoyle/svg-sanitizer) — full source in `vendor/enshrined/svg-sanitize/`

Every npm package above is resolved from the public npm registry by the `package-lock.json` in the plugin root, so `npm ci` reproduces exactly these versions.

== Development and Build ==

The human-readable source for every compiled asset ships inside the plugin, beside the `build` directory it compiles to: `resources/frontend/src`, `resources/locator-admin/src`, `resources/admin-common/src`, `resources/shared`, and `vendor/cliqthemes/ui/resources`. PHP source is in `includes`, and Composer dependency source in `vendor`.

To rebuild the bundled assets, install Node.js 18 or newer, change to the plugin directory, run `npm ci`, then `npm run build`. The `package.json`, `package-lock.json`, and `webpack.config.js` used for that build are in the plugin root. `npm run build` writes `resources/frontend/build`, `resources/locator-admin/build`, and `vendor/cliqthemes/ui/resources/admin/build` — the same files this plugin ships.

== Changelog ==

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.0.0 =
Initial release.
