Developer docs

Highlights

Show a venue's highlight cards with renderHighlights — image, title, text and an optional link — or build your own cards on client.highlights.

The same SDK file that renders the booking widget also shows a venue's highlight cards: the pictures with a title and a short text that the venue curates for its website, each optionally linking to an event, a menu item, a voucher offer or any page. Two ways in, both on the same Highlights API:

  • renderHighlights — one call, a responsive grid of cards inside an element you choose, style-isolated like the booking widget.
  • The headless client — client.highlights() next to the booking and event calls of Custom forms. Use it when the site already has its own card design and only needs the data.

Highlights are open to every plan, so nothing here depends on the venue's tier.

Install

Load the SDK as for the booking widget (JavaScript SDK) and add an element for the cards:

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

Render the highlights widget

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: '/menu#item-{target}',
    locale: 'en',
    theme: 'auto'
  });
</script>

JavaScript

// Headless: your own markup on the same data. The answer is null when the venue is unknown.
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);
}

The call returns the widget instance, or null when it refused to render (When it refuses to render). The instance has one method, destroy(), which stops its timer and any request in flight.

Options

Option Required Meaning
container yes A CSS selector or a DOM element. The widget renders inside it.
venueSlug yes Your venue's slug.
apiBaseUrl yes https://api.bookdineplay.com. Only different for a private deployment.
publishableKey yes The venue's bdp_pk_… key. Never a secret key.
locale no en (default) or de: the widget's own texts. Any de-* tag counts as de. language is accepted as an alias. The venue's titles and texts come in the language the venue wrote them in.
theme no auto (follow the visitor's system setting, default), light or dark.
title no Replaces the heading "Highlights". false hides the heading; the card titles then become the page's second-level headings.
eventUrl no Where a card that links to an event goes, for example /events/{target}.
menuItemUrl no Where a card that links to a menu item goes, for example /menu#item-{target}.
voucherUrl no Where a card that links to a voucher offer goes, for example /gift-vouchers?offer={target}.

A card with an External link needs nothing from you: the API hands over a complete https URL. The other three kinds only name their target — the event's slug, the menu item's id, the voucher offer's id — because the API cannot know where events, the menu or the voucher shop live on your site. Tell the widget with a URL template: {target} is replaced by the target, URL-encoded, so a slug can never break out of the address.

  • A template is accepted only as an absolute https URL, a root-relative path such as /events/{target}, or a #fragment. Anything else — javascript:, a protocol-relative //host/..., a relative events/{target} — is ignored, and the card is shown without a link.
  • A card of a kind you gave no template for is shown without a link, not with a dead one.
  • On a page served over plain http, as in local development, an absolute http template is accepted too.

A card with a link is one large touch target: the whole card is the anchor, with the title as its heading and a "Learn more" label as real text, and it shows a visible focus ring for keyboard users. An off-site link carries rel="noopener noreferrer". The text of a card is always set as text, never parsed as markup.

What the guest sees

Each card shows its picture (when it has a usable one), the title and the text, in the API's order. The picture carries an empty alt, because the title already names the card. A picture is shown only when its address is an absolute https URL, and one that fails to load is removed rather than left as a broken-image box.

Time zone and refresh

Which cards are visible is decided by the server in the venue's time zone, from the first and last day the operator set. The widget asks once on load, then once a minute checks the venue's calendar day, taken from the answer's timezone, never the visitor's browser. When the venue's day changes it asks again, so a screen left open overnight rolls over to the new day's cards on its own.

A failed request never blanks the widget. The last answer stays on screen and the next minute's tick tries again, at most one request a minute, with one console warning for the first failure.

One instance per container

Calling renderHighlights again on the same container replaces the first widget: the earlier one stops its timer and request and gives up the container.

Renders nothing when empty

A venue with no highlights today gets no widget at all: no frame, no heading, no border, only your empty container. The same holds while the first request is still loading, when it failed, and when the answer is 404. Give the container no height or placeholder of its own, so the page does not show a hole.

When it refuses to render

renderHighlights returns null and writes one line to the browser console, never throwing into your page — the same three refusals as renderBookingWidget (When it refuses to render): the container was not found, venueSlug or apiBaseUrl is missing, or publishableKey is missing or not a bdp_pk_… key.

Theming

The highlights widget renders in the same isolated root as the other widgets and reads the same nine --bdp-* custom properties from the host page: --bdp-accent for the hover border and the "Learn more" label, --bdp-surface for the cards, --bdp-radius for their corners. Theming lists every property with its default; there is no highlights-specific property.

The headless client

client.highlights({ signal }) calls GET /api/venues/{venueSlug}/highlights with the client's publishable key. It resolves the response body (slug, timezone and highlights[]), or null for a 404, where the other reads reject. Any other failure rejects with a BookDinePlayError.

Next steps

  • Highlights API — every field of the answer, and how the visibility range works.
  • Theming — colors, radius and font.
  • WordPress plugin — the same widget as [bookdineplay_highlights].
  • .NET SDK — GetHighlightsAsync for server-side code.