Versionen

Script-Tag: keine Version nötig

<script type="module" src="https://maps.pixelmap.at/widget/pixelmap-widget.js"></script>

Diese Adresse liefert immer die aktuelle veröffentlichte Fassung. Sie tun nichts, um aktuell zu bleiben. Wo diese Seite „ab 0.14.0” oder eine spätere Fassung nennt, ist damit die Fassung gemeint, die diese Adresse ausliefert — ein Einbau, der ein neues Attribut nutzt, wirkt, sobald sie dort liegt.

Seit 0.21.0 gilt das auch für eine brechende Änderung

Wer über diese Adresse einbindet, bekommt jede neue Fassung sofort — auch 0.21.0, die die Links in den Sprechblasen abschaltet, solange booking-cta fehlt. Was zu tun ist, steht unten bei 0.21.0.

Welche Fassung läuft gerade? Öffnen Sie auf der Seite mit der Karte die Browser-Konsole und lesen Sie window.__PIXELMAP_WIDGET_VERSION__ — etwa "0.27.1". Das geht ab 0.18.0; davor trug das Bundle keine Kennung.

npm-Paket: @innoex/pixelmap-widget

Das Paket folgt SemVer und steht vor 1.0. In dieser Phase gilt:

MINOR (0.12 → 0.13)	Neue Funktion oder eine brechende Änderung
PATCH (0.13.0 → 0.13.1)	Fehlerbehebung

Vor 1.0 ist MINOR auch die brechende Stufe

Das ist SemVer für 0.x und kein Sonderweg: ^0.13.0 nimmt deshalb nur 0.13.-Patches an. Wer automatisch mitwandern will, muss die Spanne selbst weiter fassen — und sollte dann den nächsten Abschnitt lesen.

Stand dieser Seite: 0.27.1.

0.27.1 sichert das Overlay aus 0.27.0 ab. Es öffnet nur noch, wenn cta-href auf Ihre Karte zeigt — die Herkunft Ihrer config-url oder eine Kundendomäne Ihrer Karte. Ein Redaktionslink auf eine andere Seite geht wie bisher im Tab auf, statt in einem leeren Rahmen zu enden. Blockiert die Content-Security-Policy Ihrer Seite den Rahmen, weil frame-src die Karte nicht freigibt, schließt das Widget den Dialog und öffnet die Karte im Tab; die Konsole nennt die fehlende Freigabe. cta-target wirkt nur zusammen mit cta-href. contractVersion bleibt 2.

0.27.0 öffnet die große Karte auf Wunsch über Ihrer Seite statt in einem neuen Tab: mit cta-target="overlay", für den Knopf „Auf großer Karte ansehen”, die Bühnenkarte und die Details der Sprechblasen. Voraussetzung ist, dass Ihre Seite in der Konfiguration Ihrer Karte eingetragen ist — wie, steht bei Die große Karte über Ihrer Seite. Fehlt der Eintrag, öffnet das Widget den Tab und nennt die Herkunft in der Konsole. Ohne das Attribut ist alles wie in 0.26.0, das ist additiv. contractVersion bleibt 2. In dieser Fassung ergab eine Content-Security-Policy ohne frame-src für die Karte noch einen leeren Rahmen — behoben in 0.27.1. Seit dieser Fassung schreibt das Widget Strecken und Flächen in der Sprache der Karte: Deutsch mit Komma, Englisch mit Punkt.

0.26.0 liefert MapLibre 6.13.0 aus (vorher 6.5.0). Das betrifft nur die Fassung unter der Script-Adresse; die Spanne, die das npm-Paket von Ihnen verlangt, bleibt ^5 || ^6. Auf dem iPhone öffnet langes Drücken in der Karte seitdem kein Kontextmenü mehr. Kein Attribut, contractVersion bleibt 2.

0.25.0 nimmt Symbole für die Sprechblasen aus dem Deploy Ihrer Karte nur noch aus einer festen Liste an. Kein Attribut, contractVersion bleibt 2.

