Events and basket state

The widget keeps your page informed through events. You register callbacks, the widget calls them as things happen, and you use them to keep your own UI in sync (for example a running total or an order summary). It also writes the current basket to a shared place for you to read.

The events surface

Koala events live on window.CTStore.koala.events. Each event listener is an array of callbacks, and each callback receives (status, data). Register them before the loader script runs, as part of the koala namespace (whose presence is also the readiness signal, see Widget loading).

There are five events; when each fires and the data each carries are documented in the reference page Events.

Registering handlers

Register every handler on window.CTStore.koala.events:

window.CTStore = {
  dataSource: {
    /* ... */
  },
  koala: {
    events: {
      onReady: [(status) => {}],
      onAvail: [(status, data) => {}],
      onBundle: [(status, data) => {}],
      onBasket: [(status, data) => {}],
      onError: [(status, data) => console.error(data.message)],
    },
  },
};

When nothing will render

onAvail SUCCESS carries a count of the priced bundles the widget will render. When it is 0, the quote succeeded but no bundle is sellable for this trip (the rejection reasons are in response.data.quotes), and the widget renders nothing. Treat that the same way as a quote failure and collapse any space your page reserved:

window.CTStore.koala.events.onAvail = [
  (status, data) => {
    if (status === 'ERROR' || data.count === 0) {
      hideProtectionSection(); // your own function
    }
  },
];

On koala.events, the onBasket data is the Koala basket itself (read it directly):

window.CTStore.koala.events.onBasket = [
  (status, data) => {
    const { selectedBundles, declinedBundles } = data;
    updateOrderSummary(selectedBundles); // your own function
  },
];

note

On pages that also run the CarTrawler car-rental Smartblock, the basket change is additionally mirrored on the shared window.CTStore.events bus, under a koala key. How the two event surfaces coexist is covered in Alongside the car-rental Smartblock.

Basket state on window.CTStore.koala

Alongside the onBasket event, the widget writes the latest basket to window.CTStore.koala.basketPayload, so you can read the current state at any time without waiting for an event. Its shape is documented in the reference page Events. Its book property is what your application sends after the booking to create the subscription or delete the quote (see Creating the subscription).

This state also persists across reloads: if window.CTStore.koala.basketPayload is still present when the widget next loads, it restores the traveller's previous selection rather than starting empty.