BMG Interactive Map

A WordPress plugin for creating interactive image-based maps with clickable location markers and polygon area overlays. Use any image — a photo, floor plan, hand-drawn map, or game map — and place markers and areas that visitors can click to reveal popups with titles and descriptions.

Features

• Any image as a map — upload any image as the map background
• Clickable markers — place markers anywhere on the image; each opens a popup with a title and description
• Polygon areas — draw multi-vertex regions over the map; areas render as outlines, highlight on hover, show a sticky name tooltip, and open a popup on click
• Zoom & pan — scroll to zoom, drag to pan; configurable zoom limits globally and per map
• Location list — optional side panel or floating overlay listing all locations, with search/filter and collapse toggle
• Area list — same options as location list; when both lists share a position they stack in a combined panel; hovering a list item highlights the polygon on the map
• Toolbar — icon button bar centred over the map; toggles location list, area list, fill-window mode, and native fullscreen; auto-repositions to avoid floating list panels
• Tooltips — show location names on marker hover
• Starting view — set a custom starting zoom level and center point per embed; supports per-breakpoint values in Elementor
• Keyboard accessible — Tab to markers, Enter/Space to open popups
• Three display methods — shortcode, Gutenberg block, or Elementor widget
• Elementor responsive controls — map height and starting view are configurable per breakpoint (desktop / tablet / mobile)
• Elementor styling — full visual control over markers, popups, location list, area list, toolbar, and close button via Elementor style tabs
• Tilesets — optionally pre-slice the map image into 256×256 px tiles at multiple zoom levels; served as static files for faster rendering of large images
• Deep linking — append ?location=slug or ?area=slug to any map page URL to auto-pan and open the popup for that item on load
• Cascade operations — trashing or deleting a map automatically cascades to its locations and areas

Requirements

• WordPress 5.0+
• PHP 7.4+
• Elementor (optional — widget registers only when Elementor is active)

Installation

1. Upload the plugin folder to /wp-content/plugins/.
2. Activate the plugin through Plugins → Installed Plugins.
3. On activation the plugin downloads Leaflet 1.9.4 from the CDN and stores it locally. If the download fails, it falls back to the CDN at runtime.

Quick Start

1 — Create a Map

Go to Interactive Maps → Add New. Give the map a title and set a Featured Image (this becomes the map background). Optionally set per-map zoom limits in the Zoom Settings sidebar panel. Optionally generate a tileset in the Tileset sidebar panel (see Tilesets below). Publish.

2 — Add Locations

Go to Interactive Maps → Locations → Add New. Fill in the title and description, select the parent map, then click anywhere on the map preview to place the marker. Adjust the marker colour if needed. Publish. Repeat for as many locations as needed.

3 — Add Areas (optional)

Go to Interactive Maps → Areas → Add New. Fill in the title and description, select the parent map, then click vertices on the map preview to draw the polygon. Adjust stroke colour, fill colour, and fill opacity as needed. Publish.

4 — Display the Map

Use any of the three methods below.

Display Methods

Shortcode

[bmg_map id="42"]

Copy the map's post ID from the URL in the editor (post=42).

Full parameter reference:

Parameter	Default	Description
id	(required)	Map post ID
width	(fill column)	Width: 800, 800px, or 100%
height	(aspect ratio)	Height: 600 or 600px. Leave blank to derive from the image ratio.
list_position	none	Location list placement — see values below
list_title	Locations	Label shown in the location list header
area_list_position	none	Area list placement — same values as list_position
area_list_title	Areas	Label shown in the area list header
zoom_position	(global setting)	Zoom control corner: topleft topright bottomleft bottomright
show_tooltips	0	Show location name on marker hover: 0 or 1
start_zoom	(fit all)	Starting Leaflet zoom level (e.g. -1, 0, 2)
start_x	(fit all)	Starting center X as a percentage of the image width (0–100)
start_y	(fit all)	Starting center Y as a percentage of the image height (0–100)