0.24.0 holt die Symbole der Sprechblasen aus dem Deploy Ihrer Karte (sprites/<id>/icon-nodes.json, neben den Marker-Symbolen). Ein neues Symbol aus dem Katalog braucht damit keine neue Widget-Fassung mehr; fehlt die Datei, weil Ihre Karte zuletzt vorher deployt wurde, nimmt das Widget still die mitgelieferte Liste. Die Adressen der Marker-Symbole tragen jetzt die Kennung ihres Stands (?v=<spriteVersion>): Neue Marker sind nach einem Deploy sofort sichtbar, statt bis zu einer Stunde im Cache zu hängen. Behoben ist der Umbruch eines langen cta-label: Die Pille bleibt einzeilig und endet mit Auslassungspunkten, der volle Text bleibt ihr zugänglicher Name. Außerdem verfälscht ein $ in der Kachel-Adresse — etwa in einer signierten CDN-URL — die Adressen von Kacheln, Symbolen und Beschriftungs-Glyphen nicht mehr. Kein Attribut ist neu oder entfallen, das ist additiv. contractVersion bleibt 2.

0.23.0 gibt Ihnen einen Theming-Vertrag: vier neue CSS-Variablen neben dem bekannten --pm-widget-radius — --pm-widget-accent, --pm-widget-text, --pm-widget-surface und --pm-widget-font. Sie wirken am <pixelmap-widget> oder an einem seiner Vorfahren; was jede davon färbt, steht im Attribut-Kapitel. Eine Schrift über --pm-widget-font schlägt die Brand-Schrift Ihrer Karte. Die Pille „Auf großer Karte ansehen” und die Hinweise behalten ihre Farben. Die internen --color-*-Variablen sind kein Vertrag — was Sie dort setzen, kann mit der nächsten Fassung wirkungslos werden. Das ist additiv: ohne die Variablen ändert sich nichts. contractVersion bleibt 2. Neu liegen die Lizenzhinweise zu Fremdcode bei (THIRD_PARTY_NOTICES.txt) — im npm-Paket, nicht unter der Auslieferungsadresse des Widgets. In dieser Fassung brach ein langes cta-label noch um, statt mit Auslassungspunkten zu enden — behoben in 0.24.0.

0.22.0 richtet den Ausschnitt nach Ihrer Auswahl aus. Nennt Ihr Einbau Datensätze per ID (poi-ids, tour-ids, accommodation-ids, event-ids, experience-ids), fährt die Karte nach dem Laden auf diese Datensätze — auf einen einzelnen zentriert, höchstens so nah, wie fit-max-zoom erlaubt (Vorgabe 14). Bisher blieb sie auf dem Startausschnitt Ihrer Karte stehen, und die Auswahl lag oft außerhalb des Bildes. Die Kategorie-Attribute lösen das bewusst nicht aus: eine Kategorie kann die ganze Region umfassen. contractVersion bleibt 2, aber wer IDs setzt, sieht einen anderen Ausschnitt. ⚠ Wollen Sie den bisherigen behalten, setzen Sie center und zoom ausdrücklich — ein Paar schlägt die Anpassung, eine Hälfte allein nicht.

0.21.0 ist brechend, und contractVersion steigt deshalb von 1 auf 2. booking-cta steuert jetzt die Links aller Sprechblasen und ist eine Liste: pois, accommodations, events, experiences, dazu auto (alle Typen, für die Ihre Karte eine Vorlage hat) und hidden (keine). Neu ist dabei der Link einer Unterkunft auf deren Seite bei Ihnen. Die Vorgabe ist leer: Ohne das Attribut trägt keine Sprechblase mehr einen Link, nur noch den Knopf „Auf großer Karte ansehen”. Bis 0.20.0 erschienen der Buchungsknopf der Erlebnisse und die Seitenlinks von Ausflugszielen und Veranstaltungen ohne jedes Attribut. ⚠ Was Sie tun müssen: Wollen Sie die Links behalten, schreiben Sie die Typen oder auto ausdrücklich an den Einbau — etwa booking-cta="pois,events" oder booking-cta="auto". Ein Redaktionssystem, das beim Speichern die frühere Vorgabe auto weglässt, schreibt damit jetzt „keine Links”. Details im Attribut-Kapitel.

