Frontend

Im Frontend besteht der MapsLoader aus einer Provider-Abstraktion, einem Storefront-Plugin, dem CMS-Element und den nötigen Twig-Bausteinen. Die eigentliche Karten-Logik liegt im npm-Paket @leoparden/maps-provider.

Globale Konfiguration

meta.html.twig überträgt Anbieter und API-Key aus der Plugin-Konfiguration in den Browser:

{% sw_extends '@Storefront/storefront/layout/meta.html.twig' %}
{% block layout_head_javascript_hmr_mode %}
    {{ parent() }}
    <script>
        window.maps_api_key = "{{ config('MapsLoader.config.apiKey') }}";
        window.maps_provider = "{{ config('MapsLoader.config.provider') }}";
    </script>
{% endblock %}

Über window.maps_provider entscheidet @leoparden/maps-provider, welche Implementierung (Google Maps oder Leaflet/OSM) GetProvider() zurückliefert.

Provider & ServiceProvider

MapsProviderPlugin (gebunden an body) instanziiert den Provider, registriert ihn als ServiceProvider unter dem Namen MapsProviderPlugin und startet anschließend das Maps-Plugin auf allen [data-maps]-Elementen:

const {PluginManager, ServiceProvider} = window
const {GetProvider} = await import("@leoparden/maps-provider");
const Provider = new (await GetProvider())();
ServiceProvider.register('MapsProviderPlugin', Provider);
Provider.init();
PluginManager.register("Maps", () => import('./maps.plugin'), "[data-maps]");
PluginManager.initializePlugin('Maps', "[data-maps]");

Das Maps-Plugin

maps.plugin.ts liest seine Optionen aus dem data-maps-options-Attribut und baut Karte, Marker und Info-Fenster auf. Verfügbare Optionen:

Option	Standard	Bedeutung
`lat`/`lon`	`49`/`9`	Mittelpunkt der Karte
`zoom`	`9`	Zoomstufe
`markerImage`	`""`	URL der Marker-Grafik (Fallback: Leaflet-Standardmarker)
`content`	–	Inhalt des Info-Fensters
`style`	`silver`	Karten-Stil (über `provider.getStyle(...)`)

Der eigentliche Aufbau läuft über die einheitliche Provider-API:

const provider = window.ServiceProvider.get("MapsProviderPlugin");
await provider.prepare(this.el, async () => {
    const center = provider.createLatLng(this.options.lat, this.options.lon);
    const map = provider.getMap(this.el, { zoom: this.options.zoom, center: center.getNative(), /* … */ });
    const marker = provider.addMarker({ position: map.getCenter(), map });
    const infoWindow = provider.addInfoWindow({ position: marker.getPosition(), map });
    infoWindow.setContent(this.options.content);
});

prepare() kapselt das Cookie-Consent: Der Callback läuft erst, wenn der Besucher dem Karten-Cookie zugestimmt hat.

CMS-Element „maps"

In der Administration registriert main.ts die Komponenten maps-component, maps-config und maps-preview sowie das CMS-Element maps (Label plugin.leoparden.MapsLoader.label). Die Konfigurations-Komponente blendet beim Mouseover eine interaktive Karte ein und schreibt lat/lon/zoom beim Verschieben/Zoomen zurück in die Element-Konfiguration.

Im Storefront rendert cms-element-maps.html.twig das Element, indem es die Feld-Konfiguration zu data-maps-options serialisiert:

{% sw_extends '@Storefront/storefront/component/maps-element.html.twig' %}
{% block maps_element %}
    {% set config = element.fieldConfig.elements|map(p => p.value)|merge({ markerImage: element.data.url, style: 'silver' }) %}
    <div class="cms-element-{{ element.type }} leoparden-maps-element" data-maps data-maps-options="{{ config|json_encode }}">
        {{ block('privacy_element') }}
    </div>
{% endblock %}

Einbindung in ein eigenes Plugin

Aufsetzende Plugins implementieren kein eigenes Karten-Handling, sondern liefern nur ein [data-maps]-Element mit den passenden Optionen und binden den Privacy-Block ein (er übernimmt das Cookie-Handling):

{% sw_extends '@Storefront/storefront/component/maps-element.html.twig' %}
{% block maps_element %}
    <div class="leoparden-maps-element" data-maps data-maps-options="{{ config|json_encode }}">
        {{ block('privacy_element') }} {# notwendig für das Cookie-Handling #}
    </div>
{% endblock %}

Wird ein eigenes Storefront-TS-Plugin benötigt, holt es sich den Provider über window.ServiceProvider.get("MapsProviderPlugin") und nutzt dieselbe API wie oben. Für die Typisierung im eigenen Plugin verweist die tsconfig.json auf die Shims aus @leoparden/plugin-tools-storefront sowie die shims.d.ts des MapsLoader (siehe readme.md).

Snippets

Alle Snippet-Keys folgen dem Präfix plugin.leoparden.MapsLoader.*. Die Storefront-Snippets liegen unter src/Resources/snippet/ (DE/EN), das Label des CMS-Elements in den Administrations-Snippets des Moduls:

Key	Ort	Verwendung
`…MapsLoader.label`	Administration	Bezeichnung des CMS-Elements
`…MapsLoader.cookie.<provider>`	Storefront	Cookie-Bezeichnung (Komfortfunktionen)
`…MapsLoader.privacy-text.<provider>`	Storefront	Datenschutz-Hinweistext vor dem Laden der Karte
`…MapsLoader.privacy-confirm`	Storefront	Beschriftung des Zustimmungs-Buttons

Last modified: 27 May 2026