Get Started

After successful UNZIP of the file EasyStoreLocator_UNZIP.zip you will find the module zip file and the ReadMe.txt file inside the folder.

• For Joomla 4.x, 5.x, and 6.x install: mod_store_locator_v1.9.zip

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

Go to Extensions > Extension Manager and click on the Upload Package File Tab.

Click on browse to choose the correct installation file and click on "Upload and Install"

Requirements:

• Joomla 4.x, 5.x, or 6.x
• PHP 8.0 or higher
• Google Maps API key (free tier available)

MODULE SETTINGS

• Google API Key: Google API key is mandatory for the store locator to work. Google API Link A comprehensive "How To" guide is available in the module parameters to help you obtain the API key.
• Map Height: Enter the height of the map in pixels or percentage. Examples: 500px, 50%, 400px, 100%
• Map Width: Enter the width of the map in pixels or percentage. Examples: 70%, 800px, 100%, 600px
• Sidebar Width: Enter the width of the sidebar in pixels or percentage. Examples: 30%, 200px, 25%, 300px
• Sidebar Position: Select the position of the sidebar - Left or Right side of the map.
• Zoom Level: Select the zoom level of the Google Maps (2 to 18).
• Show Get Directions Button: Toggle ON/OFF to display a "Get Directions" button in each location's info window. When enabled, clicking the button opens Google Maps directions for that location.
• Map Language: Set the language of the map from the list of over 40 predefined languages.
• Sensor: The sensor parameter indicates whether this application uses a sensor (such as a GPS locator) to determine the user's location. Note: This parameter is deprecated by Google but kept for backward compatibility.
• Search Filter: If set to ON, a search filter appears at the top of the sidebar where users can search for locations or addresses by typing. Real-time filtering as users type.

In the location settings click on the add button (+) and add a new slide. Upon clicking the following options will show up. You can add any number of slides and locations into the module.

• Latitude: Enter the latitude of the location. Must be a number between -90 and 90. Example: 37.7749
• Longitude: Enter the longitude of the location. Must be a number between -180 and 180. Example: -122.4194
• Title: Enter the title you would like to display for the location. This is required and will be shown in the sidebar and info window.
• Address: You can add additional content or address for the particular location. This will be displayed in the info window below the title.

Important Notes:

• All coordinates are automatically validated. Invalid coordinates will be filtered out.
• Locations without a title will be skipped.
• Use decimal format for coordinates (not degrees/minutes/seconds).
• See the "How To" tab for detailed instructions on obtaining coordinates.

Using these settings you will be able to control the color, font size, font weight, and alignment of the module text.

• Sidebar Position: Option to set the sidebar to the left or right of the Google Maps. This setting is also available in General Settings.
• Sidebar Width: Enter the width of the sidebar in pixels or percentage. Examples: 30%, 200px, 25%, 300px. This setting is also available in General Settings.
• Sidebar Background Color: Select the background color of the sidebar using the color picker.
• Sidebar Text Color: Select the font color of the text displayed in the sidebar.
• Sidebar Hover Color: Select the hover color that appears when users hover over sidebar items.
• Sidebar Border Color: Select the separator border color for the sidebar items.
• Sidebar Text Font Size: Enter the font size of the sidebar text in pixels. Example: 15 (which means 15 pixels). Default is 15px.
• Sidebar Text Align: Set the text alignment to left, center, or right.
• Sidebar Text Font Weight: You can set the font weight to normal or bold.

Note: The module automatically uses your template's font family. No additional font configuration is required.

• Module Class Suffix: Add a suffix class to the module to add extra CSS and customize the module. This allows you to target the module with custom CSS for advanced styling.
• Add Extra CSS: Directly add extra CSS into the module parameters to make any changes to the layout. This CSS will be added to the page head.
• Search Input Class: Option to define a custom CSS class for the Search Filter Input to match your template styling. This allows you to style the search input field independently.

Technical Notes:

• The module uses Joomla's WebAssetManager for loading CSS and JavaScript files.
• jQuery is loaded automatically through Joomla's framework.
• All assets are loaded in the document head for optimal performance.

The module includes a comprehensive "How To" guide built directly into the module parameters. This guide provides step-by-step instructions for:

• Getting a Google Maps API Key:
• Creating or selecting a project in Google Cloud Console
• Enabling the Maps JavaScript API
• Creating and restricting an API key
• Best practices for API key security
• Getting Latitude and Longitude:
• Method 1: Using Google Maps (right-click on location)
• Method 2: Using Google Maps URL (extract from URL)
• Method 3: Using online tools (latlong.net, gps-coordinates.net)
• Format requirements and coordinate ranges

To access the guide, navigate to the module parameters and click on the "How To" tab. The guide includes helpful links, screenshots descriptions, and multiple methods to help you get started quickly.

Common Issues and Solutions:

1. Map doesn't show up:

• Verify that you have entered a valid Google Maps API key in the General Settings
• Check that the API key has the Maps JavaScript API enabled
• Ensure your API key restrictions allow your domain
• Check browser console for any JavaScript errors

2. How to get latitude and longitude?

See the comprehensive guide in the "How To" tab, or visit: Google Maps Help

3. Locations not appearing:

• Verify that coordinates are in valid ranges (Latitude: -90 to 90, Longitude: -180 to 180)
• Ensure each location has a title (required field)
• Check that coordinates are in decimal format, not degrees/minutes/seconds
• Invalid coordinates are automatically filtered out for security

4. Search filter not working:

• Ensure "Search Filter" is set to ON in General Settings
• Check that you have locations added in Location Settings

5. Styling issues:

• Use Module Class Suffix to target the module with custom CSS
• Add custom CSS in the "Add Extra CSS" field in Advanced settings
• Check that your template's CSS is not overriding module styles

6. Get Directions button not showing:

• Ensure "Show Get Directions Button" is set to ON in General Settings
• Verify that locations have valid coordinates