start_zoom, start_x, and start_y must all be provided together or the starting view is ignored.

list_position / area_list_position values:

Value	Effect
none	No list
left / right	Side panel next to the map; collapses to a narrow icon strip
float-tl / float-tr / float-bl / float-br	Floating overlay in a corner; collapses to a single header bar

When both lists are set to the same position they stack vertically inside a combined panel. Each list becomes scrollable and shows a search field when it contains 5 or more items.

Examples:

[bmg_map id="42" width="100%" list_position="right" area_list_position="right"]
[bmg_map id="42" list_position="float-tl" area_list_position="float-br" zoom_position="bottomright"]
[bmg_map id="42" start_zoom="-1" start_x="30" start_y="60"]

Gutenberg Block

Search for Interactive Map in the block inserter. Select your map, then configure width, height, zoom position, tooltips, and list position in the sidebar Inspector Controls panel.

Elementor Widget

Drag the Interactive Map widget from the General category onto your page. All layout controls support desktop / tablet / mobile breakpoints via Elementor's responsive mode.

Content tab — Map Settings:

• Select Map, Width
• Map Height (responsive — set different heights per breakpoint)
• Zoom Control Position, Show Name on Hover
• Location List Position, List Title
• Area List Position, Area List Title
• Hide Toolbar (responsive — hide/show the toolbar per breakpoint)
• Starting Zoom, Starting Center X %, Starting Center Y % (all responsive)

Style tab:

• Toolbar — button background (normal / hover / active), icon colour
• Marker Tooltip — typography and colours
• Map — background colour
• Location List — panel, title bar, search field, item, hover, and active colours and typography
• Area List — same controls as Location List, scoped to the area list
• Popup — container background, border, border radius; title and body typography and colours; close button icon, colour, size, and shape

Deep Linking

Append a query parameter to any map page URL to automatically pan to a location or area and open its popup when the page loads.

Parameter	Value	Effect
?location=slug	WordPress post slug of the location	Centers the map on that marker and opens its popup
?area=slug	WordPress post slug of the area	Centers the map on that polygon's centroid and opens its popup

The slug is the URL-friendly name WordPress assigns to each post. You can see it in the Edit Location or Edit Area permalink field, or in the address bar when editing (post-name portion).

Examples:

https://example.com/my-map-page/?location=great-hall
https://example.com/my-map-page/?area=northern-district

If both parameters are present, ?location takes precedence. If the slug does not match any item on the map the page loads normally with no error.

Toolbar

Every map embed includes a small icon button bar positioned at the top-centre of the map image (automatically moved to a free corner when floating lists occupy the top edge). The toolbar contains:

Button	Icon	Action
Locations	List icon	Show / hide the location list entirely
Areas	Polygon icon	Show / hide the area list entirely
Fill Window	Window frame icon	Expand the map to fill the browser viewport (CSS only, no browser API)
Fullscreen	Expand-arrows icon	Enter native browser fullscreen (hides browser chrome)

An Exit fullscreen pill button appears at the bottom-centre of the map during either expanded mode. Press Escape or click the button to return to normal view.

Use the Elementor Hide Toolbar responsive switcher to suppress the toolbar on specific breakpoints.

Tilesets

For maps with large background images, the Tileset option pre-slices the image into 256×256 px tiles at multiple zoom levels. The browser loads only the tiles that are currently visible, rather than the full image, which significantly reduces initial load time and memory usage.

Generating a Tileset

1. Open the map in the admin editor.
2. In the Tileset sidebar panel, click Generate Tileset.
3. The plugin slices the image one zoom level at a time (with a progress bar). Generation runs in the browser via a series of AJAX requests — leave the page open until the status shows Ready.
4. Tiles are stored in wp-content/uploads/bmg-tiles/{map-id}/ as static JPEG files and served directly by the web server.

How Tiles Are Used