0.20.0 übernimmt die Brand-Schrift Ihrer Karte, sofern Sie eine gewählt haben: Fließtext für Karte, Sprechblasen, Pille und Hinweise, die Überschriftenschrift für den Titel der Sprechblase. Ohne Wahl ändert sich nichts, das Widget erbt weiter die Schrift Ihrer Seite. ⚠ Setzt Ihre Seite eine Content-Security-Policy, muss font-src die Herkunft Ihrer config-url freigeben — siehe Content-Security-Policy. Kein Attribut, contractVersion blieb 1.

0.19.0 bringt das Attribut tour-route (on-tap wie bisher oder always: die Routen aller gezeigten Touren gleich nach dem Laden), einen Link auf die Seite des Ausflugsziels bzw. der Veranstaltung bei Ihnen in der Sprechblase und drei Ereignisse (pixelmap-ready, pixelmap-empty, pixelmap-error), auf die Ihre Seite hören kann. Eine leere Karte zeigt jetzt einen dezenten Hinweis statt einer stummen Fläche. Dazu kommt Zugänglichkeit: Die Kartenfläche trägt einen Namen in der Sprache des Widgets — oder den Text eines aria-label am Element —, die Bedienknöpfe zeigen bei Tastaturfokus einen Ring, und Sprechblasen sind benannte Dialoge, die Escape schließt. Additiv, die Zahl der Attribute steigt auf 31. contractVersion blieb 1.

0.18.0 behebt drei Dinge, die Ihnen auffallen konnten: Ist der Kategorienbaum auf dem Server nicht lesbar, warnt jetzt auch das Widget in der Konsole, statt den Filter still wirkungslos zu lassen. Eine geöffnete Sprechblase verbirgt die Pille „Auf großer Karte ansehen”, statt sie zu überdecken (in Safari ab 15.4 und Firefox ab 121). Und ein 1×1-Platzhalterbild gilt als kein Bild. Neu ist die auslesbare Fassung window.__PIXELMAP_WIDGET_VERSION__. Kein Attribut, contractVersion blieb 1.

0.17.0 gibt dem Gast einen Weg zurück. Der Knopf „Auf großer Karte ansehen” öffnet einen neuen Tab ohne Vorgeschichte; ab dieser Version nimmt der Link Adresse und Titel Ihrer Seite mit, und die große Karte bietet „Zurück zu <Ihre Seite>” an — als Schaltfläche auf der Karte und als Zeile über der Trefferliste. Am Schreibtisch schließt sie dafür ihren eigenen Tab, sodass Ihre Seite unberührt dasteht; am Telefon führt der Link zurück. Das ist eine Änderung am Verhalten des Knopfes, nicht am Einbau: kein neues Attribut, die Zahl blieb bei 30, und Sie müssen nichts tun. Als Sprungmarke dient die id des <pixelmap-widget> oder die seines nächsten Vorfahren mit id, sofern die Einbettung einen solchen rendert; sonst beginnt die Seite oben (Der Weg zurück). contractVersion blieb 1.

0.16.0 ändert Verhalten, nicht nur Wortlaut: Eine Kategorie, die in keinem Ihrer aktiven Kategorienbäume aufgeht, leert ab dieser Version den betroffenen Typ, statt ignoriert zu werden. Damit entscheiden alle fünf Kategorie-Attribute denselben Fall gleich — und die eingebettete Karte zeigt dasselbe wie die große. Was das für Sie heißt und wo die Grenzen liegen, steht im Attribut-Kapitel. ⚠ Prüfen Sie nach dem Update einmal die Browser-Konsole: Eine Karte, die vorher trotz eines verwaisten Werts alles zeigte, zeigt jetzt nichts — der beanstandete Wert steht dort namentlich. contractVersion blieb 1; am Einbau änderte sich nichts.

0.15.0 zieht die vier Inhaltstyp-Kategorien nach: categories, accommodation-categories, event-categories und experience-categories nehmen jetzt — wie tour-categories seit 0.14.0 — Kategorie-Schlüssel und Kennung, mischbar. Und ein Wert, den der Kategorienbaum Ihrer Region nicht kennt, ist nicht mehr stumm: Die Browser-Konsole nennt das Attribut und den beanstandeten Wert. Was der Filter dann tut, steht im Attribut-Kapitel — er wird wirkungslos, der Typ kommt vollständig.

0.14.0 brachte das Attribut cta-scope und tour-categories in beiden Wertformen.

Beides war additiv — bestehende Einbauten änderten sich nicht, und contractVersion blieb deshalb 1.

