Events Map displays JEM events geographically on an interactive map. It is designed for sites where the location of the event is as important as the event date or category: festivals, cultural agendas, regional directories, museum programmes, venue networks and community calendars.
The map uses event data together with venue coordinates. For an event to appear accurately on the map, it must be assigned to a venue with valid latitude and longitude values.
Marker icons from JEM 5.0.1: Events Map can use icons assigned to event, category and venue types. The configured venue marker remains available as the fallback when no applicable type icon is defined.
When To Use This View
| Scenario | Recommended use | Why |
|---|
| Regional event directory |
Show all events with venue coordinates. |
Visitors can discover events by location. |
| Festival or city agenda |
Use category and date filters. |
Visitors can narrow the map to the events they want. |
| Country-specific event map |
Enable country filter or set a default country. |
Keeps the map focused when the site has international venues. |
| Venue network |
Use a wider zoom and marker clustering or heat behaviour where available. |
Shows event distribution across many locations. |
| Mobile discovery page |
Enable “My location” and use a practical map height. |
Users can relate events to their current position. |
Data Requirements
| Requirement | Needed for | Notes |
|---|
| Event assigned to a venue |
Map marker creation. |
Events without a venue cannot be positioned geographically. |
| Venue latitude |
Map marker position. |
Use decimal coordinates. |
| Venue longitude |
Map marker position. |
Use decimal coordinates. |
| Published event |
Frontend visibility. |
Unpublished events are not normally shown to visitors. |
| Accessible category and event |
Permission-aware output. |
JEM respects Joomla and JEM access rules. |
| Type icon |
Custom map marker. |
Optional. An icon can be assigned to an event type, category type or venue type. |
Map Options
| Option | Default | Purpose |
|---|
| Map center latitude |
54.526 |
Fallback latitude used to centre the map. |
| Map center longitude |
15.255 |
Fallback longitude used to centre the map. |
| Map zoom |
4 |
Initial zoom level. Lower values show larger areas; higher values show more detail. |
| Map provider |
OpenStreetMap |
Selects OpenStreetMap/Leaflet or Google Maps. Google Maps requires a valid API key in JEM settings. |
| Map type |
Political |
Chooses the base map style, such as political or physical. |
| Show my location |
Yes |
Allows visitors to use their browser location if supported and permitted. |
| Full screen map |
Yes |
Allows a larger map experience where supported by the layout. |
| Show directions link |
Yes |
Shows a navigation link in each marker popup. |
| Show full map link |
Yes |
Shows a link that opens the selected coordinates in the full external map. |
| Heat layer |
Yes |
Highlights geographic concentration of events. |
| Venue marker file |
media/com_jem/images/marker-red.webp |
Fallback marker image used when the applicable event, category and venue types do not provide an icon. |
| My location marker file |
media/com_jem/images/marker-blue.webp |
Marker image used only for the visitor’s own location. |
| Map height |
500px |
Controls the visible height of the map area. |
| Show events table |
Yes |
Displays the event list below the map. |
Frontend Filters
The Events Map view can expose filters directly to visitors. These filters are especially useful when the map contains many markers.
| Filter | Default | Visitor effect |
|---|
| Date filter |
Shown |
Allows filtering by all events, today, tomorrow, week, month, year or a specific date. |
| Date filter default |
All |
Defines the initial date range when the page loads. |
| Category filter |
Hidden |
Allows visitors to filter events by category. |
| Category selection |
Empty |
Can limit the available categories shown in the map filter. |
| Country filter |
Hidden |
Allows visitors to filter events by venue country. |
| Default country |
None |
Starts the map filtered to one country when required. |
Date Filter Behaviour
| Mode | Result | Recommended use |
|---|
| All |
Shows all available mapped events. |
Best for small datasets or general discovery maps. |
| Today |
Shows events taking place today. |
Useful for “What is happening now?” pages. |
| Tomorrow |
Shows events taking place tomorrow. |
Useful for short-term agenda discovery. |
| Week |
Shows events from today until the end of the current week. |
Good default for local event sites. |
| Month |
Shows events from today until the end of the current month. |
Good for cultural agendas and monthly programmes. |
| Year |
Shows events from today until the end of the current year. |
Useful for annual festival or season maps. |
| Specific date |
Shows events on the selected date. |
Useful when visitors plan around a particular day. |
Category And Country Filtering
Category and country filters are optional. They should be enabled when the map contains enough events that visitors need a way to reduce the marker set.
| Configuration | Best for | Notes |
|---|
| No category filter |
Small maps with few categories. |
Keeps the interface simple. |
| Category filter enabled |
Large programmes with many topics. |
Visitors can focus on concerts, talks, tours, workshops or other categories. |
| No country filter |
Single-country sites. |
A country selector is unnecessary if all events are local. |
| Country filter enabled |
International or multi-region sites. |
Visitors can quickly reduce the visible area. |
| Default country set |
Sites with a primary country and occasional international venues. |
The page opens focused, but can still allow wider discovery if the filter is shown. |
Map Markers And Event Popups
Each marker represents a venue with one or more events in the selected date and filter range. Its popup normally contains the venue name, the matching events and links to the corresponding detail pages.
Marker Icon Priority
JEM uses the most specific available type icon. The priority for Events Map is:
- Event type icon
- Category type icon
- Venue type icon
- Configured global venue marker
The configured venue marker is therefore a fallback, not an override for an assigned type icon. With the default configuration, the fallback is the red marker at media/com_jem/images/marker-red.webp.
Shared venues: when several visible events use the same venue coordinates, Events Map groups them into one marker. JEM uses the highest icon priority available among those events. If several visible events provide different icons at the same priority level, the first matching event in the current map result determines the icon.
| Marker source | Displayed when | Important data |
|---|
| Type marker |
An applicable event, category or venue type has an icon. |
The icon and colour come from the highest-priority applicable type. |
| Global venue marker |
No applicable type has an icon. |
Uses the configured Venue marker file. |
| My location marker |
The visitor allows browser geolocation. |
Used only for visitor orientation; it does not alter event or venue data. |
| Heat layer |
Heat layer is enabled and enough markers exist. |
Shows event density rather than only individual points. |
Practical Marker Examples
| Configuration | Marker shown |
|---|
| The event type has an icon; its category and venue types also have icons. |
The event type icon. |
| The event type has no icon, but one of its category types has an icon. |
The category type icon. |
| Neither the event type nor category type has an icon, but the venue type does. |
The venue type icon. |
| No applicable type has an icon. |
The configured global venue marker. |
| Several events share a venue and at least one visible event has an event type icon. |
An event type icon, because it has higher priority than category and venue type icons. |
Menu Item Target
The JEM Itemid option can be used to control the target menu item for links generated from the map. This helps keep URLs, modules and breadcrumbs consistent when the visitor clicks from a map marker to an event or venue page.
| Setup | Result |
|---|
| No target Itemid selected |
Joomla and JEM resolve links using the available routing context. |
| Target Itemid selected |
Links from the map can point through a specific JEM menu context. |
Page Text
Events Map supports page intro and footer text. This is important because map-based pages often need a short explanation: what the map shows, how filters work, whether only geocoded venues are visible, and how users can submit missing venues.
| Text area | Position | Example use |
|---|
| Introtext |
Below the page heading and above the map. |
“This map shows upcoming events with confirmed venue coordinates.” |
| Footer text |
Below the map and list output. |
“Only venues with GPS coordinates are displayed. Submit corrections using the venue form.” |
Recommended Configurations
| Map type | Recommended options | Reason |
|---|
| Local city map |
Higher zoom, date filter enabled, category filter enabled and country filter disabled. |
The visitor is already in one geographic area. |
| National event map |
Medium zoom, country default set and date filter enabled. |
Keeps the first view focused on the country. |
| International event map |
Lower zoom, country filter enabled and category filter enabled. |
Visitors need tools to reduce a large marker set. |
| Festival map |
Specific date or week as default, category filter enabled and type icons assigned where useful. |
Type icons help distinguish event programmes in a dense map. |
| Venue discovery map |
All dates, heat layer enabled and my location enabled. |
Helps users explore where events usually happen. |
Troubleshooting
| Problem | Likely cause | Solution |
|---|
| An event does not appear on the map. |
The event has no venue, or the venue has no valid coordinates. |
Edit the venue and add latitude and longitude. |
| The expected type icon is not shown. |
The type has no icon, is unpublished, is inaccessible, or a higher-priority type icon applies. |
Check the event, category and venue type assignments, icon fields, publication states and access levels. |
| The configured venue marker is not shown. |
An applicable event, category or venue type has an icon. |
This is expected. The configured venue marker is only used as the fallback. |
| The map opens in the wrong area. |
Fallback centre or zoom is not appropriate, or auto-centre has no valid markers. |
Set map centre latitude, longitude and zoom for the site region. |
| Country filter shows too many countries. |
The site country list is not restricted. |
Use the JEM country settings to keep only relevant active countries. |
| Visitors cannot use “My location”. |
Browser permission denied or the site context does not allow geolocation. |
Ask the visitor to allow location access; HTTPS may be required by browsers. |
| Markers are too crowded. |
The map contains too many events for the current zoom or filter. |
Enable category, date or country filters, or adjust the default date range. |
Technical Notes
- Events Map groups matching events by venue or coordinates before rendering the marker.
- Type icon values are validated as CSS icon classes before they are inserted into the map marker.
- Type colours are validated before being used as marker background colours, and JEM calculates a contrasting icon colour for readability.
- The same priority is applied by both the OpenStreetMap/Leaflet and Google Maps renderers.
- Type and category access rules are respected when resolving the marker icon.
Related Project Notes
- #2289 introduces the configured marker fallback and type-icon priority for map markers.
- #2032 discusses frontend category selection in map-related functionality.
- #2035 covers venue filtering concepts in calendar and map-style views.
- #2151 discusses country availability management for selectors and filters.
- #2131 relates to generating a complete JEM frontend menu.
- #2154 standardises intro and footer text options across JEM views.
