Get Started

After successful UNZIP of the distribution package you will find the module ZIP file and documentation.

• For Joomla 4.x, 5.x, and 6.x install the provided mod_store_locator package (e.g. mod_store_locator_v2.x.zip).

Note: This module supports Joomla 4.x, 5.x, and 6.x only. Support for Joomla 3.x has been discontinued.

Go to System > Install > Extensions (or Extensions > Manage > Install in older menus) and use Upload Package File.

Browse to the module ZIP and click Upload & Install.

Requirements:

• Joomla 4.x, 5.x, or 6.x
• PHP 8.0 or higher
• Google Cloud project with Maps JavaScript API enabled
• A valid API key and (for advanced markers) a Map ID — see General Settings and the How To tab

MODULE SETTINGS

• Google API Key: Required. Create a key in Google Cloud Console, enable Maps JavaScript API, and restrict the key (recommended: HTTP referrers) to your live domain and any local dev URLs (e.g. http://localhost/yoursite/*). See the Troubleshoot tab if you see RefererNotAllowedMapError.
• Google Map ID: Required for Advanced Markers (the map uses google.maps.marker.AdvancedMarkerElement). Default DEMO_MAP_ID is suitable for testing. For production, create a Map ID under Google Cloud > Google Maps Platform > Map Management and paste it here.
• Map Height: Height of the map (e.g. 500px, 50vh, or 100%).
• Map Width: Width of the map (e.g. 70%, 800px).
• Sidebar Width: Width of the location list sidebar (e.g. 30%, 300px).
• Sidebar Position: Place the sidebar on the Left or Right of the map.
• Zoom Level: Initial map zoom (values from 2 to 18).
• Show Get Directions Button: When ON, each info window can include a button that opens Google Maps directions for that location.
• Map Language: Language code passed to the Maps JavaScript API (labels, etc.). Choose from the list.
• Search Filter: When ON, a search box appears above the sidebar list; typing filters locations by visible text.

Technical note: The Maps script is loaded with loading=async and the marker library. The deprecated sensor parameter is not used.

These options control how tall the map appears on smaller viewports (stacked layout). Desktop map height still comes from Map Height in General Settings.

• Tablet map min-height (max 1024px): Minimum height when the viewport width is 1024px or less (tablet / narrow desktop).
• Mobile map min-height (max 768px): Minimum height on typical phones. Increase (e.g. 320px) if the map feels too short.
• Small phone map min-height (max 480px): Minimum height on very narrow screens.
• Tablet / Mobile / Small phone map aspect (padding-bottom): Percentage of the map container width used for responsive height (aspect ratio trick). Defaults are 75%, 56.25% (16:9), and 100% respectively. Invalid values fall back to safe defaults.

Values are validated server-side and output as CSS on the map element for your module instance.

Use Add in the repeatable list to create each location.

• Latitude / Longitude: Decimal degrees. Latitude −90 to 90, longitude −180 to 180. Invalid rows are skipped.
• Title: Required. Shown in the sidebar and in the map info window.
• Address: Optional text (e.g. address) shown under the title in the sidebar and info window.
• Phone: Optional. Shown in the sidebar and as a tel: link in the info window.

Important: At least one valid location with a title and valid coordinates is required for the map to display.

See the How To tab for coordinate help.

Control sidebar colors, typography, spacing, and alignment.

• Sidebar Background Color: Background of the sidebar (color picker, supports RGBA).
• Sidebar Text Color: Main text color for list items.
• Sidebar Hover Color: Background when hovering a row (and selected row highlight).
• Sidebar Border Color: Separator line between rows.
• Sidebar Font Size: Base font size in pixels (e.g. 15).
• Sidebar Text Align: Left, center, or right.
• Sidebar Font Weight: Normal or bold.
• Sidebar item padding: CSS padding for each location row in the sidebar. Examples: 10px, 10px 12px, or four values for top/right/bottom/left. Units: px, %, em, rem, vh, vw.

Note: Sidebar position and width are set under General Settings, not here. The module uses your template’s font family unless you override with Add Extra CSS (Advanced tab).

Front-end labels such as “Get Directions”, search placeholder, and loading text use Joomla language files when available (multiple locales shipped).

• Module Class Suffix: Extra CSS class on the module wrapper for template-specific styling.
• Add Extra CSS: Raw CSS appended after the module’s inline styles (e.g. fine-tuning).
• Search Input Class: Optional extra class on the search field when Search Filter is enabled.

Technical notes:

• CSS and JS are registered via Joomla’s WebAssetManager where applicable.
• jQuery is loaded as a dependency for the locator script when required by the site.
• The Google Maps API is loaded asynchronously; initialization waits until the API is ready.

The module includes a How To field on the How To tab in the module edit screen with step-by-step help for:

• Google Maps API key: Cloud project, enabling Maps JavaScript API, credentials, and HTTP referrer restrictions (including localhost for development).
• RefererNotAllowedMapError: How to add matching referrers when the map is blocked.
• Latitude and longitude: Several methods and format rules.

Open the module → How To tab to read the full guide in the administrator.

Common issues:

1. Map does not load / grey map / console errors

• Confirm Maps JavaScript API is enabled for your Google Cloud project.
• Check the API key and billing (Google may require a billing account even with free tier credits).
• RefererNotAllowedMapError: Add your exact site URL pattern under API key → Application restrictions → HTTP referrers (e.g. https://www.example.com/*, http://localhost/j6/* for local Joomla in a subfolder).
• Ensure Map ID is valid for production (or use DEMO_MAP_ID for testing per Google docs).

2. Coordinates / locations missing

• Each location needs a title and valid lat/lng in decimal form.
• Out-of-range coordinates are ignored.

3. Search filter

• Enable Search Filter in General Settings and ensure locations exist.

4. Styling

• Use Module Class Suffix or Add Extra CSS; check template overrides.

5. Translations

• Install the matching Joomla language pack or use Language Overrides for strings such as MOD_STORE_LOCATOR_GET_DIRECTIONS.

Google Maps error reference: Maps JavaScript API error messages