Einbau in ein CMS oder Framework

Für TYPO3 und Astro gibt es fertige Pakete. Nehmen Sie die — sie nehmen Ihnen genau den Handgriff ab, an dem ein selbstgebauter Einbau erfahrungsgemäß scheitert.

TYPO3

Die Extension pixelpoint/typo3-pixelmap-widget bringt die Karte als Inhaltselement mit.

composer require pixelpoint/typo3-pixelmap-widget

• TYPO3 13.4 LTS und 14.3 LTS, PHP 8.2 bis 8.5
• Kategorien, Orte, Touren und Inhaltssammlungen werden im Backend aus einer Liste gewählt — keine UUIDs abtippen. ⚠ Für Tour-Kategorien aus dieser Auswahl braucht die Karte das Widget ab 0.14.0: davor blieb eine so gewählte Kategorie wirkungslos, und die Karte zeigte keine Touren — ohne Fehlermeldung.
• Fünf Inhaltstypen (Ausflugsziele, Touren, Unterkünfte, Veranstaltungen, Erlebnisse) samt Zeitfenster für Veranstaltungen
• Die Konfiguration kann wahlweise headless als JSON ausgeliefert werden, wenn das Frontend entkoppelt ist

Das Paket liegt in einer GitLab-Composer-Registry, nicht auf Packagist — die Einrichtung steht im README der Extension.

Astro

pnpm add @pixelpoint/pixelmap-astro @innoex/pixelmap-widget maplibre-gl

---
import PixelmapWidget from '@pixelpoint/pixelmap-astro/PixelmapWidget.astro'
---

<PixelmapWidget
  configUrl="https://maps.pixelmap.at/demo/config.json"
  categories={['uuid1', 'uuid2']}
  ctaHref="https://maps.pixelmap.at/demo/"
  height="480px"
/>

Dazu eine Zeile in der astro.config.mjs, wenn Sie MapLibre 6 fahren:

import pixelmap from '@pixelpoint/pixelmap-astro/integration'

export default defineConfig({ integrations: [pixelmap()] })

Die Integration erkennt an Ihrer installierten MapLibre-Fassung, ob ein externer Worker gebraucht wird, und verdrahtet ihn. Unter MapLibre 5 tut sie nichts.

Eigener Bundler

Ohne eines der beiden Pakete verdrahten Sie den MapLibre-Worker selbst. Das ist seit Widget 0.12.0 Pflicht und betrifft nur den Bundler-Weg — der Einbau per <script type="module"> braucht es nie.

1. Ein Plugin, das den Worker findet. Es prüft, ob Ihre MapLibre-Fassung einen externen Worker mitbringt:

   import { createRequire } from 'node:module'
   const require = createRequire(import.meta.url)
   
   export function maplibreWorkerUrlModule() {
     let workerSpecifier = null
     try {
       require.resolve('maplibre-gl/dist/maplibre-gl-worker.mjs')
       workerSpecifier = 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url'
     } catch {
       // MapLibre 5 bündelt seinen Worker inline — dann bleibt WORKER_URL leer.
     }
     const id = 'virtual:maplibre-worker-url'
     const aufgelöst = '\0' + id
     return {
       name: 'maplibre-worker-url',
       resolveId: (quelle) => (quelle === id ? aufgelöst : null),
       load: (i) =>
         i === aufgelöst
           ? workerSpecifier
             ? `export { default } from ${JSON.stringify(workerSpecifier)}`
             : 'export default null'
           : null,
     }
   }

   Eintragen unter plugins Ihrer vite.config.js. Astro-Projekte haben keine vite.config.js — dort gehört es in die astro.config.mjs unter vite: { plugins: [ … ] }.

2. Die Verdrahtung, im faulen Pfad:

   let pending
   const load = () =>
     (pending ??= (async () => {
       const [{ config }, { default: workerUrl }] = await Promise.all([
         import('maplibre-gl'),
         import('virtual:maplibre-worker-url'),
       ])
       if (workerUrl) config.WORKER_URL = workerUrl
       return import('@innoex/pixelmap-widget')
     })())

   load() rufen Sie, wenn die Karte gebraucht wird. Mehrfach rufen ist unschädlich.

Der Fehler, der nicht wie ein Fehler aussieht

Bleibt der Worker unverdrahtet, laufen Hauptthread und Worker auseinander und die Karte bleibt leer — bei fehlerfreiem Aussehen. Kein Absturz, keine rote Meldung im Build. Wenn eine Karte in einer Bundler-Integration leer bleibt, ist das die erste Stelle, an der Sie nachsehen.

Auch MapLibre selbst gehört in den dynamischen Import

Ein statisches import { config } from 'maplibre-gl' zieht MapLibre in den anfänglichen Seitenaufbau — der faule Widget-Import danach nützt dann nichts, die Masse ist längst geladen. Gemessen an einer echten Integration: drei MapLibre-Anfragen im Erstaufbau einer Seite, deren Karte 400 vh unter dem Falz steht.

Wenn die Karte über dem Falz steht

Das Widget baut seine Karte erst auf, wenn es sichtbar wird. Das spart die Karten-Kosten, nicht das Bundle:

`display: none` verhindert das Laden NICHT

Ein <script type="module" src="…"> im Markup lädt unbedingt, unabhängig davon, ob das Element sichtbar ist. Gemessen: 757 kB mit verstecktem Element gegenüber 324 kB, wenn das <script>-Tag erst im Klick-Handler eingefügt wird.

