maps2 für TYPO3

Warum maps2 zu den Standardlösungen für Karten in TYPO3 gehört

Jede zweite Unternehmenswebsite braucht eine Kartenanzeige - für Standorte, Filialen, Veranstaltungsorte oder Liefergebiete. In TYPO3 hat sich maps2 als eine der meistgenutzten Karten-Extensions etabliert, weil sie zwei Map-Provider gleichzeitig unterstützt: Google Maps und OpenStreetMap. Das bedeutet für Unternehmen echte Wahlfreiheit. Wer Google Maps aus Datenschutzgründen vermeiden will, wechselt auf OpenStreetMap, ohne die Extension austauschen zu müssen.

maps2 geht dabei weit über eine einfache Karteneinbettung hinaus. Die Extension erzeugt Marker direkt aus TYPO3-Datensätzen, unterstützt bei Google Maps Clustering für große Markermengen und zeichnet Routen, Flächen und Radien. Für Redakteure ist das Anlegen neuer Standorte so einfach wie das Erstellen eines normalen TYPO3-Content-Elements.

Typische Einsatzszenarien

Filialfinder für Unternehmen mit 10 bis 500 Standorten. Ein Einzelhandelsunternehmen will auf seiner Website einen interaktiven Filialfinder anbieten. Jede Filiale ist als tt_address-Datensatz oder eigener Record in TYPO3 gespeichert. maps2 liest die Adressen, geocodiert sie (über den Geocoding-Dienst von Google oder OpenStreetMap, den maps2 mitbringt) und zeigt sie als Marker auf der Karte. Bei einem Klick auf den Marker öffnet sich ein Popup mit Adresse, Öffnungszeiten und Kontaktdaten. Für viele Marker lässt sich bei Google Maps das Clustering einschalten, damit die Karte übersichtlich bleibt.

Immobilien-Websites mit Objektkarten. Makler-Websites auf TYPO3-Basis nutzen maps2 zusammen mit der OpenImmo-Extension. Jedes importierte Immobilienobjekt wird automatisch auf der Karte angezeigt. Nutzer können nach Region filtern und zwischen Karten- und Listenansicht wechseln.

Event- und Veranstaltungsseiten. Kultureinrichtungen, Messen oder Kommunen zeigen Veranstaltungsorte auf einer Karte. maps2 lässt sich mit jeder Extbase-Extension verknüpfen, die Adressdaten enthält - ob cal, tt_address oder eigene Extensions.

Technische Architektur

maps2 ist als Extbase-Extension aufgebaut und nutzt das TYPO3 Plugin-System für die Frontend-Ausgabe. Die zentrale Architekturentscheidung ist die Provider-Abstraktion: Die Extension definiert ein einheitliches Interface für Map-Rendering, das von zwei Providern implementiert wird.

• Google Maps Provider: Nutzt die Google Maps JavaScript API v3. Erfordert einen API-Key mit aktiviertem Maps JavaScript API und Geocoding API. Kosten: ca. 7 USD pro 1.000 Kartenaufrufe nach dem kostenlosen Kontingent (10.000/Monat).
• OpenStreetMap Provider: Nutzt Leaflet.js als Rendering-Library mit OSM-Tiles. Keine API-Kosten, keine Registrierung nötig. Einschränkung: Die OSM-Tile-Server haben ein Fair-Use-Limit. Für Websites mit mehr als 50.000 Seitenaufrufen pro Monat empfiehlt sich ein eigener Tile-Server oder ein kommerzieller Anbieter wie MapTiler.
• Kachel-Server: Die Adresse der Kartenkacheln ist frei einstellbar, statt der OSM-Server lässt sich ein eigener Server oder ein kommerzieller Anbieter eintragen.

