OSM Multi Pin Shortcode: la soluzione WordPress per mappe OpenStreetMap con più pin e clusterosm map

[osm_map height=”460px” markers=”41.9028,12.4964|45.4642,9.1900|40.8518,14.2681″ titles=”Roma|Milano|Napoli” cluster=”1″]

Vuoi inserire mappe OpenStreetMap in WordPress con più pin, clustering numerico, popup HTML e asset locali (no CDN)? OSM Multi Pin Shortcode è un plugin leggero basato su Leaflet e MarkerCluster, pensato per performance, compatibilità e conformità alle regole della WordPress.org Plugin Directory. Indice

Perché scegliere OSM Multi Pin Shortcode

Multi-pin e cluster numerici: gestisci centinaia di marker con raggruppamenti chiari quando l’utente è zoom-out.
Popup HTML sanificati: formattazione ricca in sicurezza (wp_kses_post).
Asset locali: niente CDN esterni negli enqueue → review-friendly per WordPress.org e meno dipendenze di rete.
Compatibilità: funziona con editor a blocchi; in admin non carica script inutili per evitare conflitti di salvataggio.
API semplice: un unico shortcode con attributi chiari; supporto a markers_json per integrare dati da codice o ACF.

Installazione e requisiti

Carica la cartella del plugin in /wp-content/plugins/ e attivalo da Plugin → Installati.
Nel plugin sono previsti gli asset locali: Leaflet 1.9.4 e MarkerCluster 1.5.3. Assicurati che i file siano presenti in assets/leaflet/ e assets/cluster/ (con la cartella images di Leaflet).
Verifica che il tema includa <?php wp_head(); ?> e <?php wp_footer(); ?>.

Suggerimento: se usi tab/accordion, la mappa fa già invalidateSize() all’init, ma dai comunque un’altezza esplicita al contenitore.

Shortcode e attributi

Shortcode base: [osm_map ...]

Attributo	Tipo / Default	Descrizione
`width`	string, 100%	Larghezza contenitore (es. `100%`, `800px`).
`height`	string, 400px	Altezza mappa: deve essere esplicita.
`zoom`	int, 12	Livello di zoom iniziale (se è impostato anche `center`).
`center`	string, vuoto	Centro mappa `lat,lng`. Se omesso, fit automatico sui marker.
`tiles`	string, https://tile.openstreetmap.org/{z}/{x}/{y}.png	Template del provider. Evita di sanificarlo con funzioni che rompono le `{graffe}`.
`attrib`	string, © OpenStreetMap contributors	Attribution mostrata sulla mappa.
`cluster`	1 \| 0	Abilita raggruppamento marker (numeri).
`cluster_disable_at_zoom`	int, 12	Livello di zoom a cui i cluster si sciolgono (i numeri lasciano posto ai singoli pin).
`icon_url`	string, vuoto	URL di un’icona personalizzata (altrimenti pin di default di Leaflet).
`icon_size`	string, 32,32	Dimensione icona personalizzata.
`icon_anchor`	string, 16,32	Punto di ancoraggio sull’icona (x,y).
`popup_anchor`	string, 0,-28	Offset dell’ancoraggio popup.
`markers`	string, vuoto	Lista pipe-separata `lat,lng\|lat,lng\|...`.
`titles`	string, vuoto	Titoli (tooltip) pipe-separati per i marker.
`popups`	string, vuoto	Popup HTML (sanificati) pipe-separati.
`markers_json`	JSON, vuoto	Array di oggetti `{lat,lng,title,popup}`. Consigliato per integrazioni programmatiche.

Esempi pronti

1) Mappa base con tre città e cluster

[osm_map height="460px"
         markers="41.9028,12.4964|45.4642,9.1900|40.8518,14.2681"
         titles="Roma|Milano|Napoli"
         popups="<b>Roma</b>|<b>Milano</b>|<b>Napoli</b>"
         cluster="1"
         cluster_disable_at_zoom="12"]

2) Versione JSON (più comoda da generare a codice)

