Customizable Panels

Neben den fest eingebauten Panels (Zeitreihe, KPI, Markdown, Bild, Workflow) bietet die hetida platform Customizable Panels: Dashboard-Panels, deren Darstellung durch selbst geschriebenen JavaScript-Code erzeugt wird. Damit lässt sich praktisch jede Visualisierung umsetzen, für die es kein Standard-Panel gibt.

Es gibt zwei Ausprägungen:

Typ	Bibliothek	Wofür
ECharts-Panel (`ECHART`)	Apache ECharts	Diagramme aller Art (Gauge, Pie, Bar, Linien, Heatmap …)
Tabellen-Panel (`TABULATOR`)	Tabulator	Tabellen mit Sortierung, Filterung, Styling und Export

Der Code wird im Browser zur Laufzeit ausgeführt — es wird nichts hochgeladen, kompiliert oder deployt. Wiederverwendbarer Code wird als Vorlage (Template) gespeichert und steht anschließend in der Panel-Seitenleiste zur Verfügung.

Zwei Bedeutungen von „custom"

Diese Seite behandelt das Schreiben von Panel-Inhalten durch (Power-)Nutzer. Das Hinzufügen völlig neuer Panel-Typen ist dagegen eine Quellcode-Änderung am Frontend (PanelRegister) und kein externer Erweiterungspunkt.

Berechtigung

Das Bearbeiten von Panel-Code und das Anlegen von Vorlagen ist an die Rolle ROLE_CUSTOM_PANEL_TEMPLATE_CREATOR gebunden. Daraus ergeben sich zwei Rollen im Umgang mit Customizable Panels:

	Ohne Rolle	Mit Rolle `ROLE_CUSTOM_PANEL_TEMPLATE_CREATOR`
Vorlage auswählen und verwenden	✅	✅
Variablen im Daten-Tab mit Daten verknüpfen	✅	✅
Code bearbeiten	❌ (Editor ist schreibgeschützt)	✅
Vorlagen anlegen / ändern / löschen	❌	✅

Serverseitig erzwingt ein Guard, dass ein Dashboard mit einem Panel-Code, der von keiner existierenden Vorlage stammt, nur mit dieser Rolle gespeichert werden kann — andernfalls antwortet die API mit 403.

Sicherheitshinweis

Panel-Code läuft im Browser des Betrachters (siehe Ausführung). Die eigentliche Vertrauensgrenze ist die Rolle — vergeben Sie ROLE_CUSTOM_PANEL_TEMPLATE_CREATOR nur an Nutzer, deren Code Sie vertrauen.

Aufbau des Panel-Editors

Ziehen Sie ein Customizable Panel aus der Seitenleiste in ein Dashboard und wählen Sie eine Vorlage. Der Editor besteht aus drei Tabs:

Allgemeines – Titel, Zeitbereich und allgemeine Panel-Eigenschaften.
Daten – Verknüpfung der im Code deklarierten Variablen mit Plattform-Daten (Channel-/Signal-Outputs, Zeitreihen, KPI-Werte) oder festen Werten.
Code – der JavaScript-Editor (nur mit Berechtigung schreibbar). Änderungen werden bei validem Code sofort in der Vorschau angezeigt; bei Fehlern erscheint ein Hinweis und Speichern ist nicht möglich.

Variablen und Datenbindung

Im Code deklarieren Sie Platzhalter mit einem vorangestellten @, eingebettet in String-Literale. Das Frontend erkennt diese Platzhalter automatisch, listet sie im Daten-Tab auf und ersetzt sie vor der Ausführung durch die verknüpften Werte.

Notation	Bedeutung
`"@Name"`	Der gesamte verknüpfte Wert
`"@Name:745"`	Mit Default-Wert – der Teil nach dem `:` dient als Vorschau-/Vorlagenwert
`"@Name.value"`	Nur die Werte-Spalte einer Zeitreihe
`"@Name.timestamp"`	Nur die Zeitstempel-Spalte einer Zeitreihe
`"@Name.[*]"`	Vollständige Zeitreihe als Array

Je nach verknüpftem Output-Typ wird der Platzhalter unterschiedlich ersetzt:

Einzelwert (KPI) → der Skalar (z. B. 745).
Zeitreihe → ein JSON-Array aus [timestamp, value]-Paaren. Über .value / .timestamp lässt sich eine einzelne Spalte herausziehen.
Text / Bool / sonstige → per JSON.stringify eingesetzt.

Ein nicht auflösbarer Platzhalter wird durch [] ersetzt (mit einer Warnung in der Browser-Konsole). Default-Werte (@Name:745) sind vor allem für Vorlagen nützlich, damit die Vorschau sofort etwas anzeigt.

ECharts-Panels schreiben

Ein ECharts-Panel muss im Code die Variable option setzen — ein ECharts-Options-Objekt. Der Rückgabewert wird intern an echarts.setOption(option) übergeben.

