Beispiele

Alle Beispiele zeigen auf den Demo-Mandanten (maps.pixelmap.at/demo/, Kärnten). Für Ihre eigene Karte tauschen Sie demo gegen Ihr Kürzel und die UUIDs gegen Ihre Kategorien.

UUIDs müssen Sie nicht suchen

Die Sektion Einbetten im Editor Ihrer Karte schreibt den fertigen Tag mit Ihren Kategorien. Wer TYPO3 benutzt, wählt Kategorien, Orte und Touren im Backend aus einer Liste statt UUIDs einzutippen.

Die einfachste Karte

Alle Ausflugsziele der Region, bedienbar, mit Knopf zur großen Karte.

<pixelmap-widget
  config-url="https://maps.pixelmap.at/demo/config.json"
  cta-href="https://maps.pixelmap.at/demo/"
  height="420px"
></pixelmap-widget>

Nur bestimmte Kategorien

Zwei Kategorien statt aller. Eine Elternkategorie trifft auch ihre Unterkategorien.

<pixelmap-widget
  config-url="https://maps.pixelmap.at/demo/config.json"
  categories="1a2b3c4d-0000-0000-0000-000000000001,1a2b3c4d-0000-0000-0000-000000000002"
  cta-href="https://maps.pixelmap.at/demo/"
></pixelmap-widget>

Unterkünfte

content-types ersetzt die Vorgabe — hier werden also keine Ausflugsziele geladen, sondern nur Unterkünfte.

<pixelmap-widget
  config-url="https://maps.pixelmap.at/demo/config.json"
  content-types="accommodations"
  cta-href="https://maps.pixelmap.at/demo/"
></pixelmap-widget>

Nur Hotels, ohne den Typ extra aufzuzählen — eine Kategorie eines Typs schaltet ihn mit ein:

<pixelmap-widget
  config-url="https://maps.pixelmap.at/demo/config.json"
  accommodation-categories="<hotel-uuid>"
></pixelmap-widget>

In der Sprechblase stehen bei Unterkünften der „ab”-Preis samt Einheit und die Sterne.

Veranstaltungen

Veranstaltungen haben einen Zeitraum. Vorgabe sind die nächsten sieben Tage; derselbe Zeitraum entscheidet, welche Veranstaltungen erscheinen und welche Termine ihre Sprechblase listet.

<pixelmap-widget
  config-url="https://maps.pixelmap.at/demo/config.json"
  content-types="events"
  event-window="weekend"
></pixelmap-widget>

Ein eigener Zeitraum, beide Enden eingeschlossen:

<pixelmap-widget
  config-url="https://maps.pixelmap.at/demo/config.json"
  content-types="events"
  event-window="2026-12-01..2026-12-24"
></pixelmap-widget>

Veranstaltungen ohne festen Termin bleiben stehen

Manche Veranstaltungen tragen keinen bestimmbaren Termin (etwa eine Dauerausstellung mit Platzhalter-Zeitraum). Die werden nicht weggefiltert — sie erscheinen, nur ohne Datumszeile.

Erlebnisse

<pixelmap-widget
  config-url="https://maps.pixelmap.at/demo/config.json"
  content-types="experiences"
  booking-cta="experiences"
></pixelmap-widget>

Die Sprechblase eines Erlebnisses kann einen Buchungsknopf tragen, der auf den Buchungsweg Ihrer Region führt. Ab 0.21.0 erscheint er nur, wenn Sie ihn mit booking-cta anfordern — wie oben mit experiences oder mit auto für alle Typen. Ohne das Attribut gibt es keinen Knopf. Auch dann erscheint er nur, wenn die Region einen Buchungsweg hinterlegt hat und das Objekt die nötigen Angaben trägt — geraten wird nichts.

Der Knopf ist ein gewöhnlicher Link, der in einem neuen Tab öffnet. Von der Buchungsseite wird nichts nachgeladen; Ihr Einbau bekommt dadurch also keine zusätzliche Fremd-Herkunft in die Content-Security-Policy.