[osm_map height="500px" markers_json='[
  {"lat":41.9028,"lng":12.4964,"title":"Roma","popup":"<b>Roma</b>"},
  {"lat":45.4642,"lng":9.1900,"title":"Milano","popup":"<b>Milano</b>"},
  {"lat":40.8518,"lng":14.2681,"title":"Napoli","popup":"<b>Napoli</b>"}
]' cluster="1"]

3) Centro e zoom fissi

[osm_map height="420px" center="41.9028,12.4964" zoom="10"
         markers="41.9028,12.4964|42.0,12.6" titles="Centro|Punto 2" cluster="0"]

4) Pin personalizzato (via URL)

[osm_map height="420px"
         markers="41.9,12.49|45.46,9.19"
         titles="Roma|Milano"
         icon_url="https://tuo-sito.it/path/pin.png"
         icon_size="32,32" icon_anchor="16,32" popup_anchor="0,-28"]

5) Cambiare provider delle tessere (tiles)

[osm_map height="460px"
         tiles="https://tile.openstreetmap.org/{z}/{x}/{y}.png"
         markers="40.85,14.26" titles="Napoli"]

Attenzione: il template dei tiles deve mantenere le {graffe} ({z}, {x}, {y}).

Best practice performance e SEO

Asset locali: caricando Leaflet/MarkerCluster dal plugin eviti latency esterne e sei conforme alle policy della directory.
Height esplicita: imposta sempre height nello shortcode o via CSS, altrimenti la mappa potrebbe apparire “grigia”.
Cluster: usa cluster=1 e cluster_disable_at_zoom per mantenere l’interfaccia pulita in zoom-out.
Popup leggeri: evita HTML pesante o script inline nei popup; restano sanificati, ma è meglio tenerli snelli.
Tiles: il server OSM pubblico è perfetto per demo e siti piccoli; per carichi elevati valuta un provider dedicato/caching.

Troubleshooting

Mappa grigia (pin visibili ma sfondo assente)
Quasi sempre l’URL dei tiles è stato “rotto” (le {graffe} sono state encodate). Usa il default del plugin o passa un template con {z}/{x}/{y} intatte.

“Aggiornamento fallito. La risposta non è una risposta JSON valida.”
Evita qualunque output HTML in admin o durante richieste REST/AJAX. Il plugin carica gli script solo nel front-end e mostra eventuali notice solo nella schermata Plugin.

Non vedo il pin di default
Assicurati che in assets/leaflet/ ci sia la cartella images con marker-icon.png, marker-icon-2x.png, marker-shadow.png.

Consiglio
Se usi tab/accordion, la mappa viene inizializzata con invalidateSize() per forzare il ricalcolo quando diventa visibile.

Conformità WordPress.org e licenze

Nessun CDN negli enqueue: gli asset sono serviti dal plugin → niente “OffloadedContent”.
Licenze: includi i file LICENSE di Leaflet (BSD-2-Clause) e MarkerCluster (MIT) dentro la cartella assets.
Sicurezza: popup sanificati con wp_kses_post, nessuna telemetria.

Roadmap, changelog e supporto

Roadmap

Blocco Gutenberg “OSM Map” con UI per aggiungere marker.
Supporto GeoJSON e import CSV.
Temi di marker predefiniti.

Changelog (estratto)

1.3.x – Asset locali, handle univoci, cluster configurabile, fix admin/REST.
1.2.x – Traduzioni e controlli in editor per evitare JSON non valido.
1.0.x – Prima release con multi-pin, cluster e popup.

Hai bisogno di aiuto o vuoi proporre una funzione? Lascia un commento o contattaci: felici di migliorare il plugin insieme.

Scarica e inizia

Pronto a inserire la tua prima mappa OSM su WordPress? Installa il plugin, crea la pagina e incolla lo shortcode di esempio:

[osm_map height="460px"
         markers="41.9028,12.4964|45.4642,9.1900|40.8518,14.2681"
         titles="Roma|Milano|Napoli"
         cluster="1"
         cluster_disable_at_zoom="12"]

In meno di un minuto hai una mappa pulita, veloce e con pin raggruppati quando serve. 🚀