Once a tileset is ready the frontend map automatically switches from a single image overlay to a tiled layer. Zoom levels above the native image resolution are served by upscaling the highest-resolution tiles (no extra files are generated for zooming in past 1:1).

Staleness

When you replace the map's featured image the tileset is automatically marked stale and the map falls back to the full image overlay. A warning appears in the Tileset panel — click Regenerate Tileset to rebuild.

Deleting a Tileset

Click Delete Tileset in the panel. The tile files are removed from disk and the map reverts to image-overlay mode. Tile files are also removed automatically when the map post is permanently deleted.

Requirements for Tileset Generation

• PHP GD extension (standard on most hosts; used for image processing).
• The map's featured image must be a file hosted in the WordPress media library (not an external URL). Supported formats: JPEG, PNG, GIF, WebP.
• Sufficient upload_max_filesize / memory_limit on the server. For typical images (under 8000×8000 px) the default 256 MB PHP memory limit is sufficient.

Per-Map Zoom Limits

Each map can override the global zoom limits via the Zoom Settings sidebar panel on the map edit screen. Leave the fields blank to use the global defaults from Settings.

Settings

Go to Interactive Maps → Settings to configure global defaults.

Setting	Default	Description
Default Marker Colour	#e74c3c	Applied to new locations; overridable per location
Min Zoom	-3	How far out visitors can zoom (range: −5 to 0)
Max Zoom	3	How far in visitors can zoom (range: 1 to 5)
Zoom Control Position	topleft	Default corner for zoom buttons

Admin Reference

Interactive Maps — list and edit maps (bmg_map CPT).

Interactive Maps → Locations — list and edit location markers (bmg_location CPT).

Interactive Maps → Areas — list and edit polygon area overlays (bmg_area CPT).

Interactive Maps → Settings — global plugin configuration.

Interactive Maps → How to Use — built-in step-by-step guide and parameter reference.

Map Meta Fields

Field	Description
Featured Image	The image used as the map background
Min Zoom	Per-map override for how far out the user can zoom
Max Zoom	Per-map override for how far in the user can zoom
Tileset Status	ready when a valid tileset exists; generating during generation; blank when none
Tileset Zoom Min	Lowest zoom level the tileset was generated for
Tileset Image ID	Attachment ID of the image used to generate the tileset (used for staleness detection)
Tileset URL Base	Base URL of the tile directory, e.g. .../uploads/bmg-tiles/42/

Location Meta Fields

Field	Description
Parent Map	Which map this location belongs to
X / Y coordinates	Position as a percentage (0–100); set visually by clicking the map preview
Marker Color	Per-location hex colour (defaults to global setting)

Area Meta Fields

Field	Description
Parent Map	Which map this area belongs to
Points	JSON array of {x, y} percentage coordinates; set visually by clicking vertices on the map preview
Stroke Color	Outline colour of the polygon
Fill Color	Interior fill colour shown on hover
Fill Opacity	Opacity of the fill (0–1)

Data Storage

Item	Storage
Map	bmg_map CPT; background image = featured image; per-map zoom in _bmg_map_min_zoom / _bmg_map_max_zoom
Location	bmg_location CPT; _bmg_map_id, _bmg_loc_x, _bmg_loc_y, _bmg_loc_color
Area	bmg_area CPT; _bmg_area_map_id, _bmg_area_points (JSON), _bmg_area_color, _bmg_area_fill_color, _bmg_area_fill_opacity
Global settings	bmg_map_settings WordPress option (array)
Tileset files	wp-content/uploads/bmg-tiles/{map_id}/{z}/{x}/{y}.jpg
Leaflet library	wp-content/plugins/bmg-interactive-map/lib/leaflet/

Third-Party Libraries

• Leaflet 1.9.4 — MIT License. Downloaded on activation and served locally.

License

GPL-2.0-or-later. See https://www.gnu.org/licenses/gpl-2.0.html.