Entwicklerdokumentation

Highlights

Die Highlight-Karten einer Location mit renderHighlights zeigen – Bild, Titel, Text und optional ein Link – oder eigene Karten auf client.highlights bauen.

Dieselbe SDK-Datei, die das Buchungswidget rendert, zeigt auch die Highlight-Karten einer Location: die Bilder mit Titel und Kurztext, die die Location für ihre Website pflegt, jeweils mit einem optionalen Link auf ein Event, eine Speisekartenposition, ein Gutscheinangebot oder eine beliebige Seite. Zwei Wege hinein, beide auf derselben Highlights-API:

  • renderHighlights – ein Aufruf, ein responsives Raster aus Karten in einem Element Ihrer Wahl, stilisoliert wie das Buchungswidget.
  • Der Headless-Client – client.highlights() neben den Buchungs- und Eventaufrufen aus Eigene Formulare. Für eine Website, die schon ein eigenes Kartendesign hat und nur die Daten braucht.

Highlights stehen jedem Tarif offen, nichts davon hängt also vom Tarif der Location ab.

Installation

Laden Sie das SDK wie für das Buchungswidget (JavaScript-SDK) und fügen Sie ein Element für die Karten hinzu:

<div id="bookdineplay-highlights"></div>
<script src="https://cdn.bookdineplay.com/sdk/v1/bookdineplay.js"></script>

Das Highlights-Widget rendern

HTML

<script>
  window.BookDinePlay.renderHighlights({
    container: '#bookdineplay-highlights',
    venueSlug: 'your-venue',
    apiBaseUrl: 'https://api.bookdineplay.com',
    publishableKey: 'bdp_pk_your_publishable_key',
    eventUrl: '/events/{target}',
    menuItemUrl: '/speisekarte#item-{target}',
    locale: 'de',
    theme: 'auto'
  });
</script>

JavaScript

// Headless: eigenes Markup auf denselben Daten. Die Antwort ist null, wenn die Location unbekannt ist.
const client = window.BookDinePlay.createClient({
  apiBaseUrl: 'https://api.bookdineplay.com',
  venueSlug: 'your-venue',
  publishableKey: 'bdp_pk_your_publishable_key'
});
const response = await client.highlights();
for (const card of response?.highlights ?? []) {
  console.log(card.title, card.imageUrl, card.linkKind);
}

Der Aufruf gibt die Widget-Instanz zurück oder null, wenn er nicht gerendert hat (Wenn es nicht rendert). Die Instanz hat eine Methode, destroy(), die ihren Timer und eine laufende Anfrage beendet.

Optionen

Option Pflicht Bedeutung
container ja Ein CSS-Selektor oder ein DOM-Element. Das Widget rendert darin.
venueSlug ja Der Slug Ihrer Location.
apiBaseUrl ja https://api.bookdineplay.com. Nur bei einer privaten Installation anders.
publishableKey ja Der bdp_pk_…-Schlüssel der Location. Nie ein geheimer Schlüssel.
locale nein en (Standard) oder de: die eigenen Texte des Widgets. Jedes de-*-Tag zählt als de. language wird als Alias akzeptiert. Titel und Texte der Location kommen in der Sprache, in der die Location sie geschrieben hat.
theme nein auto (folgt der Systemeinstellung der Besucherin oder des Besuchers, Standard), light oder dark.
title nein Ersetzt die Überschrift „Highlights“. false blendet die Überschrift aus; die Kartentitel werden dann zu den Überschriften zweiter Ebene der Seite.
eventUrl nein Wohin eine Karte mit Link auf ein Event führt, zum Beispiel /events/{target}.
menuItemUrl nein Wohin eine Karte mit Link auf eine Speisekartenposition führt, zum Beispiel /speisekarte#item-{target}.
voucherUrl nein Wohin eine Karte mit Link auf ein Gutscheinangebot führt, zum Beispiel /gutscheine?angebot={target}.

Eine Karte mit einem External-Link braucht nichts von Ihnen: Die API liefert eine vollständige https-URL. Die anderen drei Arten nennen nur ihr Ziel – den Slug des Events, die ID der Position, die ID des Gutscheinangebots –, weil die API nicht wissen kann, wo Events, die Speisekarte oder der Gutscheinshop auf Ihrer Website liegen. Sagen Sie es dem Widget mit einer URL-Vorlage: {target} wird durch das Ziel ersetzt, URL-kodiert, sodass ein Slug nie aus der Adresse ausbrechen kann.

  • Eine Vorlage wird nur als absolute https-URL, als Pfad ab der Wurzel wie /events/{target} oder als #Fragment akzeptiert. Alles andere – javascript:, ein protokollrelatives //host/..., ein relatives events/{target} – wird ignoriert, und die Karte erscheint ohne Link.
  • Eine Karte einer Art, für die Sie keine Vorlage angegeben haben, erscheint ohne Link, nicht mit einem toten.
  • Auf einer Seite über reines http, etwa bei der lokalen Entwicklung, wird auch eine absolute http-Vorlage akzeptiert.

