Documentation Dynamic OSM maps plugin

Documentation for the Dynamic OSM Maps plugin

How the block works

  • Add the Dynamic OSM maps block to a page or post.
  • Choose a location source: custom field coordinates, a custom field address, or a manual address stored in the block.
  • Without a license, use Single location with Manual address (free). Custom fields and Multiple locations require a Pro license.
  • Use Location mode: Single to show one location, Multiple to show up to three separate field sets or a repeater field with multiple rows on one map (Pro).
  • The block reads coordinates from custom fields (ACF, SCF, ACPT, Modern Fields, Meta Box, or plain post meta) or geocodes the address you type in the block through OpenStreetMap.
  • On the frontend, the map is rendered with Leaflet and OpenStreetMap tiles.
  • Leaflet and OpenStreetMap are automatically rendered and you don’t need a maps API key to use this plugin.
  • If a location cannot be resolved on the frontend, the block renders nothing. In the editor you see a helpful message instead.

Free versus Pro in short

  • Free: up to 5 map blocks site-wide, each with Single location mode and Manual address only.
  • Pro (license required): custom field coordinates, custom field address text, Multiple locations (field sets and repeaters), marker popups, tooltips, and all other advanced options.

Features Dynamic OSM Maps – Free version

  • No Google API required; it works completely with OpenStreetMaps and has unlimited free usage.
  • No settings, memberships for map-data required.
  • Show one marker on a map.
  • Two types of markers (classic and dot)
  • The dot marker is available in various colors.
  • Option to not render the maps in the editor to keep your pages superfast.
  • Super light block; rendering is done by Leaflet.
  • Use up to 5 map blocks site-wide, each with Single location mode and Manual address only.
  • You can update anytime by purchasing a license.

