JEM Venues Map Module

Module name: JEM - Venues Map Module
Extension: mod_jem_map
Current versions: JEM 5.0.1 stable, JEM 5.0.2 Beta 1 and JEM 5.1.0 Beta 4
Joomla compatibility: Joomla 5.4 or later and Joomla 6.x

Overview

The JEM Venues Map Module displays published JEM venues on an interactive OpenStreetMap or Google Maps map. It can show every accessible geocoded venue or restrict the results by event date, category and country.

The module can be used for:

A general directory of venues.
A map of venues hosting events today or during a selected period.
A category-specific event-location map.
A country or regional venue map.
A visitor-oriented map with current-location and directions controls.
A heatmap showing concentrations of displayed venues.

Important: a venue is displayed only when it is published, accessible to the visitor and has valid latitude and longitude values. If a venue is missing, edit it and verify its coordinates, publication state and access level.

Version Compatibility

JEM version	Status	Map module support
JEM 5.0.1	Stable	OpenStreetMap and Google Maps providers, date/category/country filters, geolocation, heatmap and configurable popup actions.
JEM 5.0.2 Beta 1	Beta	Uses the same map configuration as JEM 5.0.1 together with the maintenance fixes included in the 5.0 branch.
JEM 5.1.0 Beta 4	Beta	Adds the Event hierarchy filter and applies the JEM 5.1 venue hierarchy, resource access and age-access rules.

Beta notice: JEM 5.0.2 Beta 1 and JEM 5.1.0 Beta 4 are testing releases. Use a staging website and keep a complete backup before testing them with production data.

Requirements

JEM must be installed and enabled.
The website must use Joomla 5.4 or later, or Joomla 6.x.
At least one published and accessible venue must have valid coordinates.
Date and category filtering require published events assigned to those venues.
Google Maps requires a Google API key in JEM Settings.
Visitor geolocation requires browser support and visitor permission.
Geolocation normally requires HTTPS, although browsers usually allow it on localhost for development.

Where to Find It

Open the Joomla administrator.
Go to System → Manage → Site Modules.
Select New.
Choose JEM - Venues Map Module.
Select a suitable template position and menu assignment.
Configure the provider, map position, filters, markers and visitor controls.

Standard Joomla Module Settings

Option	Description	Recommendation
Title	Name used in the Joomla module manager and, optionally, on the frontend.	Use a descriptive name such as Event venues near you.
Show Title	Shows or hides the Joomla module title.	Hide it for full-width map sections or show it when the context is not otherwise clear.
Position	Template position where the map is rendered.	A wide content position is recommended.
Status	Publishes or unpublishes the module.	Published.
Access	Determines which Joomla viewing levels can see the module.	Public unless the venue information is restricted.
Menu Assignment	Controls the pages on which the module appears.	Use a dedicated map page or selected JEM pages.

Map Position and Provider

Option	Default	Description
Auto center map	Yes	Calculates the centre from the venues currently displayed. Google Maps also fits the viewport to the marker bounds. Leaflet uses the calculated centre with the configured zoom.
Map center latitude	`54.526`	Fallback latitude used when automatic centring is disabled or there are no displayed venues.
Map center longitude	`15.255`	Fallback longitude used when automatic centring is disabled or there are no displayed venues.
Default map zoom	`4`	Initial zoom level from 0, representing a world view, to 19, representing street-level detail.
Map provider	OpenStreetMap / Leaflet	Selects OpenStreetMap with Leaflet or Google Maps.
Map height	`500px`	CSS height of the map container. Values such as `500px`, `40rem` or `60vh` can be used.

Map Providers

Provider	Requirements	Behaviour
OpenStreetMap / Leaflet	No JEM API key is required.	Uses the bundled Leaflet, fullscreen and heatmap libraries with OpenStreetMap tiles.
Google Maps	A Google API key must be configured in JEM Settings → System Integrations → Google API-Key.	Uses the Google Maps JavaScript API and its visualisation library.

Google Maps without an API key: if Google Maps is selected but no Google API key is configured, the embedded map falls back to Leaflet/OpenStreetMap. The popup destination links are still generated for the provider selected in the module. Select OpenStreetMap explicitly if both the embedded map and external actions should consistently use OpenStreetMap services.

Map and Popup Controls