Eine Karte mit Link ist ein großes Touch-Ziel: Die ganze Karte ist der Anker, mit dem Titel als Überschrift und einem „Mehr erfahren“ als echtem Text, und sie zeigt Tastaturnutzern einen sichtbaren Fokusring. Ein Link auf eine fremde Seite trägt rel="noopener noreferrer". Der Text einer Karte wird immer als Text gesetzt, nie als Markup ausgewertet.

Was der Gast sieht

Jede Karte zeigt ihr Bild (wenn es ein brauchbares gibt), den Titel und den Text, in der Reihenfolge der API. Das Bild trägt ein leeres alt, weil der Titel die Karte schon benennt. Ein Bild wird nur gezeigt, wenn seine Adresse eine absolute https-URL ist, und eines, das nicht lädt, wird entfernt, statt ein kaputtes Bild-Kästchen zu hinterlassen.

Zeitzone und Aktualisierung

Welche Karten sichtbar sind, entscheidet der Server in der Zeitzone der Location, anhand des ersten und letzten Tages, den der Betreiber gesetzt hat. Das Widget fragt einmal beim Laden und prüft dann jede Minute den Kalendertag der Location, entnommen der timezone der Antwort, nie dem Browser der Besucherin oder des Besuchers. Wechselt der Tag der Location, fragt es erneut, sodass ein über Nacht offener Bildschirm von selbst auf die Karten des neuen Tages umspringt.

Eine fehlgeschlagene Anfrage leert das Widget nie. Die letzte Antwort bleibt stehen, und der nächste Minutentakt versucht es wieder, höchstens eine Anfrage pro Minute, mit einer Konsolenwarnung beim ersten Fehler.

Eine Instanz pro Container

Ein erneuter Aufruf von renderHighlights auf demselben Container ersetzt das erste Widget: Das frühere beendet seinen Timer und seine Anfrage und gibt den Container frei.

Nichts, wenn es leer ist

Eine Location ohne Highlights für heute bekommt gar kein Widget: keinen Rahmen, keine Überschrift, keinen Rand, nur Ihren leeren Container. Dasselbe gilt, solange die erste Anfrage noch lädt, wenn sie fehlgeschlagen ist und wenn die Antwort 404 ist. Geben Sie dem Container keine eigene Höhe oder einen Platzhalter, damit die Seite kein Loch zeigt.

Wenn es nicht rendert

renderHighlights gibt null zurück und schreibt eine Zeile in die Browserkonsole, ohne je in Ihre Seite zu werfen – dieselben drei Ablehnungen wie bei renderBookingWidget (Wenn es nicht rendert): Der Container wurde nicht gefunden, venueSlug oder apiBaseUrl fehlt, oder publishableKey fehlt oder ist kein bdp_pk_…-Schlüssel.

Theming

Das Highlights-Widget rendert im selben isolierten Root wie die anderen Widgets und liest dieselben neun --bdp-*-Custom-Properties von der Host-Seite: --bdp-accent für den Rahmen beim Überfahren und das „Mehr erfahren“, --bdp-surface für die Karten, --bdp-radius für ihre Ecken. Theming listet jede Property mit ihrem Standard; eine eigene Highlights-Property gibt es nicht.

Der Headless-Client

client.highlights({ signal }) ruft GET /api/venues/{venueSlug}/highlights mit dem veröffentlichbaren Schlüssel des Clients auf. Er liefert den Antwort-Body (slug, timezone und highlights[]) oder null bei einem 404, wo die anderen Lesezugriffe ablehnen. Jeder andere Fehler lehnt mit einem BookDinePlayError ab.

Nächste Schritte

  • Highlights-API – jedes Feld der Antwort und wie der Sichtbarkeitszeitraum funktioniert.
  • Theming – Farben, Radius und Schrift.
  • WordPress-Plugin – dasselbe Widget als [bookdineplay_highlights].
  • .NET-SDK – GetHighlightsAsync für serverseitigen Code.