Zum Ende der Metadaten springen
Zum Anfang der Metadaten

Alle Dateien einer Source müssen liegen in ~/webfrontend/htmlauthdir/plugins/stats4lox/Sources/$Source (im weiteren wird dieser Ordner immer als $Source-Ordner bezeichnet)

$Source ist der eindeutige Name der Quelle, die mit dieser Bezeichnung auch in der Konfiguration verwendet wird.

Im Verzeichnis $Source muss ein Perl-Modul namens $Source.pm liegen (z.B. ~/webfrontend/htmlauthdir/plugins/stats4lox/Sources/Loxone/Loxone.pm)

Jede einzelne Statistik verwendet jene Source, die im statistics.json als "Source"-Objekt angegeben ist ($statsobj->{Stat}→{$key}→{Source}).

Fetch-Vorgang

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

Im Modul wird die Funktion fetch aufgerufen. Die fetch-Funktion muss das Abholen des Wertes durchführen und den oder die Ergebnisse zurückliefern.

Eingangsparameter

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

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

Im Code kann auf die Einstellungen dieses Statistikobjekts zugegriffen werden mit $statcfg->{Source}->{<Sourcename>}→{}. Die Einstellungen selbst muss das Source-Plugin bei der Einrichtung der Statistik durch den Benutzer festlegen.

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

Rückgabe

Die Rückgabe muss als Hash erfolgen.

Eine Source muss mindestens einen Einzel-Wert unterstützen, kann aber auch mehrere Werte zurückliefern. Der Einzel-Wert muss immer zurückgeliefert werden, um Sinks zu unterstützen, die nur Einzelwerte unterstützen.

ParameterBedeutung
timestampEin Zeitstempel in unix-epoch. Wenn die Daten aktuell sind, kann der Befehl time verwendet werden.
valueDer Wert der Rückgabe. Dies muss immer befüllt sein, auch wenn zusätzlich weitere Werte zurückgegeben werden.
outputs

Optional. outputs muss einen Hash enthalten mit einer Liste aus label = $value Kombinationen.

Sprich: $outputs{$label} = $value;


Der Rückgabe-Hash kann dann so ausehen:

$returnhash{timestamp} = time;
$returnhash{value} = $value;
$returnhash{outputs} = \%outputs;

Statistik-Konfiguration

Jede einzelne Statistik erlaubt der Source, Felder zu bearbeiten oder zu initialisieren. Dies erfolgt mit einem Aufruf der Funktion initstatcfg in $Source.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 $Source-Ordner abgelegt und von dort geladen.

Sollten in JavaScript Ajax-Requests verwendet werden, kann im $Source-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|Source|Loxone|category" 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.



  • Keine Stichwörter