Option	Default	Description
Full screen button	No	Adds the JEM Leaflet fullscreen control. Google Maps uses the controls provided by Google Maps itself.
Show directions link	Yes	Adds a Get directions link to every venue marker popup.
Show full map link	Yes	Adds an Open full map link to every venue marker popup.
Set Heatmap Layer	Yes	Adds a heatmap generated from the coordinates of the currently displayed venues.

The external popup actions depend on the selected provider:

OpenStreetMap uses the OpenStreetMap map and routing services.
Google Maps uses Google Maps search and directions URLs.
External links open in a new browser tab.

The heatmap uses one point per displayed venue. It visualises venue concentration and is not weighted by the number of events assigned to each venue.

Visitor Location

Option	Default	Description
Show my location	Yes	Displays a button that requests the visitor's current position through the browser Geolocation API.
You are here location marker	`media/com_jem/images/marker-blue.webp`	Image used for the visitor's position marker.

When permission is granted, the module:

Adds a marker representing the visitor's position.
Displays an accuracy circle based on the value reported by the device.
Centres the map on the visitor with a detailed zoom level.
Replaces an earlier visitor marker if the position is requested again.

The visitor's coordinates are used in the browser and are not saved as JEM data by this module. The selected map provider and browser may still process map or location-related requests according to their own policies.

If permission is denied, unavailable or times out, the module displays an explanatory message. Permission must then be changed in the visitor's browser or device settings.

Date Filter

Option	Default	Description
Show date filter	Yes	Displays date controls above the map and enables event-based venue filtering.
Default date filter	All	Determines the initially selected date period. It applies only when Show date filter is enabled.

Date value	Result
All	Shows every published, accessible venue with valid coordinates, including venues without events.
Today	Shows venues hosting an event active today.
Tomorrow	Shows venues hosting an event active tomorrow.
Week	Shows venues hosting an event between today and the end of the current week.
Month	Shows venues hosting an event between today and the final day of the current month.
Year	Shows venues hosting an event between today and 31 December of the current year.
Date	Displays a date field so that the visitor can select one specific day.

An event matches a period when its date range overlaps that period. A multi-day event can therefore make its venue visible on any day covered by the event.

The preset date buttons submit automatically. The custom Date option uses its date input and the Apply button.

Category Filter

Option	Default	Description
Show category filter	No	Displays a single-category selector above the map.
Categories	Empty	Restricts event-based venue results to one or more selected JEM categories.

The backend Categories selection restricts map results even when the frontend category selector is hidden.
If no backend categories are selected, all accessible published categories are allowed.
If the frontend selector is enabled, visitors can select one category at a time.
When backend categories are configured, only those categories are offered in the frontend selector.
Selecting All categories still respects the categories configured by the administrator.
A category filter means that only venues hosting a matching published and accessible event are displayed.

Country Filter

Option	Default	Description
Show country filter	No	Displays a country selector above the map.
Default country filter	All countries	Restricts the initial map results to one country. Leave empty to allow every country.

The default country restriction applies even when the frontend country selector is hidden.
When the selector is visible, visitors can change the country or return to All countries.
The selector contains countries used by published, accessible venues with valid coordinates.
Country names are displayed using JEM's country catalogue.

Venue Markers and Types

Option	Default	Description
Marker image path for venues	`media/com_jem/images/marker-red.webp`	Fallback marker image for venues that do not have a valid Venue Type icon.
You are here location marker	`media/com_jem/images/marker-blue.webp`	Marker image used for the visitor's geolocation result.

Marker paths can reference a site-relative SVG, PNG or WebP file. An external URL is also accepted, although a local file is usually more reliable and avoids an additional third-party request.

If a configured local marker cannot be found, JEM tries the supplied default marker.

Venue Type Markers

When a venue has a published and accessible JEM Venue Type with an icon:

JEM generates a coloured marker containing the Venue Type icon.
The venue's own marker colour has priority.
If the venue has no custom marker colour, the Venue Type colour is used.
JEM calculates a contrasting icon colour for readability.
The configured marker image is used as the fallback when no valid Venue Type icon is available.

Introductory and Footer Content

Option	Default	Description
Show intro text	No	Enables editor content above the map and its controls.
Intro text	Empty	Safe HTML displayed before the module output.
Show footer text	No	Enables editor content below the map.
Footer text	Empty	Safe HTML displayed after the module output.