Der Code läuft in einem Web Worker; das Options-Objekt wird von dort an die Seite übertragen und darf deshalb keine Funktionen enthalten. Statt eines formatter-Callbacks verwenden Sie die Formatter-Strings von ECharts (z. B. formatter: '{value} W'). Enthält das Ergebnis dennoch eine Funktion, zeigt das Panel eine Fehlerseite mit genau diesem Hinweis.

Innerhalb des Codes stehen zur Verfügung:

require – lädt ausschließlich das ECharts-Modul: require('echarts').
document – ein Mock (nur getElementById, liefert null); es gibt keinen echten DOM-Zugriff.
Math, Date, JSON.

Beispiel (an die mitgelieferte Vorlage Simple Gauge angelehnt) — eine analoge Anzeige, deren Wert aus einem KPI-Output kommt:

option = {
  series: [
    {
      type: 'gauge',
      min: 0,
      max: 1000,
      color: '#c85d11',
      progress: { show: true, width: 6 },
      detail: {
        valueAnimation: true,
        fontSize: 30,
        offsetCenter: [0, '70%'],
      },
      data: [
        // @Water-lvl-north ist die Variable; 745 der Default-Wert für die Vorschau
        { value: '@Water-lvl-north:745' },
      ],
    },
  ],
};

Beliebige Beispiele aus der ECharts-Beispielgalerie lassen sich per Copy & Paste übernehmen — ersetzen Sie die statischen Datenwerte durch @-Variablen.

Tabellen-Panels (Tabulator) schreiben

Ein Tabellen-Panel muss ein Tabulator-Options-Objekt zurückgeben (return { … }). Verfügbare Globals: Math, Date, JSON (kein require, kein document). Auch dieses Objekt verlässt den Web Worker und darf deshalb keine Funktionen enthalten: Eigene Sortier- und Filterfunktionen referenzieren Sie über ihren Namen (byNumericField, byStringField, minMaxFilter), Formatter über Tabulators eingebaute Strings (z. B. formatter: "html").

// Zeitreihe als [timestamp, value]-Paare in Tabellenzeilen umwandeln
const rows = '@MY_TIMESERIES.[*]'.map(([timestamp, value]) => ({
  timestamp,
  value,
}));

return {
  data: rows,
  layout: 'fitColumns',
  columns: [
    { title: 'Zeitpunkt', field: 'timestamp' },
    { title: 'Wert', field: 'value', sorter: 'number' },
  ],
};

Die mitgelieferten Tabellen-Vorlagen zeigen darüber hinaus fortgeschrittene Muster (in den Code-Kommentaren dokumentiert): gestylte Zellen über formatter: "html" mit class='custom', ein zusätzliches rawValue-Feld zum Sortieren/Filtern gestylter Spalten sowie eigene Sorter (byNumericField, byStringField) und Header-Filter. Tabellen-Panels können optional eine Export-Funktion anbieten (showExportOptions).

Ausführung und Grenzen

Der Code läuft isoliert in einem Web Worker (über new Function(...)), getrennt vom Haupt-Thread und ohne echten DOM-Zugriff.
Es gilt ein Timeout von 10 Sekunden pro Ausführung. Lang laufender oder blockierender Code (z. B. eine Endlosschleife) wird abgebrochen und als Fehler-Panel dargestellt.
Die Isolation schützt vor Blockieren der UI, ist aber keine harte Security-Sandbox (gleiche Origin, kein iframe). Die Zugriffskontrolle erfolgt über die Rolle, nicht über den Worker.

Vorlagen verwalten (REST-API)

Vorlagen werden pro Tenant gespeichert; der templateCode wird serverseitig als opaker String abgelegt und nie ausgeführt. Eine Vorlage besteht aus:

Feld	Beschreibung
`name`, `description`	Anzeige-Metadaten
`templateCode`	Der JavaScript-Quellcode
`libraryType`	`ECHARTS` oder `TABULATOR`
`echartsType`	Kategorie für ECharts-Vorlagen: `PIE`, `GAUGE`, `BAR`, `TIMESERIES`, `OTHER`
`showExportOptions`	Export-Funktion für Tabellen-Vorlagen

Die Vorlagen lassen sich auch programmatisch über die REST-Schnittstelle pflegen (Tag custom-panel-templates):

Vorlage anlegen/aktualisieren (PUT, Upsert – ohne id anlegen, mit id aktualisieren; erfordert ROLE_CUSTOM_PANEL_TEMPLATE_CREATOR)
Vorlage abrufen
Vorlagen nach Typ abrufen (ECHARTS / TABULATOR)
Vorlage löschen (erfordert ROLE_CUSTOM_PANEL_TEMPLATE_CREATOR)

Die Authentifizierung erfolgt wie bei allen API-Aufrufen über ein Bearer-Token (siehe Authentifizierung).

Berechtigung​

Aufbau des Panel-Editors​

Variablen und Datenbindung​

ECharts-Panels schreiben​

Tabellen-Panels (Tabulator) schreiben​

Ausführung und Grenzen​

Vorlagen verwalten (REST-API)​