Addon

Mittels Addons kann der Webclient um (projektspezifische) Funktionen erweitert werden, die nicht in den Nuclos-Kern aufgenommen werden können oder sollen.

Daraus ergeben sich zusätzlich folgende Vorteile:

• schlankerer Webclient, bessere Performance
• Addons können leicht entfernt werden, falls die Funktion nicht mehr verwendet wird und hinterlassen keinen Legacy-Code
• genau definierte Schnittstellen innerhalb des Webclients fördern die Modularität
• ermöglicht das Erstellen von Erweiterungen, die nur von Auftraggeber genutzt werden sollen
• möglicher Einsatz von nicht Opensource-Libraries, die aus Lizenz-technischen Gründen nicht im Nuclos-Kern eingesetzt werden könnten

Einsatzgebiete

Das Haupteinsatzgebiet der Addons wird die Erweiterung des Webclients um neue GUI-Komponenten sein.
So können neue Addon-Komponenten implementiert werden, die im Layout einer Detailmaske verwendet werden (Layout-Addon).
Weitere Möglichkeiten wären z.B. der Einsatz von Addons im Dashboard oder der Ergebnisliste.

Des weiteren ist es möglich über Addons (versteckte) Hintergrundfunktionen (ähnlich Groovy Regeln für berechnete Attribute im Java-Client) zu realisieren. Diese Addons wären nicht sichtbar, könnten aber z.B. auf Benutzerinteraktionen reagieren und bestimmte Ereignisse auslösen.

Addons bieten die Möglichkeit über eine definierte API auf unterschiedlichste Daten und Funktionen im Webclient zuzugreifen.
Ein Layout-Addon ist z.B. nicht auf die Attribute des geöffneten Datensatzes beschränkt, sondern kann beispielsweise Subform-Daten laden oder auf beliebige andere REST-Service Aufrufe zurückgreifen.
Es greift die Standard-Berechtigungsprüfung des REST-Service.

Einrichtung

Damit ein Addon mehrfach bzw. an unterschiedlichen Stellen in ein Nuclet integriert werden kann, benötigt das Addon in den meisten Fällen Informationen über die Datenstruktur des Nuclets, um z.B. auf Attribute eines Businessobjekts zugreifen zu können.
Diese und weitere Informationen werden je nach Addon-Art z.B. über die Addon-Eigenschaften im Layouteditor, oder in der Konfigurationsmaske des Addons konfiguriert.

Auslieferung

Der Addon-Quelltext ist im Nuclet enthalten und kann somit zusammen mit der Addon-Konfiguration über ein Nuclet ausgeliefert werden.

Systemvoraussetzung

Zusätzlich zu Java benötigt der Server ein installiertes Node.js.

Buildprozess

Die Addon-Sourcen werden im Dateisystem unter NUCLOS_HOME/data/webaddons abgelegt.
Der Webclient wird zusammen mit den Addons neu gebaut und ausgetauscht.

Addon-Entwicklung

Ein Addon kann als eigenständiges Angular Modul in einer IDE bearbeitet werden um z.B. auf Code-Completion, Refactoring, usw. zurückgreifen zu können.

Beim Starten des Nuclos-Servers bzw. beim Nuclet-Import werden dazu die Addon-Dateien in das Dateisystem geschrieben (sh. Buildprozess).
Über den Button "Dateien synchronisieren" in der Addon-Konfigurationsmaske werden die Dateiänderungen zurück in Nuclos eingelesen.

API

Der Zugriff auf Webclient-Funktionalitäten aus dem Addon heraus muss über eine API stattfinden.

Allgemein:

• Attribute des aktuellen Datensatzes lesen/schreiben
• registrieren von Event-Listener auf Webclient-Events
• Datensatzänderung (TODO gezielt für bestimmte Attribute ermöglichen)
• Speichern
• Löschen
• Erstellen
• Datensatzauswahl
• Preferences
• Nucletparameter (TODO)

ResultList:

• Zugriff auf Addon-Einstellungen am Businessobjekt

Layout:

• Zugriff auf Addon-Einstellungen aus dem Layout-Editor

Beispiel OpenStreetMap Addon (In Entwicklung)

Ein Layout-Addon welches in diesem speziellen Fall einen Zuständigkeitsbereich (Bild 1) eines Vertragspartners definiert und für einen bestimmten Punkt die möglichen Vertragspartner findet (Bild 2). Für die Suche wird die PostgreSQL Extension PostGIS benötigt.

Die Entwicklung des Addons erfolgt komfortabel in einer IDE. Im gezeigten Screenshot sind schon Zugriffe über die API zu sehen:

this.dependenceKey = this.layoutContext.getAdvancedProperty('dependenceKey');

