getWebclientApi()

dashlet.getWebclientApi() liefert den typisierten Zugriff auf die sieben Webclient-Endpunkte. Der Handle ist vollständig asynchron (die Wire ist ein asynchroner postMessage-Austausch): jede Methode liefert eine Promise. Beide Handle-Accessors (getWebclientApi / getRichClientApi) sind pro Umgebung verfügbar und schlagen hart fehl — eine fehlende Umgebung ist nie ein stiller null-Rückgang.

1. Signatur

const web: WebclientApi = dashlet.getWebclientApi();

Der Accessor ist gecacht: jeder wiederholte Aufruf liefert dieselbe Instanz (Identität per ===). Die Handle-Methoden lesen die Wire pro Aufruf — sie delegieren in denselben Dispatch-Kern wie die Fassade, sodass Wire-Posts, Normalisierung, Fire-and-forget-Verhalten, Korrelierung und Timeouts exakt identisch bleiben.

2. Endpunkte

Methode Wire-Post (Webclient) Auflösung

openIndexData(options)

openIndexData mit dem Array-Slot [inNewTab, mode, objectId, objectTypeId] (korreliert)

Host-Boolean-Ergebnis (`boolean

undefined`).

openObject(objectId)

openIndexData mit [false, 'view', objectId] (nur-lesend, korreliert)

Host-Boolean-Ergebnis (`boolean

undefined`).

openLocation(options)

openLocation mit dem 5-Slot-Array [inNewTab, objectId, objectTypeId, parentId, parentTypeId]

undefined (void, Host-Antwort abgewartet).

openHitListByIds(options)

openHitListByIds mit dem OBJEKT-Slot; inNewTab = false → Fire-and-forget (ohne msgId), true → korreliert

undefined; Fire-and-forget-Aufrufe lösen sofort auf.

refreshHitListObjects(ids)

refreshHitListObjects — das ID-Array als EIN Argument (korreliert)

Host-Boolean-Ergebnis (`boolean

undefined`).

getSelectedObjects()

getSelectedObjects mit leerem Parameter-Array (korreliert)

Normalisierte Auswahl-Einträge (SelectedObjectRef[]).

resetSessionTimeout()

resetSessionTimeout mit leerem Parameter-Array (korreliert)

undefined (void, Host-Antwort abgewartet).

Die parametrischen Formen und das exakte Verhalten pro Umgebung sind identisch zu den Fassaden-Methoden — siehe z. B. openIndexData() und openHitListByIds().

3. call() — der dokumentierte Escape-Hatch

web.call('myHostEndpoint', [1, 2]) postet einen beliebigen Host-Endpunktnamen auf der Wire als [method, params, { msgId }] — der Host validiert den Origin des einfallenden Aufrufs (eine andere Umgebung wird nie erreicht), die Antwort wird über das nicht erratbare msgId korreliert, und der Aufruf ist durch die konfigurierte Antwort-Timeout begrenzt. Die Promise löst sich mit der Host-Antwort auf, wird bei einem Host-{ error }-Payload oder bei fehlender Antwort (begrenztes TimeoutError) abgelehnt. Die katalogisierten Endpunkte (Tabelle oben) sind der bevorzugte Weg — call ist der dokumentierte Ausweichweg für nicht katalogisierte Endpunkte.

4. Anmerkungen

  • Kein has() — der Webclient-Host ist vom Dashlet aus nicht introspektierbar (es gibt keine lokalen Bridge-Mitglieder zum Sondieren); die Verfügbarkeit von Endpunkten ist eine Frage des Host-Setups, nicht eine der Bibliothek.

  • Nur asynchron — im Gegensatz zum getRichClientApi (synchron, rohe Bridge) läuft die Webclient-Wire asynchron; alle Methoden sind Promise-basiert.

  • Standalone — in der Standalone-Umgebung (kein Webclient-Host) ist der Accessor nicht verfügbar und wirft den Wrong-Environment-Fehler (siehe Fehler). Während des Erkennungsmodus (Umgebung noch nicht aufgelöst) wirft er stattdessen den Await-Init-Fehler (siehe Fehler).

5. Fehler

  • Error('dashlet destroyed') — das Dashlet wurde vor dem Aufruf zerstört (Accessor wie Handle-Methoden).

  • TypeError: Dashlet.getWebclientApi(): the environment is not resolved yet - await the dashlet.init promise first — der Aufruf erfolgte, bevor die Umgebung aufgelöst war.

  • TypeError: Dashlet.getWebclientApi(): the webclient API handle is only available in the webclient environment (current: …) — Aufruf in der falschen Umgebung (der aktuelle Wert wird genannt).

  • TimeoutError — begrenzte Fehlantwort im Standalone oder ein Host, der innerhalb von timeoutMs nicht geantwortet hat.

  • Das Host-{ error }-Payload — wenn der Host einen Fehler bei einem Methodenaufruf meldet.