Pages Map als Web Component

Die Web Component <done-generic-map> stellt die gemeinsame destination.one-Karte für externe Websites bereit. Datenquelle, Kartenverhalten und UI werden über HTML-Attribute oder über die JavaScript-Properties source und options konfiguriert.

Einbindung

Das Web-Component-Bundle wird einmal in die Host-Seite eingebunden:

<script
  type="module"
  src="https://newpages.destination.one/web-components.js"
  data-language="de"
  data-experience="example"
  data-template="wlan"
></script>

Die Karte belegt immer 100 % der Breite und Höhe ihres Elternelements. Das Elternelement muss deshalb eine berechenbare Höhe besitzen:

<div class="map-container">
  <done-generic-map source-kind="query" type="Tour,POI"></done-generic-map>
</div>

<style>
  .map-container {
    width: 100%;
    height: 600px;
  }
</style>

Ohne eine Höhe am Elternelement hat auch height: 100% der Karte keine sichtbare Höhe.

Datenquellen

source-kind bestimmt, woher die Kartendaten stammen.

query	Lädt Marker über eine META-Suchanfrage. Dies ist der Standard.
items	Zeigt eine vorgegebene Liste von META-Items.
detail	Zeigt ein primäres Detail-Item und optional Wegpunkte, verwandte und empfohlene Items. Tour- oder Area-Geometrien werden unmittelbar angezeigt.
location	Zeigt eine feste Position oder lässt den Benutzer eine Position auf der Karte auswählen. Dieser Modus wird über source oder source-json konfiguriert.

Query-Quelle über HTML

Für eine Query-Quelle stehen folgende Attribute zur Verfügung:

Items-Quelle über HTML

Mit source-kind="items" kann der WC-Adapter Items anhand ihrer IDs laden:

<done-generic-map
  source-kind="items"
  global-ids="p_100235769,p_100027802,p_100152965"
></done-generic-map>

Alternativ akzeptiert items-json ein JSON-Array vollständiger META-Items. Für dynamische Daten ist die JavaScript-Property source vorzuziehen.

Detail-Quelle über HTML

Der Detailmodus lädt das primäre Item über global-id. Nicht explizit übergebene Wegpunkte, verwandte und empfohlene Items werden standardmäßig automatisch geladen.

<done-generic-map
  source-kind="detail"
  type="Tour"
  global-id="t_100267026"
  detail-auto-load-items="true"
></done-generic-map>

detail-auto-load-items="false" deaktiviert das automatische Nachladen. Vollständige Items können über item-json, waypoint-items-json, related-items-json und recommendation-items-json oder über die entsprechenden JavaScript-Properties gesetzt werden.

Location-Quelle

Der feste Modus zeigt einen Marker an der angegebenen Position. Optional wird ein kreisförmiger Radius in Kilometern dargestellt:

map.source = {
  kind: 'location',
  mode: 'fixed',
  position: { lat: 53.1435, lng: 7.3412 },
  radiusKm: 5,
  showRadius: true,
};

Im Pick-Modus wird der Marker durch einen Kartenklick gesetzt. Die Position wird über das Event location-select ausgegeben:

map.source = {
  kind: 'location',
  mode: 'pick',
  radiusKm: 5,
  showRadius: true,
};

GenericMapOptions

Alle Optionen sind optional. Die Spalte „HTML-Attribut“ zeigt das zugehörige flache Attribut der Web Component. Bei booleschen Attributen aktiviert sowohl ein leeres Attribut als auch der Wert "true" die Option; zum Deaktivieren wird ausdrücklich "false" gesetzt.

Karte und Provider

Viewport

Tour- und Area-Geometrien

Die Geometrien werden aus den META-Items beziehungsweise über die dafür vorgesehenen META-Geometrieanfragen ermittelt. Externes GeoJSON muss nicht erzeugt oder übergeben werden.

Routing

Ergebnisdichtepunkte

Die Query kann über folgende flache Attribute überschrieben werden: density-points-custom-query, density-points-type, density-points-categories, density-points-features, density-points-cities, density-points-keywords und density-points-sort. Ohne explizite Density-Query verwendet eine Query-Quelle automatisch die Marker-Query; limit und andere Paginationseinstellungen werden dabei entfernt.

Interaktionen

Benutzeroberfläche

Einige Defaults sind vom Datenmodus abhängig. „Detail“ bezeichnet source.kind: 'detail'.

Beschriftungen

Die Standardwerte stammen aus den Übersetzungen der konfigurierten Sprache.

