Business App Leitfaden für Anpassungen

7.3. UI Events

BA bietet mit dem EventManager eine einfache Möglichkeit für Projekte im Browser Ereignisse aller Art auszulösen und darauf zu reagieren. Von dem Basissystem werden eine Reihe von Standardevents automatisiert ausgelöst, die entsprechend verwendet werden können.

Standard-Events

Für die Standard-Event-Typen stehen clientseitig Konstanten in der Klasse BA.Ui.Event.StandardEventTypes zur Verfügung.

Die zur Verfügung stehenden Events sind:

  • FieldUpdate reserviert, bitte über die im nachfolgenden beschriebenen API “Feldänderung eines Datensatzes” nutzen
  • TabOpening Wird gefeuert, wenn ein Tab geöffnet werden soll. Der Rückgabewert der Handler entscheidet, ob der Tab dann tatsächlich geöffnet wird.
  • TabOpened Wird gefeuert, nachdem ein Tab geöffnet und dessen Inhalt vollständig geladen wurde.
  • TabActivated Wird gefeuert, wenn der aktuelle Tab in der Ui gewechselt wurde.
  • TabClosing Wird gefeuert, wenn ein Tab geschlossen werden soll. Der Rückgabewert der Handler entscheidet, ob der Tab dann tatsächlich geschlossen wird.
  • TabClosed Wird gefeuert, wenn ein Tag final geschlossen wurde.
  • RecordSaving Wird gefeuert, wenn ein Datensatz gespeichert werden soll. Der Rückgabewert der Handler entscheidet, ob der Datensatz dann tatsächlich gespeichert wird.
  • RecordSaved Wird gefeuert, wenn ein Datensatz erfolgreich gespeichert wurde.
  • RefreshGrids Wird gefeuert, wenn die Menübandaktion “Ansichten aktualisieren” betätigt wird.

Alle Tab-Events bekommen in den Daten das betreffende Tab-Objekt unter dem Schlüssel Tab geliefert.
Ausnahme hiervon ist TabOpening, weil zum Aufrufzeitpunkt noch kein Tab-Objekt existiert; dieser Event bekommt alle Kontextinformationen geliefert, die in der Funktion OpenTab zur Vefügung stehen:

let eventData: CustomData = {
	url: baseUrl + tmpUrl,
	willActivate: tmpUrlLwr.indexOf("andredirect") < 0,
	overrideTabReference: overrideTabReference,
	asLastVisibleTab: asLastVisibleTab,
	isUniqueTab: isUniqueTab,
	predecessor: predecessor,
};

Alle Save-Events bekommen die Oid des betreffenden Datensatzes unter dem Schlüssel Oid und den Orm-Typen unter OrmType geliefert.

let eventData: CustomData = {
	Oid: oid,
	OrmType: ormType,
};

Einfaches Beispiel (in der Browser-Konsole nachstellbar):

BA.Ui.Event.EventManager.AddEventHandler(BA.Ui.Event.StandardEventTypes.TabOpening, "myHandlerUniqueId", (data) => { console.log(data); return true; }, null);

"myHandlerUniqueId" entspricht einer eindeutigen Id des eigenen Event-Handlers. Kann beispielsweise bei der Deregistrierung verwendet werden. Genauere API Beschreibung folgt.

Öffentliche API / Eigene Events

Auf der TypeScript-Klasse BA.Ui.Event.EventManager stehen folgende Funktionen zur öffentlichen Verwendung zur Verfügung:

public static AddEventHandler(type: string, id: string, handler: Function(data: CustomData), scope: string = null): void

Die Funktion prüft zunächst, ob bereits ein Handler mit derselben Id registriert ist und entfernt diesen, falls dies der Fall ist.
Das heißt im Umkehrschluss, dass immer nur ein Handler mit derselben Id registriert sein kann. Dies gilt für die gesamte Applikation, die in einem Browser-Fenster geöffnet ist.

Die Handler-Funktion ist eine Funktion mit einem Parameter des Typs CustomData, welcher ereignisspezifische Daten beinhaltet, welche beim Triggern des entsprechenden Events übergeben werden können. Die Handler-Funktion wird automatisch in dem Fensterkontext (iFrame) ausgeführt, aus welchem heraus sie registriert wird.
Der Parameter scope dient zur Beschränkung der Grültigkeit eines Events beispielsweise auf den aktuellen Tab.
Hierfür kann die Gültigkeit eines Events z.B. auf die Id des aktuellen Tabs eingeschränkt werden. Diese Einschränkung sollte dann bei TriggerEvent ebenfalls mit berücksichtigt werden.

public static RemoveEventHandler(id: string): boolean

Diese Funktion deregistriert den konkreten Event-Handler mit der gegebenen Id und gibt true zurück, sollte dies gelungen sein.
Wenn unter der gegebenen Id keine Handler-Funktion registriert ist, gibt die Funktion entsprechend false zurück.
Es ist nicht zwingend notwendig, alle Handler innerhalb eines Tabs zu deregistrieren, wenn der Tab geschlossen wird; dies erfolgt automatisch.

