Quickstart

Diese Seite führt vom leeren dashlet.js zu einem laufenden Dashlet, das im Webclient, im Rich Client und im Standalone gleiches Verhalten zeigt. Was jede Umgebung konkret tut und wie die Bibliothek entscheidet: Umgebungen und Erkennung.

1. Installation

Machen Sie das Paket für Ihren Dashlet-Bau verfügbar:

npm install ecmind-blue-dashlet

(oder ein lokaler Pfad ins Repository, wenn Sie gegen die Quellversion bauen). Das Paket ist framework-unabhängig mit null Laufzeit-Abhängigkeiten; es bringt dualen ESM- und CJS-Output mit, funktioniert also unverändert aus vanilla JS, React, Angular oder jeder anderen Umgebung.

2. Die eine Regel

installDashletGlobal(options) zuerst aufrufen, auf Top-Level im Dashlet-Skript, vor allem, was verzögert werden könnte. Der Rich Client feuert seinen ersten window.osDashletInit-Aufruf ohne zu warten auf load; die Bibliothek installiert ihren Globalen daher synchron zur Import-Zeit und puffert jeden Host-Aufruf, der vor dem Aufruf von installDashletGlobal eintrifft.

3. Das minimale Dashlet

// dashlet.js — die Dashlet-Seite
import { installDashletGlobal } from 'ecmind-blue-dashlet';

// ERSTES. Top-Level. Vor jeglichem Framework-Setup, UI-Importen usw.
const dashlet = installDashletGlobal();

dashlet.init.then((ctx) => {
    // ctx ist der normalisierte InitContext in jeder Umgebung:
    //   ctx.environment: 'webclient' | 'richClient' | 'standalone'
    //   ctx.clientVersion, ctx.language, ctx.session, ctx.user,
    //   ctx.selection (SelectedEntry[]), ctx.lastSelectedEntry, ctx.location, ctx.raw
    render(ctx);
});

dashlet.onUpdate((ctx) => {
    // spätere Auswahl-/Kontext-Änderungen (Webclient onUpdate, Rich-Client-Callbacks)
    rerender(ctx);
});

Keine Optionen nötig — das ist der Standard. Im Webclient läuft der Wire im Lernmodus: Er verankert die Host-Origin aus dem ersten akzeptierten onInit (siehe Origin-Konfiguration). Wenn Sie die Origin bereits kennen, übergeben Sie expectedOrigin für den strengen Modus.

4. Was das init-Promise garantiert

  • init löst sich genau einmal auf und wird niemals abgelehnt — auch der Standalone-Degradationszustand ist ein beobachtbarer Fallback, kein Fehler. Siehe Standalone-Betrieb.

  • Es ist begrenzt durch die konfigurierten Timeouts (DashletOptions), so dass das Dashlet nie hängt.

  • In jeder Umgebung löst es sich in denselben normalisierten InitContext auf; die Umgebung ändert nur, welcher Wire aktiv ist, nicht die Form, die Ihr Code erhält.

5. Ihre ersten Host-Aufrufe

const dashlet = installDashletGlobal();
await dashlet.init;

await dashlet.openIndexData({ inNewTab: false, mode: 'view', objectId: '1024' });
await dashlet.getSelectedObjects(); // [{ objectId: 1024, objectTypeId: 262145 }, …]

Die sieben portablen Methoden laufen über dieselbe Dispatch-Tabelle wie call(method, params), so dass die typisierte Fassade und der Zeichenketten-Aufruf nicht divergieren können. Ein Webclient-Sonderfall, den man vor dem Aufruf von openHitListByIds kennen sollte: außer bei inNewTab === true trägt der Post kein msgId und löst sofort auf — der Host öffnet die Hit-Liste im aktuellen Tab, was das Dashlet-iframe zerstört, bevor eine Antwort eintreffen könnte. Im Standalone werden alle Fassade-Methoden mit dem begrenzten TimeoutError abgelehnt — zeigen Sie einen Fallback, statt zu warten.

6. Weiterführende Seiten