Zum Inhalt

Karten

Voraussetzung

Entweder Modul Google Maps oder OpenStreetMap muss unter Theme → Module aktiv sein. Beide setzen Integrations voraus. Standardmäßig sind beide aus.

Wozu

Eine Karte mit Markern im Inhalt ausgeben. Zwei Module stehen zur Wahl, die sich gegenseitig ausschließen — sie gehören derselben exklusiven Gruppe an, weil beide den Shortcode [map] beanspruchen.

Modul Vorteil Nachteil
OpenStreetMap Kein API-Schlüssel nötig, Leaflet liegt lokal im Modul, keine Verbindung zu einem Konzern weniger Kartendetails als Google
Google Maps vertraute Darstellung, Geocoding und Vorschau im Backend API-Schlüssel und Abrechnung nötig, Verbindung zu Google

Für die meisten Projekte ist OpenStreetMap die einfachere Wahl: kein Schlüssel, keine Kosten, weniger datenschutzrechtliche Fragen.

Diese Entscheidung fällt einmal am Anfang. Ein Wechsel später bedeutet, die Attribute in bestehenden Inhalten zu prüfen — sie unterscheiden sich.

Einstellungen

Unter Theme → Einstellungen → Integration. Der Abschnitt trägt den Namen des aktiven Moduls; sind beide Kartenmodule aus, bleibt der Reiter leer.

Google Maps

Der Abschnitt Google Maps im Reiter Integration

Feld Wofür
API-Key Pflicht. Ohne Key bleibt die Karte leer und der Shortcode gibt nichts aus
Map ID cloud-basierter Kartenstil, Voraussetzung für Advanced Markers
Zoom Obergrenze für den automatischen Zoom auf alle Marker
Symbol HTML für den Marker, etwa ein Inline-SVG
Icon Color Farbe des Standardmarkers
Polygon Color Füllfarbe für Flächen aus geojson
Polygon Border Size Randstärke dieser Flächen in Pixel
Polygon Border Color Randfarbe dieser Flächen
Placeholder image liegt unter der Karte, solange sie nicht geladen ist

Das Zoom-Feld ist eine Obergrenze, keine feste Stufe: Die Karte rahmt zunächst alle Marker ein und zoomt nicht näher heran als dieser Wert. Ein zoom-Attribut am Shortcode hat Vorrang.

OpenStreetMap

Der Abschnitt OpenStreetMap im Reiter Integration

Drei Felder — Leaflet braucht keinen Schlüssel:

Feld Wofür
Zoom leer lassen, damit die Karte auf alle Marker zoomt
Tile-Server leer bedeutet den öffentlichen Server von OpenStreetMap
Placeholder image liegt unter der Karte, solange sie nicht geladen ist

Tile-Server im Produktivbetrieb

Bleibt das Feld leer, nutzt die Karte https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png. Dieser Server ist für Entwicklung und kleine Websites gedacht und hat eine Nutzungsrichtlinie. Bei hohem Aufkommen gehört hier ein eigener oder gebuchter Server hinein.

Ein eigener Eintrag braucht dieselben Platzhalter, die Leaflet einsetzt: {z}, {x} und {y} für die Kachel, {s} für die Subdomain. Eine URL ohne diese Platzhalter liefert keine Karte.

Ein Feld für das Marker-Symbol gibt es hier nicht: OpenStreetMap verwendet den Standardmarker von Leaflet, der als Bild im Modul liegt.

Verwenden

Als Shortcode. [map] liefert das aktive Modul; [gmap] und [osm] sind eindeutig:

[map coords="52.520008,13.404954" title="Standort Berlin" zoom="14"]
[osm coords="52.52,13.40|48.13,11.58" title="Berlin|München"]

Mehrere Marker werden mit | getrennt. OpenStreetMap kennt zusätzlich address, eine Auswahlliste über dropdown und eigene Geometrien über geojson; Google Maps dafür ein eigenes icon je Aufruf.

coords ist bei beiden Pflicht

Fehlt das Attribut, gibt der Shortcode eine leere Zeichenkette zurück — ohne Fehlermeldung. Das gilt auch dann, wenn bei OpenStreetMap address gesetzt ist: Die Adresse beschriftet den Marker, sie ersetzt seine Koordinaten nicht.

Alle Attribute unter Shortcodes.

Einwilligung

Beide Module laden ihre Ressourcen erst nach Klick oder nach Einwilligung. Bis dahin steht das Platzhalterbild.

Das ist bei Google Maps der wichtige Punkt: Ein direkt eingebundener Kartenrahmen nimmt beim Seitenaufruf Verbindung zu Google auf. Der Blocker verhindert das.

Siehe Einwilligung.

Entwicklertipps

Funktion Modul
twtheme_osm_render($map_data, $args = []) openstreetmap
twtheme_gmaps_render($map_data, $args = []) google-maps

Beide Module bieten zusätzlich twtheme_map() an — aber erst bei after_setup_theme mit Priorität 99, und nur wenn der Name noch frei ist. Ein Projekt kann ihn also selbst belegen. Für eindeutige Aufrufe sind die beiden Funktionen oben die bessere Wahl.

Filter Zweck
twtheme_osm_blocker_name Name des Consent-Blockers bei OSM
twtheme_gmaps_blocker_name Name des Consent-Blockers bei Google
twtheme_field_data_integration Karten-Assets für ein Feld nachladen

Weiter