installDashletGlobal()

The library entry point. Call it first, at the top level of the dashlet script, before anything that could be deferred.

1. Signature

import { installDashletGlobal } from 'ecmind-blue-dashlet';

const dashlet = installDashletGlobal(options); // options is optional
// dashlet: Dashlet — the instance handle (page: Dashlet)

Call installDashletGlobal(options) first, at the top level of the dashlet script, before anything that could be deferred. The rich client fires its first window.osDashletInit call without waiting for load; importing the package already self-registers the global and buffers every host call that arrives before this call runs, so nothing is missed — but the wire and the detection start only when this call executes.

2. What it does

Synchronously, before returning:

  • installs window.osDashletInit — a stable per-window dispatcher; the install is atomic and idempotent, and host calls arriving before the dashlet is configured are buffered (bounded, in arrival order) and flushed when the dashlet goes live — never dropped;

  • attaches the single buffering message listener (idempotent per window);

  • starts the webclient wire when the origin decision allows it: a usable configured expectedOrigin gives strict mode, an omitted origin inside an iframe gives learning mode, and a top-level window without a configured origin gets no wire (see Origin configuration);

  • goes live and flushes the buffered host calls and messages.

Asynchronously:

  • rich-client detection runs — an immediate throw-safe probe plus polling (Environments and detection); the state machine settles to exactly one of the three states;

  • the detection wait is bounded by detectionTimeoutMs plus a 250 ms safety net; a timeout settles the dashlet as standalone.

3. Parameters

Name Type Description

options (optional)

DashletOptions

The configuration object — see DashletOptions for the field-by-field reference. All fields are optional; options.window defaults to the current global window (inject it in unit tests).

Behavior:

  • Idempotent registration: re-calling installs the same stable dispatcher. A later call on the same window takes over the shared sink (last configuration wins) — the previous instance’s wire simply stops receiving host events.

  • With no usable window object, or with expectedOrigin === "*", the call throws a TypeError at install time (see Errors).

4. Examples

import { installDashletGlobal } from 'ecmind-blue-dashlet';

// FIRST. Top level.
const dashlet = installDashletGlobal({ expectedOrigin: 'https://enaio.example.com' });

await dashlet.init; // the normalized init context

See Quickstart for the complete minimal dashlet.

5. Errors

  • TypeError('installDashletGlobal: no usable window object available') — no options.window and no usable global (for example, Node without a window).

  • TypeError('installDashletGlobal: expectedOrigin must never be "*"') — the wildcard origin is rejected at install time, not at post time.