Features Dynamic OSM Maps – Pro version

  • No Google API required; it works completely with OpenStreetMaps and has unlimited free usage.
  • No settings, memberships for map-data required.
  • Two types of markers (classic and dot)
  • The dot marker is available in several colors.
  • Option to not render the maps in the editor to keep your pages superfast.
  • Super light block; rendering is done by Leaflet.
  • Show one or multiple markers on the map.
  • Works with simple ‘set details in the block’ values, with custom fields and yes, also with repeaters.
  • With simple custom fields (address in a text field) you can show up to 3 markers on a map.
  • When using a repeater, the nr of markers on a map is endless.
  • Popups (tooltip style) with location name, location extras info, location logo, and URL (https:// or tel:+)
  • Works with custom fields from ACF, SCF, ACPT, Meta Box, and Modern Fields.
  • Type of data accepted: custom field coordinates, custom field address text, multiple locations (field sets and repeaters).

Limitations

  • You can display locations from a query item (for example, in a flyout, popup, or on the post itself).
  • However, the plugin is not intended to display all locations of all posts in a query on a map.
  • The block can, however, show multiple locations in a repeater on a map.

Installation

  • Upload the ‘super-modal’ folder to /wp-content/plugins/.
  • Activate the plugin through the Plugins menu in WordPress.
  • Add the Dynamic OSM Maps block to a page.
  • Set a trigger selector in the block sidebar.
  • Add that class or ID to any element that should open the panel.

Usage

Single or Multiple locations

You can choose a Single address or Multiple addresses. Set Location mode to Multiple in the block sidebar. You can combine up to three separate custom fields, or read multiple rows from one repeater field.

Different options to provide location data for the map

When opening the block settings, select Single (if you just want to show one address / location) or Multiple (if you want to show more addresses / locations).

Single

Single offers the following sources:

  • Custom field (address text)
    • Select the custom field containing the address (as text).
  • Custom field (coordinates)
    • Select the correct type of coordinates field (Separate latitude and longitude fields or Combined lat/lng field).
    • Select the custom field(s) containing the coordinates.
  • Manual address
    • Type the address in the Address field.
    • You can correct the map and marker manually.

Multiple

Field sets (max 3) in block settings, select the source:
  • Address text field
    • Select the custom field containing the address (as text).
    • Optional: select location name and location URL fields.
  • Separate latitude and longitude fields
    • Select the Latitude meta key.
    • Select the Longitude meta key.
    • Optional: select location name and location URL fields.
    • Note: repeat this for every field set you need, max 3.
  • Combined lat/lng field
    • Select the Combined lat/lng field.
    • The fields Latitude key and Longitude key are only to be adjusted if using an alternative property.
    • Optional: select location name and location URL fields.
    • Note: repeat this for every field set you require, max 3.

Repeater field, select the source:

  • Address text field
    • Select the custom field containing the address (as text).
    • Optional: select location name, location URL, location image field, and location extra info fields.
  • Separate latitude and longitude fields
    • Select the custom field with the Latitude meta.
    • Select the custom field with the Longitude meta.
    • Optional: select location name, location URL, location image field, and location extra info fields.
  • Combined lat/lng field
    • Select the Combined lat/lng field.
    • Optional: select location name, location URL, location image field, and location extra info fields.

Map address source field is empty

  • When using a custom field as the source, every map with an empty field is automatically hidden on the front-end.
  • This is especially important if a map is placed in a template or element and the user or editor enters the address in a custom field. If the user leaves the field empty, the map will not be displayed on the frontend (not even in the source HTML).

Notes

  • Most custom field providers offer the combined lat/lng field.
  • If you need to show more than 3 locations, use the repeater option.
  • Rows without valid coordinates or addresses are skipped silently.
  • With two or more valid locations, the map automatically zooms to fit all markers.
  • Optional location name and URL fields show a tooltip on hover and a small popup on click or tap. Repeater mode also supports an optional location image (logo) in the popup and extra info text in both the tooltip and popup.

General information – how to capture locations

  1. Type the address manually in the block settings and adjust if needed with the arrows and marker. This is perfect for dynamic use-cases.
    • Example: Rozengracht 1, Amsterdam, Netherlands. You can also just use town and country only.
    • When the address is not found, it can’t be converted to coordinates. Check the address here: https://www.openstreetmap.org. Adjust the address until it’s found, and use that address in the map-block.
  2. Custom address field with Latitude and Longitude values automatically calculated by an address block. For example ACPT provides that. ACF Pro as well, but you require a Google key.
    • Example: “lat”: 52.123,”lng”: 5.456
  3. Custom text field with Latitude and Longitude values manually added. Helpful tools are: Latlong and gps-coordinates
    • Example: “lat”: 52.123,”lng”: 5.456
  4. Custom text field with the address manually added. Values are comma separated.
    • Example: Rozengracht 1, Amsterdam, Netherlands. It frequently happens that a place name appears multiple times in a country. In that case, add the province or region.
    • The address then becomes: Rozengracht 1,Amsterdam,Noord-Holland,Nederland.
    • When the address is not found, it can’t be converted to coordinates. Check the address here: https://www.openstreetmap.org. Adjust the address until it’s found, and use that address in the map-block.
    • Note: If the website is, for example, a directory of therapists, doctors, or similar, where participants manage their own profiles, this is the best option, because they often lack the knowledge or experience to enter their location in any other way.
  • Location name: shown on hover and in the marker popup.
  • Location URL: shown as a clickable link in the marker popup only.
  • For a phone number, store a tel: link in the URL field, including the country code. Example: tel:+311234567890
  • Location extra info (repeater only): optional title, description, or other short text shown under the location name in the popup and also in the hover tooltip.
  • Location image (repeater only): optional logo or image shown above the location name in the popup only. ACPT image fields are supported whether they store an attachment ID or an image object with src/url.

Multiple locations and query loops

  • The plugin can show multiple addresses on one map using up to three field sets or one repeater field.
  • It is not suitable for collecting all addresses from a query loop and showing them together on a single map.
  • You can place the Dynamic OSM maps block inside a query loop to render one individual map per query item instead.
  • Multiple mode with a repeater offers the most options, such as extra info, a title, and an image field for a logo.

Manual address fine-tuning

  • When the source is Manual address, the editor preview lets you zoom in with the +/- buttons on the map or the Zoom control in the block sidebar (Map size). You can also move the map with the arrow buttons above the map and click to place the marker.
  • Adjusted coordinates are saved in the block and override the geocoded result from the address text.
  • Changing the address clears a previous manual marker adjustment so the address is geocoded again.
  • When the address is not found, check and adjust the address here: https://www.openstreetmap.org.

Caching

  • Geocoded addresses are cached in WordPress transients for one week to reduce repeated requests to Nominatim.
  • Failed geocode attempts are cached briefly so repeated invalid lookups do not overload the geocoder.
  • The editor preview loads map tiles directly in the browser. The frontend loads tiles through the visitor’s browser as well.
  • If a static image fallback is ever used server-side, individual OpenStreetMap tiles may also be cached in transients for one week.

Choice help

Address field with address as text

  • If you use a custom field plugin that requires a paid key or does not work well.
  • If you let users manage their profile with an address on the front-end themselves.

Address field with coordinates

  • If you use a custom field plugin that does not require a paid key.
  • If you have a location picker field that works really well.
  • If that level of precision matters to you (for example whether the marker is in a building or on the sidewalk).
  • If you choose not to let users manage their profile with an address on the front-end themselves.

Multiple locations with field sets

  • If you do not need to show more than 3 locations.
  • If you do not have a custom field plugin with a repeater field (that is usually a pro feature).
  • You do not need a custom field plugin; our Dynamic OSM maps plugin provides the 3 field sets.

Multiple locations with repeaters

  • If you want to show more than 3 locations now or later.
  • If you have a custom field plugin with a repeater field.
  • If you would like to use the option with the most extra fields (also shows extra info under the name field).

Settings page

On the Settings page you can configure several things:

  • Render maps in the block editor or not (default: on).
  • Marker type and color.
  • Popup logo height (default: 30px).

Creating a simple map

Step 1: Install Dynamic OSM Maps

  • Install Dynamic OSM Maps
  • Use the free version or enter the license key and save.

Step 2: Create the map

Placement of the map block
  • Place the Dynamic OSM Maps block on a page.
  • The location is the place where the map is shown frontend.
Block settings
  • Location mode: Single
  • Source: Manual address
  • Address: type the address you wish to show on the map.
    • Street and nr, place, country.
    • If a place name occurs multiple times in a country, include the region or province: Street and nr, place, region or province, country.
Map size
  • Height: Set a height. The default is 400px.
  • Width: Usually this is set at 100%
Zoom
  • Usually a zoom between 10 and 14 is good.
  • The zoom factor you used to set the marker does not affect the final frontend view.
Save the page
  • Don’t forget to save the page.

Step 3 (optional): change the marker or color of the marker

  • Go to the settings page.
  • Go to the settings tab.
  • Select a marker type and color.
  • Save

CSS for Dynamic OSM Maps

  • Ready-to-use CSS snippets to customize the appearance of the maps front-end.

Placement of the CSS

Your theme or builder provides an ‘Additional CSS’ field

  • The CSS in an ‘Additional CSS’ field of the block, automatically only targets that block, in this case the map.
  • Placing the CSS in a CSS snippet, or in the themes CSS page, targets all maps on your website.

Use the ‘CSS for this map’ in the Map Styling tab

  • The CSS in an ‘CSS’ for this map’ field, automatically only targets that block, in this case the map.

Target specific maps – per class

  • Target specific maps – per class.
    • Add a custom-class after the class you what to want change.
    • Example: .osm-location-map .leaflet-tile-pane img becomes: .osm-location-map.map-grayscale .leaflet-tile-pane img
    • Add the class map-grayscale to the ‘Additional CSS class(es)’ field
    • That way you only target the maps with the custom class map-grayscale
  • Target maps on a specific page:
    • osm-location-map .leaflet-tile-pane img becomes: .page-id-42 .osm-location-map .leaflet-tile-pane img
  • Placing the CSS in a CSS snippet, or in the themes CSS page, targets all maps on your website.

The CSS snippets

1. Black & white 

.osm-location-map .leaflet-tile-pane img {

filter: grayscale(100%);

}

Equivalent on the tile layer:

.osm-location-map .leaflet-tile-pane {

filter: grayscale(100%);

}

2. Color overlay (tint)

The map wrapper is .osm-location-map. Make it a positioning context and add an overlay:

.osm-location-map {

position: relative;

}

.osm-location-map::after {

content: "";

position: absolute;

inset: 0;

background: rgba(0, 80, 160, 0.35); /* blue tint */

pointer-events: none;

z-index: 400; /* above tiles, below markers/popups */

}

3. Grayscale + tint (common combo)

.osm-location-map .leaflet-tile-pane img {

filter: grayscale(100%) brightness(0.9);

}

.osm-location-map {

position: relative;

}

.osm-location-map::after {

content: "";

position: absolute;

inset: 0;

background: rgba(255, 200, 100, 0.25); /* warm tint */

pointer-events: none;

z-index: 400;

}

4. High Contrast

/* High-contrast B&W */

.osm-location-map .leaflet-tile-pane img {

filter: grayscale(100%) contrast(1.3);

}

5. Sepia / Vintage

/* Sepia / vintage */

.osm-location-map .leaflet-tile-pane img {

filter: sepia(60%) saturate(0.8);

}

6. Dark / inverted-ish

/* Dark / inverted-ish */

.osm-location-map .leaflet-tile-pane img {

filter: invert(1) hue-rotate(180deg);

}

7. Only tiles styled — markers stay normal

Filters on .leaflet-tile-pane (or its imgs) affect tiles only. Markers, tooltips, and popups are in separate Leaflet panes, so they keep their normal colors.

The ::after overlay sits on top of tiles but under markers if z-index: 400 is used (Leaflet markers are typically higher).
Back to Dynamic OSM Maps