Documentation

Every WebProCMS site can drop a map onto any page through the Map design-library row (or the x-dl.map component inside other rows). A map needs nothing but an address — no API key, no setup. Maps come in three flavours: a lightweight embed (Google Maps or OpenStreetMap), an interactive, on-brand Styled map (the default), and a keyed Google Maps JavaScript map for sites that bring their own Google API key. Styled maps are a premium feature that's on by default for members and can be turned off (falling back to embeds) at any time.

Providers — Google Maps vs OpenStreetMap

The site-wide map provider is chosen in Dashboard → Settings → Business → Maps, with a live preview of each so you can see the difference before you pick:

• Google Maps — the familiar Google look. The "Get Directions" link opens Google Maps directions. Google sets cookies, so when the built-in Cookie Consent feature is enabled, a Google embed renders behind the consent banner until the visitor opts in.
• OpenStreetMap — the open-data map. The "Get Directions" link opens OpenStreetMap directions. OSM sets no cookies, so it renders immediately and never needs a consent banner.

Both providers produce a working "Get Directions" link — pick Google if you'd rather send visitors to Google Maps for directions, or OpenStreetMap if you want a cookie-free, consent-free embed.

Embed vs Styled vs Google Maps rendering

The Map rendering setting (same Settings → Maps card) chooses how maps draw:

• Embed — a lightweight provider iframe (Google or OSM). Zero JavaScript on the page beyond the iframe itself. Available on every plan.
• Styled — an interactive, themeable map rendered with Leaflet. Keyless (free map tiles), sets no cookies, and so needs no consent banner regardless of provider. This is the paid Styled Maps upgrade, and the default for new installs — seeded at install time, so sites that predate the styled default keep their original embed rendering until they opt in (falling back to an embed when the feature is off).
• Google Maps (requires API key) — true Google cartography rendered with the Google Maps JavaScript API, including multiple markers with fitted bounds and info popups. The site owner supplies their own key (Settings → Business → Maps → Google Maps API key): create it in the Google Cloud Console with the "Maps JavaScript API" enabled and restrict it to the site's domain. Google requires a billing account; typical small-site usage stays inside the free monthly tier. Without a saved key, google-mode maps fall back to a keyless embed. The Google script sets cookies, so with Cookie Consent enabled the map shows a consent prompt until the visitor opts in. (Marker clustering is currently a Styled-mode feature.)

The setting is a site-wide default; any individual map can override it in the page editor ("Map type": Site default / Embed / Styled / Google Maps).

Styled Maps (paid feature)

When the Styled Maps feature is enabled (Dashboard → Settings → Features), maps can switch from a plain embed to an interactive, branded map with these options — set site-wide for defaults, and per-map in the page editor:

