Map Blocks releasesself-updates

Gutenberg blocks for displaying maps using Advanced Custom Fields and Leaflet.

Requirements

• WordPress 6.0+
• PHP 7.4+
• Advanced Custom Fields (Pro or Free), 6.0+
• Mapbox API token (free at mapbox.com)
• Google Maps JavaScript API key (free tier at Google Cloud Console)

Blocks Included

• Post Map — display a map with a single pin for an individual post
• Category Map — show all posts in a category on a clustered map (renders on category archive pages; auto-focuses on the densest cluster of pins)
• Archive Map — show every post that has a location on a single clustered map

Setup

All three blocks render their pins from a single ACF field, so the bulk of setup is wiring up ACF correctly. The blocks read a specific field name (map) — it must match exactly, or the blocks render nothing.

1. Prerequisites: two API keys

The Mapbox token is configured in the WordPress admin; an admin notice will remind you if it is missing.

The Google Maps API key is an ACF requirement, not a Map Blocks one — without it the Google Map field in the editor shows a blank box and you can't place pins. Add it with a snippet in your theme's functions.php or a code-snippets plugin:

add_action('acf/init', function () {
    acf_update_setting('google_api_key', 'YOUR_GOOGLE_MAPS_API_KEY');
});

Your Google Maps API key needs the Maps JavaScript API and Geocoding API enabled in the Google Cloud Console.

2. Required ACF fields

Create these fields (field group setup is walked through below, or import the ready-made groups — see Quick start with the ACF import):

All three blocks read the same per-post map field, so there is just one field to set up. Category Map and Archive Map have no configuration of their own: Category Map only displays on a category archive page and automatically focuses the opening view on the densest cluster of its posts' pins (a single far-flung post won't zoom the whole map out), while Archive Map fits the view to all pins. Earlier versions required category-level map/zoom_level fields — these are no longer used.

3. Step-by-step walkthrough

1. Install and activate Advanced Custom Fields (free or Pro) and Map Blocks.
2. Go to Settings → General, paste your Mapbox Access Token, and save.
3. Add the Google Maps API key snippet (see Prerequisites).
4. Create the post field group (e.g. "Post Location") — this one group powers all three blocks:
   • Add a field, type Google Map, field name map.
   • Set Location rule: Post Type is equal to Post.
   • Publish.
   • Category Map and Archive Map need no extra fields or configuration — they read this same per-post map field.
5. Geocode your content — Edit a post, find the Map field, search an address to drop a pin, and update.
6. Add a block — In the editor, insert a block and search "map". Choose Post Map (single post), Category Map (on a category archive), or Archive Map (anywhere you want all locations).

Nothing showing up? Confirm the field name is exactly map, that posts actually have a pin saved, and that both API keys are set. The Category Map only renders on a category archive URL.

Quick start with the ACF import

To skip manual field creation, import the bundled field groups:

1. Go to ACF → Tools → Import Field Groups.
2. Upload acf-export.json from this repo.
3. Click Import File.

This creates the "Post Location" group (post map field) the blocks expect. You still need to set both API keys (walkthrough steps 2–3 above).

Installation

See readme.txt for end-user installation instructions.

License

GPL-2.0-or-later