Skip to end of metadata
Go to start of metadata

Sink bedeutet Datenziel, z.B. eine Datenbank.

Alle Dateien einer Sink müssen liegen in ~/webfrontend/htmlauthdir/plugins/stats4lox/Sinks/$Sink

$Sink ist der eindeutige Name des Datenziels, die mit dieser Bezeichnung auch in der Konfiguration verwendet wird.

Im Verzeichnis $Sink muss ein Perl-Modul namens $Sink.pm liegen (z.B. ~/webfrontend/htmlauthdir/plugins/stats4lox/Sinks/RRD/RRD.pm)

Jeder einzelne Fetch einer Statistik ruft alle verfügbaren Sinks auf.


Sende-Vorgang

Das Modul $Sink.pm muss eingebunden werden können.

Im Modul wird die Funktion value aufgerufen. Die value-Funktion muss das Speichern des oder der Werte durchführen und als Ergebnis einen return ungleich undef/0 zurückgeben.

Eingangsparameter

Folgende Eingangsparameter stehen der Funktion zur Verfügung. Diese werden als Hash (Named Parameters) übergeben:

Eingangsparameter

Bedeutung

statid (string)Das ist die ID des aktuellen Statistikobjekts
statcfg (hashref)Dies ist ein Hashref auf die Konfiguration dieses Statistikobjekts
timestamp (string)Die Zeit des Wertes in unix-epoch
value (string)Der abgeholte Wert
outputs (hash)Ein Hash mit zusätzlichen Werten. Das key-Element des Hashes ist das Label, der Wert dessen Wert.

Im Code kann auf die Einstellungen dieses Statistikobjekts zugegriffen werden mit $statcfg->{Sink}→{$Sink}→{$Param}, bzw. auch auf alle anderen Einstellungen des Statistikobjekts. Die Einstellungen selbst muss das Sink-Plugin bei der Einrichtung der Statistik durch den Benutzer festlegen.

Für Zeit-Genauigkeit sollte unbedingt die Zeit (timestamp) aus dem Fetch-Ergebnis verwendet werden (kein generisches time beim Speichern), da Holen und Speichern zeitlich versetzt ist. 

Der Code im Modul kann beliebige Unterprogramme enthalten. Diese sollten mit Underscore gepräfixt werden (sub _meinefunktion), damit es keine Namenskonflikte mit dem Interface gibt.

Rückgabe

Jede Rückgabe, die nicht undef/0 ist, wird als Erfolg gewertet.

Eine Rückgabe von undef/0 wird als "kontrollierter Abbruch" gewertet (der Fetcher protokolliert das mit einem Fehler, dass die Speicherroutine einen Nicht-Erfolg zurückgegeben hat.

Liefert der Aufruf der value-Funktion eine Exception, wird das als "unkontrollierter Abbruch" gewertet (der Fetcher protokolliert die Fehlermeldung der Exception).

Statistik-Konfiguration

Jede einzelne Statistik erlaubt jeder Source, Felder zu bearbeiten oder zu initialisieren. Dies erfolgt mit einem Aufruf der Funktion initstatcfg in $Sink.pm.

Die Funktion muss einen String mit dem zu integriernden html-Code zurückliefern, sowie das zuvor übergebene statcfg-Hashref.

Eingangsparameter

Bevor die statcfg-Daten in die Felder im Formular geschrieben werden, kann eine Routine Felder im aktuellen Datensatz bearbeiten oder initial befüllen.

Übergeben wird ein Hash mit named Parametern.

EingangsparameterBedeutung
statid (string)Das ist die ID des aktuellen Statistikobjekts
statcfg (hashref)Dies ist ein Hashref auf die Konfiguration dieses Statistikobjekts

Die Routine muss nun HTML-Code mit den Anzeige- und Eingabefeldern erstellen, und diesen als String zurückliefern.

Für das Erstellen des Templates eignet sich HTML::Template, wie es auch in Plugins verwendet wird. Das Template-File wird am besten im $Sink-Ordner abgelegt und von dort geladen.

Sollten in JavaScript Ajax-Requests verwendet werden, kann im $Sink-Ordner auch ein serverseitiger Ajax-Handler gespeichert werden.

Wichtig!

  • Die Werte selbst müssen NICHT befüllt werden! Das erledigt Stats4Lox. 
  • Auswahlen von Dropdowns oder Auswahllisten müssen vorbefüllt sein, jedoch nicht selected/checked.
  • Damit diese Befüllung funktioniert, müssen die Feld-IDs der Hierarchie des statcfg-JSON-Files folgen, beginnend mit dem Präfix statcfg, z.B. id="statcfg|Sink|RRD|step" befüllt die Konfiguration mit dem Wert aus dem JSON.
  • Wenn Formularfelder mit dieser ID-Syntax erzeugt werden, die in der Config leer sind, und der Benutzer speichert, wird dieser als Datensatz neu im JSON angelegt.
  • Auch normale <div>'s oder <span>'s können diese ID-Syntax verwenden, dann wird der Wert nur angezeigt und kann vom Benutzer nicht verändert werden.

Sollen Werte automatisch initialisiert oder modifiziert werden, dann im übergebenen statcfg-Objekt ändern. Bitte beachten, dass diese Änderungen nur im Formular enthalten sind, und tatsächlich erst gespeichert werden, wenn der Benutzer auch auf "Speichern" drückt.

Rückgabeparameter

Zurückgegeben werden soll ein Hash mit zwei Inhalten: Dem HTML, das angezeigt werden soll, und dem statcfg-Objekt.

RückgabeparameterBedeutung
statcfg (hashref)Die übergebene statcfg muss wieder zurückgegeben werden.
html (string)Das HTML, das ausgegeben werden soll.


  • No labels