Zwei tragfähige Wege, wenn das Gewicht zählt:

• Fassade: ein statisches Vorschaubild mit Knopf; das <script>-Tag wird erst bei Interaktion eingefügt.
• Bundler mit dynamischem import() (etwa das Astro-Paket): ein verstecktes Element löst dort null Anfragen aus.

Was Sie serverseitig nicht einrichten müssen

Das Widget wird auf einer fremden Herkunft eingebunden, jede Anfrage ist also herkunftsübergreifend und braucht CORS-Kopfzeilen. Die werden auf maps.pixelmap.at automatisch gesetzt — für jede Karte, ab ihrem ersten Deploy. Es gibt keinen Handgriff je Kunde und keinen je Karte.

Woran Sie eine fehlende Kopfzeile trotzdem erkennen würden (etwa bei einem eigenen, selbst betriebenen Host):

Symptom	Ursache
„Karte konnte nicht geladen werden.” statt einer Karte	CORS fehlt auf der config.json
Karte da, aber Marker sind einfarbige Punkte statt Symbolen	CORS fehlt auf den Symbol-Dateien (/sprites/**) — die Karte funktioniert, sie sieht nur ärmer aus. Ab 0.24.0 fallen dann auch die Symbole in den Sprechblasen auf die mitgelieferte Liste zurück, mit einer Warnung in der Konsole

Ereignisse

Ab Widget 0.19.0 meldet das Element drei Ereignisse, auf die Ihre Seite hören kann — etwa um ein Lade-Skelett auszublenden oder eine leere Karte durch einen eigenen Hinweis zu ersetzen. Es sind CustomEvents am <pixelmap-widget>, mit bubbles und composed: Ein Zuhörer am umgebenden Container oder am document hört sie ebenso.

Ereignis	Wann	event.detail
pixelmap-ready	Die Karte ist geladen und die Einträge sind eingespielt — bei jedem erfolgreichen Laden, auch mit 0 Einträgen.	{ features, tours } (Anzahlen)
pixelmap-empty	Direkt nach pixelmap-ready, wenn keine Einträge sichtbar sind.	{ reason }: collection, no-data oder no-match
pixelmap-error	Ein harter Fehler, die Karte ist unbrauchbar — oder die Basiskarte kam gar nicht.	{ stage, message }, stage: config, init, layers oder tiles

• reason: collection — die Sammlung war leer oder nicht auflösbar; no-data — es kamen gar keine Einträge an; no-match — Einträge waren da, aber Ihre Auswahl (IDs, Kategorien, Zeitraum) ließ keinen übrig.
• stage: config — config-url fehlt oder die config.json war nicht ladbar; init — der Aufbau von Daten oder Karte scheiterte; layers — die Karte lud, ihre Ebenen ließen sich nicht einrichten; tiles — binnen 8 s nach dem Laden kam keine einzige Kachel der Basiskarte an. Bei tiles malt das Widget weiter, Marker und Sprechblasen bleiben nutzbar; Ihre Seite entscheidet, was sie daraus macht. Einzelne fehlende Kacheln sind kein Ausfall.
• message ist technisch und für die Konsole gedacht, nie für Besucher.
• Bei einer leeren Karte zeigt das Widget selbst einen dezenten Hinweis oben in der Mitte, bei einem Fehler seine Fehlermeldung.
• Die Ereignisse feuern erst, wenn das Element in den Sichtbereich kommt — dann beginnt das Widget zu laden. Ein Zuhörer, den Sie vor dem Einfügen anlegen, verpasst also nichts.

document.addEventListener('pixelmap-error', (e) => {
  console.warn('pixelmap', e.detail.stage, e.detail.message);
});

Content-Security-Policy

Das Widget rendert in einem eigenen Shadow DOM und bringt seine Stile mit — Sie importieren kein zusätzliches CSS. An Fremd-Herkünften braucht es den SPA-Host Ihrer Karte (maps.pixelmap.at oder Ihre Kundendomäne) sowie die Kachel-Hosts. Die Links in den Sprechblasen (booking-cta) fügen keine weitere Herkunft hinzu: Sie sind gewöhnliche Links, von dort wird nichts geladen.

font-src, sobald Ihre Karte eine Brand-Schrift hat

Ab Widget 0.20.0 lädt das Widget die Brand-Schrift Ihrer Karte, wenn Sie eine gewählt haben. Die Schriftdateien kommen von der Herkunft Ihrer config-url (in aller Regel https://maps.pixelmap.at) und fallen unter font-src. Genau diese Herkunft geben Sie frei — auch bei einer eigenen Schriftdatei, denn eine andere Herkunft kann die Konfiguration nicht tragen. Fehlt die Freigabe, bleibt die Ersatzschrift, und die Konsole nennt die blockierte Adresse.

frame-src, sobald die große Karte über Ihrer Seite aufgeht

Mit cta-target="overlay" (ab Widget 0.27.0) lädt das Widget die große Karte in einen Rahmen auf Ihrer Seite. Geben Sie dafür unter frame-src die Herkunft von cta-href frei — https://maps.pixelmap.at oder Ihre Kundendomäne. Fehlt die Freigabe, öffnet das Widget ab 0.27.1 die Karte im neuen Tab und nennt die fehlende Richtlinie in der Konsole. Siehe Die große Karte über Ihrer Seite.