Sollten Ereignisse im Kontext von Dialogen angemeldet worden sein, so müssen diese beim Schließen des Dialogs vom Entwickler deregistriert werden.

public static TriggerEvent(type: string, scope: string = null, data: CustomData = null): boolean

Diese Funktion führt zum Aufruf aller Event-Handler, welche für den gegebenen Typen und den gegebenen Gültigkeitsbereich scope registriert sind.
Die Reihenfolge, in der die Handler-Funktionen ausgeführt werden, ist undefiniert.
Der Rückgabewert dieser Funktion ist true solange alle Handler-Funktionen true zurückgeben. Gibt nur eine der Handler-Funktionen false zurück, ist der Rückgabewert hier auch false.

Alle Handler-Funktionen bekommen dasselbe Datenobjekt data übergeben.

Beispiel

Einfaches Beispiel welches in der Browser-Konsole nachstellbar ist.

Schritt 1: Registrieren zweier Event-Funktionen für einen eigenen Event-Typen mit unterschiedlichen Geltungsbereichen

BA.Ui.Event.EventManager.AddEventHandler("MyEventType", "myUniqueId-1", (data) => { console.log(data); return true; }, top.tabController.ActiveTab.Guid);
BA.Ui.Event.EventManager.AddEventHandler("MyEventType", "myUniqueId-2", (data) => { console.log(data); return true; }, "ownScope");

Schritt 2.1: Triggern eines konkreten Events

BA.Ui.Event.EventManager.TriggerEvent("MyEventType", "ownScope", {mydata: "Event was triggered!"});

Es wird nur der Event-Handler ausgeführt, der unter dem angegebenen Geltungsbereich registriert wurde.

Schritt 2.2: Triggern aller Events

BA.Ui.Event.EventManager.TriggerEvent("MyEventType", null, {mydata: "Event was triggered!"});

Weil der angegebene Geltungsbereich null ist, werden BEIDE Event-Handler ausgeführt.

Schritt 3: Deregistrieren der Event-Handlers

BA.Ui.Event.EventManager.RemoveEventHandler("myUniqueId-1")
BA.Ui.Event.EventManager.RemoveEventHandler("myUniqueId-2")

Eigene Events auswählbar in der Konfiguration

Die Applikation beinhaltet eine Auswahlliste, in welcher alle Event-Typen, die unterstützt werden, hinterlegt sind. Diese Liste heißt BA.Core.Enums.EnumUiEventType.
Die hier beinhalteten Werte dienen der Auswahl von Events in entsprechenden Steuerelementen und generell nur zur serverseitigen Verwendung.

Die Enum-Werte selbst besitzen eine Eigenschaft, die besagt, ob sie in der UI auswählbar sein sollen, und den Typ-String, welcher in der Ui als Event-Typ verwendet wird.

Dieser darf nicht doppelt vorkommen. Eine Überprüfung findet aber nicht statt. Bei Erweiterung der Auswahlliste sollten daher passende Prä- oder Postfixes verwendet werden und sollten nur aus Buchstaben bestehen.

Feldänderung eines Datensatzes

Die EventManager Klasse bietet eine spezielle API für die Änderung der Felder. Soll auf Feldänderungen reagiert werden oder wird ein eigenes Maskensteuerlement implementiert, muss diese API verwendet werden.

public static AddFieldUpdateHandler(fieldName: string, handler: Function(data: UpdateFieldEventData), scope: string): string

Diese Funktion registriert einen Event-Handler, der bei einer Wertänderung des gegebenen Feldes in der Ui automatisch getriggert wird. Sie gibt eine generierte Id zurück, welche zusammen mit RemoveFieldUpdateHandler verwendet werden kann, um den Handler zu deregistrieren.

Die übergebenen Daten der Klasse UpdateFieldEventData beinhalten folgende Werte:

  • Type: string Typ des gefeuerten Events (üblicherweise in diesem Fall "FieldUpdate")
  • FieldName: string Name des geänderten Feldes (abstrahierter Feldname, ggf mit Teildatensatzbezeichner "Addresses.PostalCode" aber ohne Dialog-Prefix und ohne Teildatensatzindex)
  • Context: Window Kontext der Handler-Funktion
  • Scope: string Gültigkeitsbereich des Event-Handlers
  • FullFieldName: string Voller Name des geänderten Feldes (mit Index bei Änderung eines Feldes auf einem Teildatensatz "Addresses[0].PostalCode" oder mit Dialog-Prefix in Dialogen "DLG1.Addresses[0].PostalCode")
  • AdditionalData: CustomData zusätzliche Informationen (im Standard leer)
public static RemoveFieldUpdateHandler(fieldName: string, scope: string, id: string = null): boolean

Deregistriert einen konkreten Handler unter Ferwendung des zugehörigen Feldnamens und der von AddFieldUpdateHandler zurückgelieferten Id.

public static TriggerFieldUpdated(fieldName: string, scope: string, fullFieldName: string = null, additionalData: CustomData = null): boolean

Triggert alle Feldaktualisierungs-Handler für ein bestimmtes Feld. Diese Funktion wird im Standard automatisch bei allen Änderungen von editierbaren Feldern aufgerufen.