Sign in to see your venue's slug and publishable key in every sample.
Your account has no venue yet, so the samples keep their placeholders. Sign out
Signed in as · . Create a publishable key in the console and reload to see it here. Sign out
Signed in as · . The samples show your venue's publishable key. Sign out
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}. |
Links
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
httpsURL, a root-relative path such as/events/{target}, or a#fragment. Anything else —javascript:, a protocol-relative//host/..., a relativeevents/{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 absolutehttptemplate 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 —
GetHighlightsAsyncfor server-side code.