Links auf Ihre eigenen Seiten

Ausflugsziele, Veranstaltungen und Unterkünfte können in ihrer Sprechblase auf ihre Seite bei Ihnen verlinken. Welche Typen das tun, sagt booking-cta:

<pixelmap-widget
  config-url="https://maps.pixelmap.at/demo/config.json"
  content-types="pois,events,accommodations"
  booking-cta="pois,events"
></pixelmap-widget>

Hier tragen Ausflugsziele und Veranstaltungen ihren Link, Unterkünfte nicht. booking-cta="auto" nähme alle Typen, für die Ihre Karte eine Vorlage hat, booking-cta="hidden" keinen. Der Link einer Unterkunft heißt immer „Mehr erfahren”. Touren bekommen nie einen.

Bis 0.20.0 kamen diese Links ohne Attribut

Der Link auf die Seite eines Ausflugsziels oder einer Veranstaltung (seit 0.19.0) und der Buchungsknopf der Erlebnisse erschienen bis 0.20.0 ganz ohne booking-cta. Ab 0.21.0 ist die Vorgabe leer: Wer die Links behalten will, schreibt die Typen oder auto ausdrücklich an den Einbau.

Mehrere Typen zugleich

<pixelmap-widget
  config-url="https://maps.pixelmap.at/demo/config.json"
  content-types="pois,accommodations,events"
  cta-href="https://maps.pixelmap.at/demo/"
  height="520px"
></pixelmap-widget>

Die Ringe fassen alle aktiven Typen zusammen. Ist ein Typ aktiv, steht ein Ringsegment für eine Hauptkategorie dieses Typs; sind es mehrere, steht ein Segment für einen Typ, in dessen Farbe.

Touren

Touren sind kein Wert von content-types — sie haben eigene Attribute, und ohne eines davon wird keine Tour geladen.

<pixelmap-widget
  config-url="https://maps.pixelmap.at/demo/config.json"
  tour-categories="tour.hiking"
  cta-href="https://maps.pixelmap.at/demo/"
></pixelmap-widget>

Ab 0.14.0 nimmt tour-categories beide Wertformen an und mischt sie: den Kategorie-Schlüssel wie oben oder die UUID derselben Kategorie, wie sie ein Kategorie-Picker im Redaktionssystem schreibt. Ein Wert unterhalb der obersten Ebene steigt auf seine oberste Kategorie auf.

Die Linie einer Tour erscheint, sobald der Gast ihren Marker antippt. Sollen die Routen gleich zu sehen sein — etwa auf einer Bühnenkarte —, setzen Sie ab 0.19.0 tour-route="always":

<pixelmap-widget
  config-url="https://maps.pixelmap.at/demo/config.json"
  tour-ids="<id>,<id>"
  tour-route="always"
  interactive="false"
  cta-href="https://maps.pixelmap.at/demo/"
></pixelmap-widget>

Dann zeichnet die Karte die Routen aller gezeigten Touren gleich nach dem Laden, jede in der Farbe ihrer Kategorie — auch ohne Bedienung.

Ausflugsziele und Touren zusammen:

<pixelmap-widget
  config-url="https://maps.pixelmap.at/demo/config.json"
  categories="<uuid>"
  tour-categories="tour.hiking"
></pixelmap-widget>

Eine gepflegte Sammlung

Wenn Ihre Redaktion eine Inhaltssammlung pflegt, können Sie die Karte darauf einschränken, statt Kategorien und IDs zu pflegen:

<pixelmap-widget
  config-url="https://maps.pixelmap.at/demo/config.json"
  content-types="pois,accommodations"
  collection="sommer-highlights"
></pixelmap-widget>

collection ist eine Schnittmenge über alle aktiven Typen — welche Typen aktiv sind, sagen Sie weiterhin selbst.