Verträglichkeit erkennt man an contractVersion, nicht an der Versionsnummer

Das Paket veröffentlicht neben der Versionsnummer eine eigene, ganzzahlige contractVersion. Sie beschreibt den Attribut-Vertrag — also das, was Ihr Einbau tatsächlich benutzt. Sie steigt nur, wenn sich dieser Vertrag brechend ändert, und steht derzeit auf 2 — seit 0.21.0, als booking-cta zur Liste wurde. Davor stand sie von 0.4.0 bis 0.20.0 auf 1, über alle MINOR-Sprünge dazwischen hinweg.

Für ein Integrationspaket heißt das: die ehrliche Aussage ist „verträglich mit jeder Fassung, deren contractVersion 2 ist” — nicht eine Aufzählung einzelner Minor-Versionen. So hält es @pixelpoint/pixelmap-astro (Stand 0.9.1): Es verlangt @innoex/pixelmap-widget in der Spanne >=0.4 <1 als peerDependency und ist gegen ^0.23.0 getestet.

Warum eine Aufzählung schadet

Eine Liste erlaubter Minor-Versionen hat frische Installationen zweimal ausgesperrt, jeweils am Tag einer Widget-Veröffentlichung: das neue Minor stand noch in keiner Liste, obwohl der Vertrag unverändert war.

Die verträgliche MapLibre-Spanne steht ebenfalls maschinenlesbar im Vertrag (@innoex/pixelmap-widget/contract → maplibreRange). Wer sie für eigene Kunden deklarieren muss, leitet sie von dort ab, statt sie abzuschreiben — zwei Literale sind zwei Wahrheiten, und eine davon läuft nach.

MapLibre ist Ihre Abhängigkeit, nicht unsere

npm i @innoex/pixelmap-widget maplibre-gl

maplibre-gl (^5 || ^6) ist eine Peer-Dependency und wird bewusst nicht mitgeliefert: sonst hätte Ihre Anwendung am Ende zwei Kopien von MapLibre im Bundle.

Der Unterschied zwischen den beiden Hauptversionen ist für Sie an genau einer Stelle spürbar: MapLibre 6 bringt keinen eingebauten Worker mehr mit. Ab Widget 0.12.0 muss Ihr Build deshalb sagen, wo dieser Worker liegt — siehe Einbau in ein CMS oder Framework. Unter MapLibre 5 entfällt das.

Registry

Das Paket liegt in einer privaten GitLab-Registry, nicht auf npmjs.org. Ohne die passenden .npmrc-Zeilen antwortet die Installation mit einem irreführenden 404 — es sieht dann aus, als gäbe es das Paket nicht.

@innoex:registry=https://git.pixelpoint.biz/api/v4/projects/<PROJEKT-ID>/packages/npm/
//git.pixelpoint.biz/api/v4/projects/<PROJEKT-ID>/packages/npm/:_authToken=<IHR-TOKEN>

Das Token braucht mindestens read_package_registry. Projekt-ID und Token bekommen Sie von uns.

Wenn eine Karte nach einem Update leer bleibt

Die Reihenfolge, in der sich das erfahrungsgemäß aufklärt:

1. Bundler-Einbau ohne Worker-Verdrahtung — der häufigste Fall seit MapLibre 6. Die Karte bleibt leer, ohne dass irgendetwas rot wird.
2. Konsole lesen. Fehlende Inhalte melden sich dort als Warnung, nicht als Absturz: ein Inhaltstyp, den Ihre Region nicht veröffentlicht, eine unerreichbare Sammlung, ein unlesbarer Zeitraum.
3. config-url prüfen. Antwortet sie nicht oder ohne CORS-Kopfzeile, zeigt das Widget seinen Rückfalltext „Karte konnte nicht geladen werden.“.

Ab 0.19.0 sagt die Karte selbst, welcher Fall vorliegt: Oben in der Mitte steht dann „Keine Einträge für diese Auswahl.” oder „Inhalte konnten gerade nicht geladen werden.“, und Ihre Seite kann auf die Ereignisse pixelmap-empty und pixelmap-error hören.

Fehlen nach dem Update nur die Links in den Sprechblasen, ist das 0.21.0: Setzen Sie booking-cta mit den gewünschten Typen oder auto.