Advanced Options

Option	Default	Description
Alternative Layout	Default	Selects the supplied default layout or a compatible layout override from the active template.
Module Class	Empty	Adds one or more CSS classes to the Joomla module container.
Caching	Use Global	Uses Joomla's global module caching setting or disables caching for this instance.
Cache Time	`900`	Cache lifetime in seconds. The default is 15 minutes.

Disable module caching temporarily when testing filters or frequently changing venue/event data. Also clear Joomla, browser, server and CDN caches if a previous marker set remains visible.

Available Layout

The module supplies one selectable layout:

Layout	Description
`default`	Renders the optional filters and location controls, followed by the interactive map and marker popups.

Template Layout Override

Copy the supplied PHP layout to:

/templates/YOUR_TEMPLATE/html/mod_jem_map/default.php

Do not modify the original file in /modules/mod_jem_map/tmpl/, because a JEM update can replace it.

CSS Overrides

The module loads two stylesheets in this order:

mod_jem_map.css for map-specific controls and filter presentation.
default.css for the selected layout and Venue Type marker presentation.

Complete template stylesheet overrides can be stored at:

/templates/YOUR_TEMPLATE/css/mod_jem_map/mod_jem_map.css
/templates/YOUR_TEMPLATE/css/mod_jem_map/default.css

The alternative template HTML-directory locations are:

/templates/YOUR_TEMPLATE/html/mod_jem_map/mod_jem_map.css
/templates/YOUR_TEMPLATE/html/mod_jem_map/default.css

Stylesheet Search Order

For each stylesheet, JEM uses the first matching file in this order:

/templates/YOUR_TEMPLATE/css/mod_jem_map/FILENAME.css
/templates/YOUR_TEMPLATE/html/mod_jem_map/FILENAME.css
/media/mod_jem_map/css/FILENAME.css
/modules/mod_jem_map/tmpl/FILENAME.css

Shared Module CSS

Smaller additive rules shared with other JEM modules can be placed in:

/media/com_jem/css/custom/jem-user-module.css

This file is loaded after both map-module stylesheets.

Do not rename mod_jem_map.css: unlike several older JEM module stylesheets, this remains the current base filename for the Map Module. It is not part of the legacy filename migration table.

Frontend Behaviour

The module displays distinct venues rather than one marker for every matching event.
Only published and accessible venues with coordinates are considered.
All mode can include venues that currently have no event.
Date or category filtering requires at least one matching published and accessible event at the venue.
Multi-day events match every filter period with which their date range overlaps.
The country and category selectors submit automatically when changed.
Date presets submit automatically; a custom date is applied using the Apply button.
The venue name in a popup links to the JEM venue page.
Popups contain the venue name, city, country flag and optional external map actions.
Joomla and JEM access levels are applied before venue, country and category options are generated.

Configuration Examples

1. General Venue Directory

Map provider: OpenStreetMap / Leaflet
Auto center map: Yes
Show date filter: Yes
Default date filter: All
Categories: Empty
Default country filter: All countries
Show my location: Yes
Set Heatmap Layer: Yes
Map height: 500px

Shows every accessible geocoded venue, including venues without current events.

2. Events Taking Place Today

Map provider: OpenStreetMap / Leaflet
Show date filter: Yes
Default date filter: Today
Show category filter: No
Show country filter: No
Show directions link: Yes
Show full map link: Yes
Full screen button: Yes
Map height: 60vh

Displays only venues with an event active today and provides visitor navigation controls.

3. Music Venues This Month

Categories: Concerts, Festivals, Live Music
Show category filter: Yes
Show date filter: Yes
Default date filter: Month
Auto center map: Yes
Set Heatmap Layer: Yes
Show my location: Yes

Visitors can select one of the allowed music categories, while the administrator-defined category restriction remains active.

4. Country-Specific Google Map

Map provider: Google Maps
Google API-Key: Configured in JEM Settings
Default country filter: Spain
Show country filter: No
Show date filter: Yes
Default date filter: Year
Show directions link: Yes
Show full map link: Yes

The country restriction remains active even though visitors cannot change it.

5. Fixed-Centre City Map

