Widget loading

One asynchronous script and one custom element are all you add. From there the widget boots itself, pulls everything it needs from the Smartblock CDN, and tells you when it is ready. This section covers what happens, the order you must set things up in, and what it costs your page.

What you place on the page

Two things:

• The custom element, where the widget should appear:

  <koala-smartblock-sb4 data-config-name="your-slug"></koala-smartblock-sb4>

  data-config-name is your partner slug; it tells the widget which configuration to load.
• The loader script, included once and loaded asynchronously.

What happens on load

Once the loader runs, the widget:

1. Registers the custom element and boots.
2. Reads its data-config-name and fetches your versioned configuration and assets from the Smartblock CDN.
3. Waits for window.CTStore.koala (your data and the required namespace) to be present.
4. Prices the configured bundles for the trip (quoting).
5. Renders the priced options, firing onReady once it has loaded and onAvail once the prices are in.

You do not orchestrate any of this. You set things up, include the script, and listen for onReady and onAvail.

Ordering rules

The one thing you must get right is order:

• Create the custom element and initialize window.CTStore, including the koala namespace and your dataSource, before the loader script runs.
• The recommended order is: element and CTStore first, then inject the script.
• Never assign a new object to window.CTStore.koala once the loader has run. The loader creates the namespace if it is missing and writes the resolved partner, versions and restart helper into it; a later window.CTStore.koala = {...} wipes them and the widget cannot start. Add your handlers to the existing object instead. Handlers registered later are still called: the widget reads the arrays when it fires.

When it cannot load

The loader tells you at once, through onError, when it can see the load will not happen: the element has no data-config-name, the partner is not enabled for Koala, or no widget version can be resolved. Nothing is rendered in the element for these, so collapse the space you reserved. If the widget was fetched but did not render within the loader's watchdog (12 seconds, longer on slow connections), onError fires with KoalaError-100. If the loader script itself never runs (blocked, offline), no event can fire: keep your own timeout on onReady END for that case. The codes are listed in the reference page Events.

Footprint

• The loader is asynchronous and non-blocking: it does not hold up your page's render.
• Configuration and assets are served from the Smartblock CDN and cached, so repeat loads are fast.
• The widget inherits the available width from its container; you do not size it.

Restarting

If the trip data changes after load, for example the traveller edits their dates, you can re-initialize the widget by calling window.CTStore.koala.restart(). It re-reads dataSource, quotes again and renders again.

It does so by replacing the custom element with a fresh one that carries the same attributes. Any reference you kept to the old element, and any listener or property you set on it, is gone: query the element again after a restart.

Single-page applications

The guides describe one page load. In an application that navigates without reloading:

• Leaving the page: remove the custom element (your framework's unmount does it). Keep window.CTStore if the traveller may come back to the offer during the same visit: the basket it holds is restored as is, and your handlers stay registered. Delete it to start from a clean state on the next placement.
• Coming back: render the element again, set dataSource for the new trip, and call restart() if the widget is already loaded, or inject the loader again if it is not. Injecting the loader twice is tolerated: it removes its earlier script tag and registers the element only once.
• Several placements in one visit: each placement has its own context in dataSource.custom.context, and a selection kept in the browser never carries over from one placement to another.