• Basemap themes — Modern (the default style for new installs: today's Google Maps look — gray roads, blue water, broad vegetation greens, with the tiles' salmon-pink building fill muted to a warm tan), Light, Voyager, Hybrid (aerial imagery with the road network drawn over it), Explorer (National Geographic's warm parchment), Nightfall (a readable dark-navy theme), and Graphite (Nightfall's neutral charcoal twin). The site-wide default is picked from a visual thumbnail grid; each map can override it (or use "Site default"). Retired themes (Streets, Grayscale, Slate, Dark) are no longer offered but keep rendering on installs that saved them. Streets and Modern bake their labels into the tiles, so the hide-labels toggle applies to the other themes.
• Hide labels — drop place names on the themes whose labels ship as a separate overlay layer (Light, Grayscale, Slate, Dark, Nightfall) for a cleaner look; on Hybrid it drops the road/name overlay back to bare imagery. Streets, Modern, Voyager, Graphite and Explorer bake labels into the tile itself and can't honour it.
• Brand-color tint — tint the whole map toward your primary or secondary brand color, at Subtle / Medium / Strong strength, so the map matches the site.
• Custom markers — choose a marker style: a classic pin, a pin with an icon inside (any glyph from the icon library — home, storefront, star, coffee, etc.), or a minimal dot. Set the marker color (or let it follow the brand color) and an optional label.
• Info popup — when enabled, clicking the marker opens a small card with the label, address, and a "Get Directions" link. The popup's directions link is always present when the pin has a resolvable destination; it is not tied to the "Get Directions" toggle, which governs the standalone link rendered below a single-address map.
• Interaction controls — lock scroll-zoom (so the page doesn't hijack the wheel), hide the zoom buttons, or make the map fully static (non-interactive).
• Height presets — a quick Short / Medium / Tall height, or keep full control through the wrapper classes.
• Many locations on one map, with clustering — the map rows plot every published location as its own pin; markers that sit close together collapse into a numbered cluster that zooms in when clicked, and each pin's popup links to the location's page. Clustering can be toggled per map ("Cluster nearby markers"). Multi-pin maps need an interactive renderer: Styled draws every pin (Google-API mode does too); a multi-marker map that resolves to a classic embed degrades to a single regional embed anchored on the first location, zoomed out far enough to cover the full marker spread.

The Maps row category

Map rows live in their own Maps category in the page editor's add-row drawer — not under Contact — because they belong on a locations index just as readily as a contact page. Four designs ship:

The four all-locations designs need the paid Styled Maps feature (multi-pin rendering); Map Embed works on any install.

Lettered pins and pin ↔ list sync (locator rows). Both locator designs letter their pins A, B, C… and put the matching badge on each list entry, so a visitor can go from a pin to its address and back. Clicking a pin scrolls its entry into view inside the list panel and highlights it; clicking an entry's empty space opens that pin's popup (the entry's own links still navigate as normal, so keyboard and no-JS visitors are unaffected). Rows and pins are paired by the location's URL rather than by position, so the list and the map can't drift out of step if one side is filtered or limited differently. Letters run past Z as AA, AB… for very large location sets. The lettering is applied by the map script, so it appears only where the map itself does.

"Closest to me" (overlay locator). The overlay design's panel header carries a Closest to me button beside its title. Clicking it asks the browser for the visitor's position, ranks every pin by straight-line distance, then eases the map to the winner, opens its popup, and scrolls the list to its entry. Denials and failures report next to the button rather than doing nothing. The button is only rendered where geolocation can actually work — it needs a secure (https) page, so an http:// site shows no button instead of one that always fails. Its wording lives in the row template, so changing it means editing the row rather than the page.

A new install's locations index page is seeded as two rows — the Locations With Hours list layout with Locations Map stacked beneath it — so the map half can be swapped for either locator design without touching the list, and the list layout can be changed without losing the map. (The older merged "Locations With Hours & Map" single-row design was retired in favour of this split; installs that still carry it keep rendering it, and choosing any new list layout swaps it out cleanly.)

Placing the pin visually

Every map field group in the page editor includes a Pin location mini-map: drag the pin (or click the map) to set the exact coordinates, zoom to set the saved zoom level, and use Center on address to jump to the typed address. It writes the same Latitude / Longitude / Zoom values you could type by hand — no more copying coordinates out of another map tool. The picker works for OpenStreetMap embeds and styled maps alike (Google embeds locate themselves from the address).

Styled maps stay keyless: tiles come from Esri's free ArcGIS Online services with proper attribution, and the map sets no cookies — so a styled map never triggers a consent banner.

CARTO is no longer a tile source. The Light/Dark/Voyager family used to render from basemaps.cartocdn.com; in 2026 CARTO ended keyless access and began stamping "API KEY REQUIRED" diagonally across every tile it serves without a key. Nothing errors — the request still returns 200 with a real tile — so the only symptom is a defaced public map, and the watermark is unconditional (identical with and without a Referer). Every theme now sources from Esri instead. If a future theme needs a non-Esri tileset, verify a tile by eye before shipping it; a status code proves nothing here.

How the gating works

Styled Maps is a feature flag (Dashboard → Settings → Features), on by default for members:

• On (the default) — the "Styled" rendering option, the default-style picker, and all the per-map styling fields appear.
• Off — only the Embed providers (Google / OpenStreetMap) are offered. The editor shows just the plain map fields; the Settings card shows an upgrade hint. Any map that was set to Styled automatically falls back to a Google/OSM embed, so nothing breaks — and re-enabling the feature restores the styled look.

The flag keeps the free/paid line clean for distribution: an install that isn't entitled to the premium tier has the feature turned off and gracefully serves embeds.

Coordinates

Embedded Google maps geocode the address themselves. The OpenStreetMap embed and every Styled or Google-API map need latitude/longitude, which the CMS resolves once from the address (via OpenStreetMap's Nominatim) — warmed when you save the page or a content item with an address field, so the first visitor never waits on a lookup. A map can also be given explicit coordinates in its advanced fields.

Resolved coordinates are kept permanently, in the geocodes database table (the cache sits in front of it purely for speed). An address doesn't move, so nothing routine re-resolves it: clearing the caches, updating the CMS, or restoring a backup all leave the pins in place. Should the geocoder ever answer badly for an address — an ambiguous street matching the wrong town — php artisan geocode:forget "<address>" drops it and re-queues it for a fresh lookup (--all for every address).

Some addresses have no entry in the map data at all and can never be looked up. Every address field carries an optional manual pin for those — a latitude and longitude entered under Set the map pin manually — which outranks the lookup, applies to every map rendering that address, and is never swept by geocode:forget. See Locations.

Nominatim is a free community service with a strict ≤1 request/second policy, and a violation rate-limits the whole server's IP — so the CMS never bursts it. A public render spends at most two live lookups; any further cold addresses (e.g. a locations map with twenty pins on a fresh install) are queued for the geocode:warm background task, which resolves a small batch every few minutes at a polite pace and then clears the page cache so the pins appear. The first failed lookup (a 429 or outage) arms an install-wide backoff — all geocoding pauses for 15 minutes rather than hammering a service that's already saying no. Until an address resolves, its pin is simply absent (a single-address map shows its placeholder); everything self-heals with no admin action.

Where maps come from

• The standalone Map row lives in the design library's Contact category.
• Location, contact, and event detail pages include a map automatically.
• Any row can embed x-dl.map directly; on a data-driven detail page the address can be fed from the record (e.g. {item.data.address}).

Maps render on the cached, public HTML like everything else — the styled map's JavaScript (Leaflet) is loaded lazily and only on pages that actually contain a styled map, so map-free pages ship zero map code.