MapsLoader

Das Maps Loader Basis Plugin ist die gemeinsame Grundlage für alle Leoparden-Plugins, die Karten (Google Maps oder OpenStreetMap) in der Storefront einbinden. Es kapselt die Karten-Anbindung hinter einer einheitlichen Provider-Abstraktion, liefert ein CMS-Element „Karte", übernimmt die Cookie-Zustimmung und stellt die nötigen Frontend-Bausteine bereit. Nachgelagerte Plugins setzen darauf auf, statt die Karten-Logik erneut zu implementieren.

Der Anbieter (Google Maps oder OSM) wird einmalig in der Plugin-Konfiguration gewählt; der restliche Code – sowohl im MapsLoader selbst als auch in den aufsetzenden Plugins – bleibt unverändert, weil beide Anbieter dieselbe API bedienen.

Auf einen Blick

Bereich	Kurzbeschreibung
Konfiguration	Anbieter (`gmaps`/`osm`) und API-Key in der Plugin-Konfiguration
Provider-Abstraktion	Das npm-Paket `@leoparden/maps-provider` liefert je nach Konfiguration eine einheitliche Karten-API (`getMap`, `addMarker`, `addInfoWindow`, `createLatLng`, `getStyle`)
Cookie-Handling	`MapsCookieProvider` dekoriert den Shopware-`CookieProviderInterface` und ergänzt den anbieter-spezifischen Cookie in der Gruppe „Komfortfunktionen"
CMS-Element	Element `maps` mit Admin-Komponente, Konfiguration und Vorschau sowie Storefront-Rendering
Storefront	`MapsProviderPlugin` registriert den Provider als ServiceProvider und startet das `Maps`-Plugin auf `[data-maps]`
Server-seitig	`MapsCmsElementResolver` löst das Marker-Bild (Media-Entity) des CMS-Elements auf

Begriffe

Provider / Anbieter: Der gewählte Karten-Dienst: gmaps (Google Maps) oder osm (OpenStreetMap / Leaflet). Wird in der Plugin-Konfiguration unter MapsLoader.config.provider gespeichert.
Provider-Abstraktion: Das externe npm-Paket @leoparden/maps-provider. Über GetProvider() liefert es – abhängig von der Konfiguration – eine Provider-Klasse mit einheitlicher API, sodass derselbe aufrufende Code für Google Maps und OSM funktioniert.
CMS-Element "maps": Ein über den Shopping-Experiences-Editor platzierbares Element, das eine Karte mit Marker und Info-Fenster rendert. Konfigurierbar sind Position (lat/lon), Zoom, Marker-Bild und Inhalt.
data-maps: Das Storefront-Attribut, auf das das Maps-Plugin gebunden ist. Ein Element <div data-maps data-maps-options="…"> wird automatisch zu einer Karte initialisiert.

Wo geht es weiter?

Betreiber: Installation & Konfiguration (Anbieter & API-Key), Karten in den Erlebniswelten (Karten-Element in den Erlebniswelten) und Karte in der Storefront (Karte & Cookie-Zustimmung aus Besuchersicht).
Entwickler: Entwickler mit den technischen Details zur Server-Seite und Client-Seite inklusive der Einbindung in ein eigenes Plugin.

Last modified: 27 May 2026