getBrowserEnvironment()

rich.getBrowserEnvironment() reads the browser-environment object of the rich client synchronously from the bridge member osjxGetBrowserEnvironment(). It is a method of the rich-client handle — the handle is obtained once via dashlet.getRichClientApi() and its methods read the bridge per call (lazily, no snapshot).

1. Signature

getBrowserEnvironment(): unknown;

2. Parameters

None — the method is parameterless.

3. Behavior

The bridge member osjxGetBrowserEnvironment() is invoked synchronously, per call without arguments — the bridge is read lazily at call time (a bridge state that is injected or swapped later is visible immediately; no snapshot is kept).

The raw value is returned verbatim as unknown: the method neither validates nor normalizes anything — the caller narrows the shape to the expected form (the test simulation provides e.g. the window-size object { windowWidth: 1920 }).

The null semantics: an absent or non-function bridge member yields null, and a throwing call yields null as well (the read is throw-safe). Important: the reduced COM-OpenBrowser bridge (only osjxGetBrowserEnvironment + osjxSetBrowserCaption, without the dashlet marker member osjxGetSelectedObjects) carries this member — there, null can only mean a throwing call.

In contrast, the portable facade has no browser-environment method — the browser-environment object is exclusively reachable through the rich-client handle.

4. Examples

const env = rich.getBrowserEnvironment(); // the raw object (unknown) or null

5. Errors

Bridge problems never surface as a throw from getBrowserEnvironment — the method itself is throw-safe: the read path yields null instead (absent or non-function member, throwing call). The hard errors listed here come from the handle accessor dashlet.getRichClientApi():

  • Error('dashlet destroyed') — the dashlet was destroyed (accessor and handle methods).

  • TypeError: Dashlet.getRichClientApi(): the environment is not resolved yet - await the dashlet.init promise first — the accessor was called before the environment was resolved.

  • TypeError: Dashlet.getRichClientApi(): the rich client API handle is only available in the richClient environment (current: …) — the accessor was called in the wrong environment (the current value is named).