Eine unerreichbare Sammlung zeigt nichts

Ist der Endpunkt unbekannt oder nicht erreichbar, bleibt die Karte leer und meldet das in der Konsole. Das ist Absicht: die Alternative wäre, im Störfall den gesamten Bestand auszuspielen — also genau das, was die Kuratierung verhindern sollte.

Die Auswahl mitnehmen

Der Knopf „Auf großer Karte ansehen” gibt normalerweise nur den Filterzustand und den gelebten Ausschnitt weiter — Ihre Kuratierung bleibt im Embed, und der Gast landet auf der vollen Karte der Region. Ab 0.14.0 können Sie das ändern:

<pixelmap-widget
  config-url="https://maps.pixelmap.at/demo/config.json"
  poi-ids="<id>,<id>,<id>"
  cta-href="https://maps.pixelmap.at/demo/"
  cta-scope="selection"
></pixelmap-widget>

Die große Karte zeigt dann genau die Inhalte Ihres Embeds. Eine collection reist dabei als Endpunkt mit, nicht als eingefrorene Mitgliederliste — was Ihre Redaktion später ändert, stimmt auch in längst geteilten Links noch. Drüben benennt eine kleine Pille die mitgebrachte Auswahl und gibt sie mit einem Klick wieder frei, damit niemand in Ihrem Ausschnitt festsitzt.

Die zwei Seiten scheitern absichtlich verschieden

Lässt sich eine Sammlung nicht auflösen, zeigt das Embed nichts — Ihre Kuratierung ist ja der Zweck. Die große Karte zeigt dann alles plus einen Hinweis: eine leere Vollkarte sähe kaputt aus.

Der Weg zurück

Der Knopf „Auf großer Karte ansehen” öffnet einen neuen Tab, solange Sie nichts anderes wählen. Der hat keine Vorgeschichte: Der Zurück-Knopf des Browsers führt dort ins Leere, und viele Gäste merken gar nicht, dass sie den Tab gewechselt haben. Ab 0.17.0 nimmt der Link deshalb mit, woher der Gast kam — und die große Karte bietet den Weg zurück von selbst an.

Sie müssen dafür nichts tun. Kein neues Attribut, keine Änderung am Einbau.

Drüben steht „Zurück zu <Name Ihrer Seite>” an zwei Stellen: als Schaltfläche auf der Karte und als Zeile über der Trefferliste. Zwei, weil die Schaltfläche verdeckt ist, sobald der Gast die Seitenleiste geöffnet hat — dort ist die Zeile ohnehin näher an seinem Blick.

Am Schreibtisch schließt die große Karte ihren eigenen Tab. Ihre Seite steht danach genau so da, wie der Gast sie verlassen hat: Scrollstand, aufgeklappte Abschnitte, laufendes Video. Sie wurde ja nie verlassen. Am Telefon führt der Weg zurück stattdessen über den Link auf Ihre Seite.

Öffnen Sie die große Karte über Ihrer Seite (ab 0.27.0, siehe unten), ist der Weg zurück ein Schließen: „Zurück zur Seite” steht an denselben zwei Stellen, und der Gast war nie weg.

Wo der Rückkehrer landet