Die Extension speichert Orte, Routen, Flächen und Radien in einer eigenen Datenbanktabelle, Zoom und Kartengröße in den Plugin-Einstellungen. Marker werden über eine Relation zu beliebigen TYPO3-Records erzeugt - maps2 ist nicht auf einen bestimmten Record-Typ festgelegt. Über ein TCA-Override können Entwickler jede Tabelle mit Kartendaten verknüpfen.

Abhängigkeiten: TYPO3 Core (v11+), das Geocoding von Adressen bringt maps2 selbst mit. Für die Frontend-Darstellung benötigt maps2 die JavaScript-API des gewählten Providers. Bei Google Maps wird die API über einen externen Script-Tag geladen; bei OpenStreetMap wird Leaflet.js lokal als Dependency mitgeliefert.

Häufige Probleme und Lösungen

Problem: Karte wird nicht angezeigt, nur grauer Bereich. Bei Google Maps ist in 90% der Fälle der API-Key das Problem. Entweder fehlt er, die Abrechnung ist nicht aktiviert (Google verlangt seit 2018 eine hinterlegte Kreditkarte), oder die erlaubten Domains im API-Key stimmen nicht mit der Website überein. Die Lösung: In der Google Cloud Console prüfen, ob Maps JavaScript API aktiviert ist und der Key für die richtige Domain freigeschaltet wurde.

Problem: Marker erscheinen an falscher Position. Ursache ist häufig ein fehlerhaftes oder fehlendes Geocoding. Wenn Adressen keine Koordinaten haben, versucht maps2 sie über den konfigurierten Geocoding-Service aufzulösen. Bei ungenauen Adressen (z.B. nur Postleitzahl ohne Straße) landen Marker in der Stadtmitte statt am tatsächlichen Standort. Die Lösung: Koordinaten einmalig über einen Batch-Geocoding-Lauf korrigieren und im Datensatz als feste Werte speichern.

Problem: Performance-Probleme bei mehr als 200 Markern. Die JavaScript-Bibliothek rendert jeden Marker einzeln ins DOM. Ab 200 Markern wird das auf mobilen Geräten spürbar langsam. Die Lösung: Marker-Clustering aktivieren und bei Bedarf serverseitiges Filtering implementieren, sodass nur Marker im aktuellen Kartenausschnitt geladen werden.

Migration und Versions-Kompatibilität

maps2 wird aktiv von Stefan Froemken gepflegt und hat für jede LTS-Version eine eigene Reihe: 10.x für v11, 11.x für v12, 12.x für v13 und 13.x für v14. Major-Versionen bringen allerdings Umbauten mit, etwa die Umstellung der Plugins auf Inhaltselemente in 12.0.0; die Doku beschreibt jeden Schritt samt Upgrade Wizard.

Wer von einer älteren Karten-Extension migriert (z.B. wec_map), muss die Datenbankstruktur anpassen. maps2 nutzt eigene Tabellen für die Kartenkonfiguration, die nicht kompatibel mit älteren Extensions sind. Eine Migration umfasst typischerweise: Koordinaten-Export aus der alten Extension, Neuanlage der maps2-Records, Verknüpfung mit bestehenden TYPO3-Datensätzen.

Beim Wechsel von Google Maps auf OpenStreetMap (häufig aus DSGVO-Gründen) muss nur die Provider-Konfiguration in maps2 geändert werden. Templates und Marker-Daten bleiben identisch. Gosign hat diesen Wechsel bei mehreren Kunden in unter einem Tag umgesetzt. Die DSGVO-Motivation dahinter: Google Maps überträgt personenbezogene Daten wie die IP-Adresse an Google, auch an Server außerhalb der EU. Mit OpenStreetMap-Kacheln vom eigenen Tile-Server gehen die Daten an niemanden sonst, und ein Consent-Banner für Kartendienste wird überflüssig. Für Unternehmen, die Karten auf jeder Seite einbinden, verbessert das auch die User Experience, weil die Karte sofort sichtbar ist, ohne dass der Besucher erst dem Cookie-Banner zustimmen muss.