this.layoutContext.onEoSave().subscribe(...)

this.eo.getDependents(this.dependenceKey!)...

Addon Entwicklung

Der Webclient unterstüzt folgende Addon Typen:

• Layout Addon Component

• Resultlist Addon Component

Mögliche zukünftige Addon Typen:

• Dashboard Addon Component

Layout Addon Komponente

Die Layout Addon Komponente wird über den Layouteditor hinzugefügt und konfiguriert.

Innerhalb der Layout Addon Komponente bietet der [LayoutContext](classes/LayoutContext.html) Zugriff auf die Webclient API.

@Inject(LAYOUT_CONTEXT) private layoutContext: LayoutContext

Addon Konfiguration

Die Addon Konfiguration, die über den Layouteditor vorgenommen wird kann so über den layoutContext gelesen werden:

this.layoutContext.getAddonProperty('someProperty')

Resultlist Addon Komponente

Eine Resultlist Komponente muss einer bestimmten Position innerhalb des Webclient zugewiesen werden.

Addon Position

Folgende Positionen stehen derzeit zur Auswahl:

• menu-bottom

• content-top

• content-bottom

• content-left

• content-right

• ( detail-toolbar)

Die Resultlist Addon Komponente wird im Webclient durch die AddonExecutorComponent Komponente instanziiert.

<nuc-addon-executor [addonPosition]="'content-top'"></nuc-addon-executor> 

Innerhalb der Resultlist Addon Komponente bietet der [ResultlistContext](classes/ResultlistContext.html) Zugriff auf die Webclient API.

 @Inject(RESULTLIST_CONTEXT) private resultlistContext: ResultlistContext

Addon Konfiguration

Über die Addon Konfiguration können Parameter definiert werden, die im Addon Kontext verfügbar sind.

Der Parameter muss zuerst in der Addon Konfiguration hinzgefügt werden, und kann dann für jedes BusinessObject einen eigenen Wert erhalten.

Die Addon Konfiguration, die über die Addon Konfiguration vorgenommen wird kann so über den resultlistContext gelesen werden:

this.resultlistContext.getAddonProperty('someProperty') 

Definition benötigter Attribute

Falls ein Resultlist Addon bestimmte BusinessObject Attribute voraussetzt, so können diese über den `RequiredResultlistAttributes` Decorator spezifiziert werden.

 @RequiredResultlistAttributes('name', 'customerNumber')

Alternativ können die benötigten Attribute über Addon Properties definiert werden.

 @RequiredResultlistAttributesViaAddonProperties('nameAttributeName', 'customerNumberAttributeName')

InputRequired Addon Komponente

Analog zur InputRequiredException unter Verwendung von InputDelegateSpecification in Java-Client-Extensions, besteht die Möglichkeit, individualisierte Dialoge mittels WebAddon in den Webclient zu integrieren.

final InputDelegateSpecification inputDelegateSpecification = new InputDelegateSpecification("CustomizedInputRequiredComponent");
Map<String, java.io.Serializable> data = new java.util.HashMap<>();	
data.put("prop1", "Abc");
data.put("prop2", "123");
inputDelegateSpecification.setData(data);
throw new InputRequiredException(inputDelegateSpecification);

Über den Exception-Aufruf aus der Regel heraus können Daten über eine Map zu übergeben werden, diese werden an das Addon weitergereicht.

//...
export class CustomizedInputRequiredComponent implements OnInit {
   @Input() specification: InputRequiredSepecification;
   eo: IEntityObject;

   constructor(private activeModal: NgbActiveModal,
            private addonContext: ResultlistContextImplementation
   ) {
         // this.addonContext.getEntityClassId();
   }

   ngOnInit() {
      let data = this.specification.data;
      // ...
   }

   ok(result: any) {
      this.activeModal.close(result);
   }

   cancel() {
      this.activeModal.dismiss();
   }
}

Abhängigkeiten zu 3rd Party Libraries

Package Namen und Version jeder zusätzlich benötigten Library müssen im Addon-eigenen package.json spezifiziert werden.

Installieren der Addon Abhängigkeiten:

npm run install-addon-deps

Addon Entwicklunsmodus

Der Addon Entwicklunsmodus kann benutzt werden um die zeitaufwändige Build-Zeit zu reduzieren.

Zum Aktivieren muss der System-Parameter WEBCLIENT_SRC_DIR_FOR_DEVMODE konfiguriert werden.
Dieser muss auf ein Webclient Source Verzeichnis verweisen.

Nach Aktivierung werden die Addon Module in WEBCLIENT_SRC_DIR_FOR_DEVMODE/src/addons/ erzeugt.
Der Build-Prozess wird nicht gestartet.
Stattdessen muss der Webclient Server über ng serve ... gestartet werden.