Der Anker ist die id des <pixelmap-widget> oder die seines nächsten Vorfahren mit id — sofern die Einbettung einen solchen rendert. Auf TYPO3-Fluid-Seiten ist das der Container des Inhaltselements (c<uid>, etwa #c5473), wenn es einen Rahmen hat. Ob ein Headless-Frontend einen Vorfahren mit id ausgibt, entscheidet dessen eigene Ausgabe — dass c<uid>-Kennungen auf der Seite vorkommen, heißt nicht, dass eine davon die Karte umschließt. Ohne Anker landet der Rückkehrer oben auf der Seite.

An Ihrer eigenen Seite lesen Sie es ab, indem Sie im Entwicklerwerkzeug das Widget auswählen und in der Konsole $0.closest('[id]:not([id=""])') ausführen — kommt null zurück, gibt es keinen Anker.

<pixelmap-widget
  id="karte"
  config-url="https://maps.pixelmap.at/demo/config.json"
  cta-href="https://maps.pixelmap.at/demo/"
></pixelmap-widget>

Das Widget erfindet keine id; eine vorhandene muss auf der Seite eindeutig sein, sonst springt der Browser zum ersten Vorkommen. Fehlt jede, funktioniert der Weg zurück unverändert — er beginnt nur am Seitenanfang.

Wenn Sie den Rückweg selbst prüfen wollen

Der Knopf „Auf großer Karte ansehen” ist ein <button> im Shadow-DOM des Widgets, kein Link. Ein Selektor wie a[href] findet ihn deshalb nicht — er trifft nur die Attributionslinks der Karte, und das sieht aus wie „dieses Embed hat gar keinen Knopf”. Am einfachsten prüfen Sie die Adresse, indem Sie den Knopf anklicken und im geöffneten Tab die Adresszeile lesen; dort stehen return-url und return-label. Für eine automatische Prüfung: Der Shadow-Root ist offen, der Knopf also über document.querySelector('pixelmap-widget').shadowRoot.querySelector('.pm-widget-cta') erreichbar.

Was im Link mitreist

Zwei Angaben: die Adresse Ihrer Seite und ihr Titel (auf 60 Zeichen gekürzt, er dient nur der Beschriftung). Kampagnen-Parameter — utm_*, gclid, fbclid, msclkid, dclid — werden dabei entfernt, damit Ihre Statistik den Rückkehrer nicht als neuen Kampagnenbesuch zählt. Pfad, Sprungmarke und alle übrigen Parameter bleiben unverändert stehen.

Warum Telefon und Schreibtisch sich unterscheiden

Gemessen, nicht angenommen: Ein Tab lässt sich nur schließen, solange er genau einen Eintrag in seiner Vorgeschichte hat — das trifft auf den frisch geöffneten zu. Auf dem iPhone schließt Safari den Tab zwar, zeigt danach aber eine andere Seite, nicht Ihre. Am Telefon wird deshalb gar nicht erst geschlossen, sondern gleich der Link genommen.

Die große Karte über Ihrer Seite

Ab 0.27.0 geht die große Karte auf Wunsch als Dialog über Ihrer Seite auf statt in einem neuen Tab. Am Schreibtisch liegt sie mit einem Rand über der Seite, am Telefon füllt sie den Bildschirm. Ihre Seite bleibt darunter stehen, wie der Gast sie verlassen hat.

<pixelmap-widget
  config-url="https://maps.pixelmap.at/demo/config.json"
  cta-href="https://maps.pixelmap.at/demo/"
  cta-target="overlay"
></pixelmap-widget>

Zum Ausprobieren: Variante 14 „Große Karte als Overlay” im Showcase.

cta-target="overlay" gilt für alle drei Wege zur großen Karte: den Knopf „Auf großer Karte ansehen”, die Bühnenkarte und die Details in den Sprechblasen. Die Links aus booking-cta öffnen weiter einen neuen Tab — sie führen auf Ihre Seiten, nicht auf die Karte.

Geschlossen wird auf vier Wegen: mit „Zurück zur Seite” in der Karte, mit Escape, mit einem Klick neben die Karte und mit dem X des Widgets, solange die Karte noch lädt. Hat der Gast in der Karte etwas geöffnet — eine Sprechblase, ein Detail —, schließt Escape zuerst das, das nächste Escape die Karte. Danach liegt der Tastaturfokus wieder auf dem Knopf, der sie geöffnet hat.

Was dafür vorliegen muss

1. Ihre Seite steht in der Konfiguration Ihrer Karte. Nennen Sie uns die Websites, die die Karte über sich öffnen sollen; wir tragen sie ein, und der Eintrag wirkt mit dem nächsten Deploy Ihrer Karte, also nach Sekunden. Eingetragen wird die Herkunft genau so, wie der Browser sie nennt: https://www.example.at — mit https://, ohne Pfad, ohne Schrägstrich am Ende, ohne Platzhalter. https://example.at und https://www.example.at sind zwei Einträge; einen Port braucht nur eine Testumgebung, die einen hat. Dieselbe Liste erlaubt Ihrer Karte, sich in diese Seiten rahmen zu lassen — jeder anderen Seite verweigert sie das.
2. cta-href zeigt auf Ihre Karte — auf die Herkunft Ihrer config-url oder auf eine Kundendomäne Ihrer Karte. Ein Link auf eine andere Seite geht im Tab auf (ab 0.27.1).
3. Ihre Content-Security-Policy lässt den Rahmen zu, falls Ihre Seite eine setzt: frame-src mit der Herkunft der Karte, siehe Content-Security-Policy.

Fehlt eine Voraussetzung, verliert der Gast nichts: Das Widget öffnet die Karte wie bisher im neuen Tab und nennt in der Browser-Konsole, woran es lag — die nicht eingetragene Herkunft, das fremde Ziel oder die blockierende Richtlinie. Dasselbe gilt für Browser ohne modalen Dialog.

Bühnenkarte statt Bedienkarte

Für einen Kopfbereich: die Karte zeigt die Region, reagiert aber nicht auf Bedienung — ein Klick irgendwo führt auf die große Karte.

<pixelmap-widget
  config-url="https://maps.pixelmap.at/demo/config.json"
  interactive="false"
  center="14.3053,46.6247"
  zoom="9"
  height="320px"
  cta-href="https://maps.pixelmap.at/demo/"
></pixelmap-widget>

Fester Ausschnitt

Wenn die Karte immer denselben Ausschnitt zeigen soll, unabhängig davon, wo die Punkte liegen: center und zoom setzen — einzeln greift sonst der Wert aus der Mandanten-Konfiguration.

<pixelmap-widget
  config-url="https://maps.pixelmap.at/demo/config.json"
  center="14.3053,46.6247"
  zoom="12"
  max-bounds="13.9,46.4,14.7,46.9"
></pixelmap-widget>

Das gilt besonders, wenn Ihr Einbau Datensätze per ID nennt: Ab 0.22.0 fährt die Karte sonst auf diese Datensätze. Ein Paar aus center und zoom hält den Ausschnitt fest.

Abgerundete Ecken

Damit die Karte zu einer abgerundeten Kachel Ihres Layouts passt:

pixelmap-widget {
  --pm-widget-radius: 16px;
  max-width: 640px;
  height: 420px;
}

Farben und Schrift

Ab 0.23.0 passt das Widget Sprechblasen und Schrift an Ihr Layout an:

pixelmap-widget {
  --pm-widget-accent: #0b6e4f;
  --pm-widget-surface: #f7f5f0;
  --pm-widget-text: #2b2b2b;
  --pm-widget-font: "Source Sans 3", sans-serif;
}

--pm-widget-accent färbt den Aktionsknopf in der Sprechblase, --pm-widget-surface deren Grund und --pm-widget-text ihre Schrift. Mit --pm-widget-font nimmt die ganze Karte Ihre Schrift an, auch gegen die Brand-Schrift Ihrer Karte. Die Schrift muss Ihre Seite selbst laden. Die Pille „Auf großer Karte ansehen” und die Hinweise behalten ihre Farben. Was jede Variable genau bestimmt, steht im Attribut-Kapitel.

Kontrast prüfen Sie selbst

Das Widget übernimmt Ihre Farben, wie Sie sie setzen, und prüft sie nicht. Ob Schrift und Grund der Sprechblase genug Kontrast haben, liegt dann bei Ihnen. Die Pille und die Hinweise bleiben deshalb bewusst bei ihren festen Farben.