Auto center map: No
Map center latitude: 40.4168
Map center longitude: -3.7038
Default map zoom: 12
Default country filter: Spain
Set Heatmap Layer: No
Map height: 550px
Intro text: Information about the covered city or region

Keeps a consistent city-centred viewport even if the currently displayed venues are concentrated in one district.

Operational Limitation: Multiple Module Instances

Use one JEM Venues Map Module instance per page with the supplied layout. The map containers themselves use unique identifiers, but some filter and geolocation controls still use page-wide IDs or selectors. Two map instances on the same page can therefore cause a control in one module to operate on the other instance.

A custom template override would need to make every control identifier and JavaScript selector instance-specific before several map modules can be used safely on the same page.

Troubleshooting

Problem	Likely cause	Suggested check
No venues appear.	No accessible venue has valid coordinates, or active filters exclude every venue.	Check publication, access, latitude, longitude, country, category and date filters.
A venue appears in All mode but disappears with a date filter.	The venue has no matching published and accessible event in that period.	Check the event venue, date range, publication window, categories and access level.
The category selector does not contain every category.	The module Categories option or visitor access level limits the available choices.	Review the backend Categories selection and category access levels.
The country selector does not contain a country.	No accessible published geocoded venue uses an active country entry.	Check the venue country, coordinates, publication, access and country catalogue state.
The map is centred incorrectly.	Auto center is disabled, no venue remains after filtering or the manual coordinates are incorrect.	Enable Auto center or verify the fallback latitude, longitude and zoom.
Google Maps was selected but OpenStreetMap appears.	The JEM Google API key is empty.	Configure the key in JEM Settings under System Integrations or select OpenStreetMap explicitly.
The visitor-location button does not work.	Geolocation is unsupported, blocked, denied or unavailable in the current security context.	Use HTTPS and review browser, operating-system and device location permissions.
A custom marker is ignored.	The path is invalid, or a Venue Type icon takes priority.	Verify the file path and check the Venue Type assigned to the venue.
The marker opens the wrong or non-SEF venue URL.	The Joomla menu structure or SEF routing context is incomplete.	Create or review the relevant JEM menu item and clear the Joomla routing cache.
The map overlaps template navigation or dialogs.	A template z-index or positioning rule conflicts with Leaflet or Google Maps.	Inspect the active template CSS and add a narrowly scoped override.
Filters show previous results.	A module, Joomla, browser, server or CDN cache is serving old output.	Temporarily disable module caching and clear every active cache layer.
A CSS override is ignored.	The wrong file was overridden or the active template/path is incorrect.	Check both `mod_jem_map.css` and `default.css`, then clear caches.
Controls affect another map on the same page.	Several module instances are sharing page-wide control identifiers.	Use one instance per page or implement an instance-safe template override.

Appendix: What Is New in JEM 5.1.0 Beta 4

Event Hierarchy Filter

JEM 5.1.0 Beta 4 adds the Event hierarchy option. In this module it controls which events can make a venue appear when a date or category filter is active.

Event hierarchy has no visible effect when the map uses All, no category restriction is configured and no event-based filtering is required. In that situation, the module displays venues directly, including venues without events.

Value	Behaviour
Calendar default	Uses top-level events plus programme items whose Show in general calendars option is enabled.
Parent events only	Only parent or top-level events can make a venue appear.
Subevents only	Only programme items or child events can make a venue appear.
Parent events and subevents	Both hierarchy levels can make a venue appear.

Beta example: Conference Session Locations

Event hierarchy: Subevents only
Categories: Conference sessions
Show category filter: Yes
Show date filter: Yes
Default date filter: Today
Auto center map: Yes
Show directions link: Yes

Shows the venues or subvenues used by today's programme sessions without allowing the parent conference alone to add another location.

Venue Hierarchy and Resource Visibility

JEM 5.1.0 applies venue hierarchy and resource-level visibility before map results and filter countries are generated. A visitor only receives venues that are visible through the current Joomla/JEM access configuration.

Age-Aware Event Filtering

When the map uses event-based date or category filtering, JEM 5.1.0 applies the effective event and venue age-access rules. Events hidden from an identified registered user because of their age classification do not make a venue appear through that event filter.

All mode without an event-based filter remains a venue map. It is not automatically converted into an event-age filter.