Vollständiges HTML-Beispiel mit flachen Attributen

Flache Attribute sind für CMS- und statische HTML-Einbindungen vorgesehen:

<div class="tour-map">
  <done-generic-map
    source-kind="query"
    type="Tour"
    categories="Wandern,Radtouren"
    sort="title"
    limit="24"
    map-cluster="true"
    viewport-fit-bounds="true"
    geometry-on-pin-click-tour="true"
    geometry-direction-arrows="true"
    density-points-enabled="true"
    interactions-initial-reload-on-move="false"
    ui-fullscreen="true"
    ui-marker-detail="true"
    ui-teaser-popup="true"
    ui-elevation-profile="true"
    ui-elevation-preview="true"
    ui-show-reload-on-move-toggle="true"
    link-target="_self"
  ></done-generic-map>
    source-kind="query"
    type="Tour"
    categories="Wandern,Radtouren"
    sort="title"
    limit="24"
    map-cluster="true"
    viewport-fit-bounds="true"
    geometry-on-pin-click-tour="true"
    geometry-direction-arrows="true"
    density-points-enabled="true"
    interactions-initial-reload-on-move="false"
    ui-fullscreen="true"
    ui-marker-detail="true"
    ui-teaser-popup="true"
    ui-elevation-profile="true"
    ui-elevation-preview="true"
    ui-show-reload-on-move-toggle="true"
    link-target="_self"
  ></done-generic-map>
</div>

<style>
  .tour-map {
    width: 100%;
    height: min(700px, 80vh);
  }
</style>

Komplexe Konfigurationen können alternativ als JSON über source-json und options-json übergeben werden. Für dynamische Daten sind echte JavaScript-Objekte besser geeignet.

JavaScript-Beispiel mit Objekt-Properties

Die Properties source und options übernehmen echte Objekte. Das Element wird zuerst in das DOM eingefügt, damit der Lazy Loader die Web Component registriert. Anschließend wartet der Code auf die Definition und setzt die Properties:

<div id="map-host">
  <done-generic-map id="map"></done-generic-map>
</div>

<style>
  #map-host {
    width: 100%;
    height: 600px;
  }
</style>

<script type="module">
  await customElements.whenDefined('done-generic-map');

  const map = document.querySelector('#map');

  map.source = {
    kind: 'query',
    searchParameters: {
      type: 'Tour',
      category: 'Wandern',
      limit: 24,
      sort: 'title',
      cause: 'newpages.portal',
    },
  };

  map.options = {
    map: {
      cluster: true,
      overlap: {
        enabled: true,
        zoomThreshold: 14,
        offsetMeters: 8,
      },
    },
    viewport: {
      initial: { mode: 'items' },
      fitBounds: true,
      fitOnItemsChange: true,
    },
    geometry: {
      onPinClick: {
        tour: true,
        area: true,
      },
      directionArrows: true,
    },
    densityPoints: {
      enabled: true,
    },
    ui: {
      fullscreen: true,
      markerDetail: true,
      teaserPopup: true,
      elevationProfile: true,
      elevationPreview: true,
      linkTarget: '_self',
    },
  };

  map.addEventListener('marker-click', (event) => {
    const payload = event.detail[0];
    console.log('Marker ausgewählt:', payload.item);
  });

  map.addEventListener('update:fullscreen', (event) => {
    console.log('Fullscreen:', event.detail[0]);
  });
</script>

Bei einer dynamischen Änderung wird der Property ein neues Objekt zugewiesen. Das direkte Mutieren eines tief verschachtelten Feldes ist von außen nicht zuverlässig beobachtbar:

map.options = {
  ...map.options,
  ui: {
    ...map.options.ui,
    markerDetail: false,
  },
};

Konfigurationspriorität

Wenn dieselbe Option mehrfach gesetzt ist, gilt folgende Priorität:

1. JavaScript-Property options
2. flache HTML-Attribute
3. options-json
4. interne Standardwerte

Für die Quelle gilt: source vor source-json vor den flachen Source-Attributen.

Events

Vue Custom Elements geben die Argumente eines Events als Array in CustomEvent.detail aus. Bei den folgenden Events liegt die Nutzlast daher jeweils in event.detail[0].

Die Zustände fullscreen, active-categories und selected-item sind kontrollierbar. Wenn der Host einen solchen Wert dauerhaft als Attribut oder Property setzt, muss er auf das zugehörige update:*-Event reagieren und den Wert aktualisieren, damit Benutzeränderungen bestehen bleiben.