Events Map

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.

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/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/JEM access rules.

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 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	No	Allows a larger map experience where supported by the layout.
Heat layer	Yes	Highlights geographic concentration of events.
Venue marker file	media/com_jem/images/marker-red.webp	Marker image used for event venues.
My location marker file	media/com_jem/images/marker-blue.webp	Marker image used for the visitor’s own location.
Map height	500px	Controls the visible height of the map area.

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/filter range. The marker content depends on the Events Map template, but normally points users toward the event and venue detail pages.

Marker source	Displayed when	Important data
Venue marker	The venue has valid coordinates and at least one matching event.	Venue name, coordinates, event list and event links.
My location marker	The visitor allows browser geolocation.	Used only for visitor orientation; it does not alter event data.
Heat layer	Heat layer is enabled and enough markers exist.	Shows event density rather than only individual points.

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/JEM resolves 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/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, country filter disabled.	The visitor is already in one geographic area.
National event map	Medium zoom, country default set, date filter enabled.	Keeps the first view focused on the country.
International event map	Lower zoom, country filter enabled, category filter enabled.	Visitors need tools to reduce a large marker set.
Festival map	Specific date or week as default, category filter enabled, custom marker if desired.	Useful for dense event programmes over a short period.
Venue discovery map	All dates, heat layer enabled, 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 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 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/filter.	Enable category/date/country filters or adjust the default date range.

Related Project Notes

#2032 discusses frontend category selection in map-related functionality.
#2035 covers venue filtering concepts in calendar/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.