Custom Control

Die CustomControl Komponente kann verwendet werden, um beliebige Elemente innerhalb eines iFrames anzuzeigen. Sofern für eine GUI-Anforderung kein fertiges GUI-Control existiert, kann mit diesem Control eine individuelle Komponente mit Hilfe von HTML/CSS/JS aufgebaut werden.

Bei der Erstellung eines CustomControls sind folgende Punkte zu beachten:

In der package[.install].yaml wird unter objects.customControls eine Liste mit custom Definitionen eingeführt.
Im Ordner .objects.customControls wird ein neuer Ordner mit dem Namen des CustomControls erstellt. In diesem können dann die html, js und css Dateien hinterlegt werden.
Soll eine externe Seite als iFrame eingebunden werden, so muss lediglich in der custom Definition die URL angegeben werden.

Name des ControlType: custom

Eigenschaften von custom in der package[.install].yaml

name	Name des CustomControls. Dieser muss dem Ordnernamen in `.objects.customControls` entsprechen.
description?	(optional) - Beschreibung der Komponente
url?	(optional) - Standardmäßig wird auf die `index.html` des CustomControls verwiesen. Mit `/xyz.html` kann auf eine andere Startseite verwiesen werden. Bei einem externen CustomControl ist die Angabe der vollständigen URL notwendig.
source?	Beschreibt die Quelle eines CustomControls. Es wird ein Source-Objekt mit folgenden Parametern erstellt: `package`
source.package?	Enthält weitere Angaben zum Package des CustomControls. Es wird ein Package-Objekt mit folgenden Parametern erzeugt: `name` (Name des CustomControls im Format “@packageKey/custom-control-name”) `version` (Version des CustomControls im Format “Major.Minor.Bugfix-Beschreibung”

Beispiel:

YAML

customControls:
  - name: demoCustomControl
    description: CustomControl mit Kommunikation zwischen Page und iFrame
  - name: demoCustomControlZwei
    description: Zweites CustomControl als Beispiel im Anwendungsframework
    source:
      package:
        name: "@demo/demo-custom-control-zwei"
        version: "1.0.0-demo"

Eigenschaften von customControl in der page

name	Name des CustomControls. Dieser muss dem Ordnernamen in `.objects.customControls` entsprechen.
id	ID des CustomControls. Wird für die Kommunikation zwischen Page und iFrame benötigt. mögliche Datentypen: `String` `$bind`
width?	(optional) - Breite der Komponente. Wird direkt an die `width`-property vom iFrame gebunden.
height?	(optional) - Höhe der Komponente. Wird direkt an die `height`-property vom iFrame gebunden.
events?	(optional) - Definition der Events des CustomControls.
visible?	(optional) - Gibt an, ob das Element angezeigt wird. Technisch wird es dennoch aufgebaut.
exists?	(optional) - Gibt an, ob das Element angezeigt wird. Technisch wird es nicht aufgebaut.
style?	(optional) - Angabe von individuellem Styling

Eigenschaften von events

receiveMessage

Aktion, die beim Erhalt einer Nachricht vom zugehörigen CustomControl ausgeführt wird:

$script: JavaScript ausführen
$backend: Codeblock ausführen
$page: Auf eine Page navigieren
$navigation: Auf ein Standardmodul des Portals navigieren
$command: Command ausführen

Die Kommunikation zwischen iFrame und Page ist nur bei selbst definierten iFrames möglich. Sollte eine Kommunikation zu einem externen iFrame benötigt werden, so kann dies in ein CustomControl eingebettet und darin die Kommunikation abgewickelt werden.

Beispiel eines CustomControls mit Kommunikation zum iFrame in einer Page:

YAML

controlType: custom
name: demoControl
id: demoCustomControlId
width: 300px
height: 400px
events: 
  receiveMessage:
    $script: |
      if ($.message.startsWith('Init abgeschlossen')) {
        debug.log('Nachricht vom iFrame erhalten');
      }
...
controlType: button
label: SendMessageToCustomControl
events:
  click:
    $script: |
      $.customControl('demoCustomControlId').postMessage($.variables.testVar);

Beispielhafte Implementierung einer JavaScript-Datei für die Kommunikation mit der Page. Die page.js-Datei wird automatisch generiert und sorgt dafür, dass die Nachricht an das entsprechende Element in der Page gesendet wird.

JSX

import { page } from "./page.js";

window.addEventListener("message", (event) => {
  var messageContent = event.data;
});

page.sendMessage("Nachricht vom CustomControl an die Page");

Aktuell stellt die generierte page.js über das pageObject zwei Functionen zur Verfügung:

`page.sendMessage`	Erlaubt die Kommunikation mit der Page
`page.onThemeChanged`	Erlaubt die Reaktion auf Themewechsel, indem hier ein Callback `(mode, style) => void` definiert wird.

Neuer CustomControl Lifecycle

Seit der be-Portal-Verison 10.0.0 ist der neue CustomControl Lifecycle implementiert und verwendbar. Die “alte” Herangehensweise funktioniert weiterhin, soll bei größeren CustomControls immer weiter auf die neue Version umgestellt werden.

Mit dem neuen Lifecycle ist es möglich CustomControls unabhängig vom Besitzer-Package zu Versionieren und zu Veröffentlichen. Dies soll die Verwendung und die Arbeit mit CustomControls vereinfachen.

In der neuen Version werden CustomControls als NPM-Package gebaut und veröffentlicht, ohne dass das Besitzer-Package geupdated werden muss. Das neue CustomControl-Package wird unter dem Scope des Besitzer-Packages veröffentlicht, das heißt, dass der Name des CustomControls innerhalb des Besitzer-Packages eindeutig sein muss.

CustomControls werden anschließend aus der Dontenwill-NPM-Registry geladen.

Definition im Package:

Die neuen customControls werden weiterhin in einer .customControls.yml - Datei angegeben. Es ist nun jedoch möglich mithilfe der Property source.package sowohl den Namen des customControls, als auch die zu verwendende Version des customControls anzugeben.

YAML

customControls:
  - name: demoCustomControl
    description: CustomControl mit Kommunikation zwischen Page und iFrame
    source:
      package:
        name: "@demo/demo-custom-control"
        version: "1.0.0"

Die hinterlegte Version muss im Vorfeld veröffentlicht worden sein und im Dontenwill-Nexus verfügbar sein: http://10.10.227.188:4873/

Veröffentlichen eines CustomControls:

Zunächst erstellt man für sein neues CustomControl ein neues Modul, in welchem alle zugehörigen Dateien abgelegt werden. Dies können HTML, Javascript, CSS oder andere Dependency-Dateien sein. Außerdem muss für jedes CustomControl eine eigene package.json erstellt werden, da wir das “neue” CustomControl wie ein eigenes Package behandeln. Für unser Beispiel sollte die package.json ungefähr so aussehen:

JSON

{
  "name": "@demo/demo-custom-control",
  "version": "1.0.1",
  "type": "module",
  "files": [
    "dist/**/*",
    "!dist/**/*/js.map"
  ],
  "publishConfig": {
    "registry": "http://10.10.227.188:4873"
  },
  "description": "demo",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "build": "vite build",
    "devpublish": "node ./devpublish.js"
  },
  "author": "",
  "license": "ISC",
  "dependencies": {
    "vite": "^7.3.1"
  }
}

