Get Started

After unzipping the distribution package you will find the module ZIP (e.g. mod_store_locator_2.1.zip) and documentation.

• Install via System → Install → Extensions → Upload Package File.
• Browse to the ZIP and click Upload & Install.

Requirements:

• Joomla 4.x, 5.x, or 6.x (Joomla 3 is not supported)
• PHP 8.0+
• Google Cloud project with Maps JavaScript API enabled
• A valid API key and a Map ID for Advanced Markers (use DEMO_MAP_ID for testing)

After install: Content → Site Modules → New → Easy Store Locator, paste your API key, add locations (or Import & Demo), publish to a position, and clear cache.

Configure the Google Maps connection and basic map behaviour.

• Google Maps API Key — Required. Enable Maps JavaScript API and restrict the key with HTTP referrers (live domain + localhost if needed).
• Map ID — Required for Advanced Markers. Default DEMO_MAP_ID is fine for testing; create a production Map ID under Google Cloud → Map Management.
• Map Language — Language for Google Maps UI labels.
• Map Height — e.g. 560px or 70vh.
• Fit All Stores on Load — Auto-zoom so every location is visible. When OFF, use Fallback Zoom.

The Maps script loads with loading=async and the marker library. The deprecated sensor parameter is not used.

Choose how the map and store list are arranged.

• Design — Classic (map + sidebar), Split (equal columns), Overlay (floating panel), Cards (map on top, cards below), or Map only (full map; list via toggle).
• Sidebar Side — Left or right (Classic / Split / Overlay).
• Map Width / Sidebar Width — Classic layout only (percentages such as 68% / 32%).
• Show Sidebar — OFF starts with the list collapsed (Map only always starts collapsed).
• Sidebar Toggle Button — Floating control so visitors can show/hide the list. Always available when the list starts hidden.

• Search Box — Live filter by name, area, address, phone, hours, or category (with highlight and clear).
• Category Chips — Filter chips when stores have a Category filled in.
• Get Directions Button — Opens Google Maps directions from the info window.
• Result Count — Compact “N stores” badge under the search box.

Info windows can also show Call, Email, and Website when those fields are set on a store.

Use Add in the repeatable list, or fill the list via the Import & Demo tab.

• Store Name — Required.
• Category — Optional group for chips (e.g. Flagship, Outlet).
• Address, Phone, Email, Website, Opening Hours, Short Description — Optional.
• Latitude / Longitude — Required decimal degrees (lat −90…90, lng −180…180). Invalid rows are skipped.
• Pin Accent Color — Colour for that store’s pin and list highlight.

At least one valid location is required for the map to display. See the How To tab for coordinate help.

• Load Demo Stores — Inserts sample London locations so you can preview layouts immediately. Save the module afterwards.
• CSV Import — Upload a CSV to fill Locations. Required columns: title, latitude, longitude. Optional: category, address, phone, email, website, hours, description, pin_color.
• Download the sample CSV from the Import field, then replace or append rows as needed.

Open the Locations tab after import to review rows before saving.

• Accent — Buttons, chips, and active highlights.
• Panel Background / Text / Hover / Borders — Sidebar colours (RGBA supported).
• Corner Radius — 0–48px (12+ uses pill-style controls).
• Title Size / Weight / Align — List typography.
• Row Padding — e.g. 14px 16px.

Map / sidebar widths and sidebar side are under Layout. Front-end strings (Search, Get Directions, Hide list, etc.) come from Joomla language files.

• Min map height — Separate minima for ≤1024px, ≤768px, and ≤480px viewports.
• Module Class Suffix — Extra class on the module wrapper.
• Search Extra Class — Optional class on the search input.
• Extra CSS — Custom CSS for this instance (dangerous constructs are stripped).
• Layout — Joomla alternate layout override if you provide one.

Technical notes: Vanilla JS (no jQuery). Assets via WebAssetManager. Joomla 5 services architecture (Dispatcher / Helper / Field). Google Maps loads asynchronously.

Open the module → How To tab for the built-in guide covering:

• Creating a Google Cloud project and enabling Maps JavaScript API
• Creating and restricting an API key (HTTP referrers for production and localhost)
• Fixing RefererNotAllowedMapError
• Getting latitude / longitude from Google Maps or online tools
• CSV import columns and demo content

1. Map does not load / grey map

• Enable Maps JavaScript API; check billing and the API key.
• RefererNotAllowedMapError — Add matching HTTP referrers (e.g. https://www.example.com/*, http://localhost/demo/*).
• Use a valid Map ID, or DEMO_MAP_ID for testing.

2. No markers

• Each store needs a title and valid lat/lng. Out-of-range rows are ignored.

3. Search / categories

• Turn Search Box / Category Chips ON under Features; fill Category on stores for chips.

4. Styling conflicts

• Use Module Class Suffix or Extra CSS; clear Joomla and browser cache.

5. Translations

• Override keys such as MOD_STORE_LOCATOR_SEARCH_PLACEHOLDER under System → Language Overrides.

Google reference: Maps JavaScript API error messages