In dieser JSON müssen wir den Namen, die zu veröffentlichende Version und die IP des Dontenwill-Registry angegeben werden.

Mithilfe von npm run build im entsprechenden Verzeichnis des CustomControls, werden die Assets (HTMP, JS, CSS, Dependency-Dateien) in ein s.g. Vite-Bundle zusammengefasst.

Ein anschließendes npm publish führt dazu, dass die aktualisierten Assets auf die Dontenwill-Registry hochgeladen werden.

Diese neuste Version muss nun in der customControl-package.json hinterlegt und neu installiert werden. Das Portal versucht anschließend die aktuellste Version des CustomControls aus der Registry zu laden und anzuzeigen.

Development von CustomControls:

Während der Entwicklung von neuen CustomControls möchte man nicht die ganze Zeit neue Versionen des CustomControls und des Packages installieren.

Deshalb gibt es die Möglichkeit einen s.g. “Dev-Upload” zu nutzen und damit das CustomControl und dessen Assets mit der Version “dev” direkt in die Datenbank zu laden. Für dieses Vorgehen benötigt es die devpublish.js im Modul des CustomControls. In dieser werden Informationen zum Zielsystem und Zugangsdaten hinterlegt, damit es möglich ist, Assets auf das System zu laden. Die Vorlage für die devpublish.js befindet sich wie alle anderen Vorlagedateien im beng-Repo unter demo-custom-control.

Des Weiteren ist es notwendig das CustomControl in den “Dev-Mode” zu versetzen, damit nicht die installierte Version vom Portal genutzt, sondern die kürzlich hochgeladene Dev-Version angezeigt wird. Dafür navigiert man auf die “Portal Debug Einstellungen” - Page ( /page/BEPO.portal-debug ) und versetzt sein gewünschtes CustomControl in der unteren Tabellen in den “Dev-Mode”.

Durch einen Klick auf “Cookie setzen” wird im Hintergrund ein Cookie auf der Seite gesetzt, welches dafür sorgt, dass immer die Dev-Version dieses CustomControls angezeigt wird. Damit dieses Cookie erstmals greift muss ein Package-Reload und ein Cache-Reload im Portal stattfinden.

Um eine neue Dev-Version des CustomControls zu erstellen, bearbeitet man die Assets seines Controls nach seinen Wünschen. Anschließend muss man diese Assets wieder mithilfe von npm run build zu einem Vite-Bundle bauen. Nach erfolgreichem Build ruft man mithilfe von npm run devpublish den Dev-Upload auf.

Die neuen Assets sollten nun dem Portal zur Verfügung stehen und angezeigt werden.

Die korrekte Funktion lässt sich über die F12-Konsole und dem Network-Tab überprüfen. Im Request eines CustomControl-Assets (z.B. index.js) sollte die “dev”-Version statt einer normalen Version zusehen sein.