List

Benötigt: IP-Symcon >= 4.2

Erstellt eine Liste mit der Überschrift caption.
Die angezeigten Spalten werden in columns definert.
Initiale Einträge der Liste können via values vorgegeben werden.

Allgemeine Parameter

Parameter für columns

Parameter für edit

Wird der "type" List oder Tree verwendet, so wird der Wert dieser Spalte nicht noch einmal JSON-codiert. Es ist also lediglich erforderlich den Wert der übergeordneten Liste einmalig zu parsen. Jede Unterliste bzw. Unterbaum steht dann direkt als Objekt zur Verfügung. Analog müssen die Werte in "values" auch nicht doppelt codiert werden.

Der Parameter "add" der Spalte wird entsprechend der Lokalisierung übersetzt, sofern der "type" von "edit" ValidationTextBox oder PasswordTextBox ist oder "edit" gar nicht gesetzt ist

Es ist möglich mit der Funktion UpdateFormField nur Teile von von columns oder values zu aktualisieren, indem eine Punktnotation verwendet wird. In dem Fall wird als Ziel columns.x.y bzw. values.x.y verwendet. x bezieht sich dabei auf den Index der betroffenen Spalte bzw. des betroffenen Wertes und y auf den Namen des Feldes. Es ist auch möglich einen einzelne Spalte bzw. einen einzelnen Wert komplett zu bearbeiten indem als Ziel columns.x bzw. values.x verwendet wird. Um also beispielsweise die Breite der zweiten Spalte anzupassen, kann der Befehl $this->UpdateFormField('list', 'columns.1.width', '200px'); verwendet werden.

Parameter für sort

Parameter für values

Was die einzelnen Farben bei Meldungen und im Konfigurator bedeuten kann unter den Farbcodes für Meldungen und Konfiguratoren nachgelesen werden.

Speichern und Laden von Listen

Beim Speichern der Liste werden alle Listenelemente, die editierbar sind oder den Paramter save gesetzt haben, als Modul-Eigenschaften gesichert.
Wird die Liste erneut geladen und ist der Parameter loadValuesFromConfiguration nicht auf false gesetzt, so werden zuerst die Werte eingetragen, die als Modul-Eigenschaften gesichert wurden. Steht loadValuesFromConfiguration auf false, werden keine Werte aus den Eigenschaften geladen sondern nur wie in den weiteren Schritten beschrieben geladen. Sollen dennoch Werte aus der Eigenschaft als Grundlage verwendet werden, so müssen diese selbstständig in values eingetragen werden. Die weiteren Elemente, inklusive der Farbe, werden mit den initialen Werten aus values aufgefüllt.
Existieren mehr Zeilen als Elemente in values, so werden Elemente der überzähligen Zeilen, welche nicht als Modul-Eigenschaften gesichert waren, mit dem Initialwert add der entsprechenden Spalte gefüllt.

Ausgewählte Zeile als Variable in on-Aktionen

In der Definition des Konfigurationsformulares können die Werte der Tabelle als Variable $Name verwendet werden. Auf das Objekt kann wie auf ein Array zugegriffen werden. Wird auf das entsprechende Objekt mit einem String-Index zugegriffen, so wird der entsprechende Wert wie in values definiert der ausgewählten Zeile zurückgegeben. Wird mit einem numerischen Index zugegriffen oder das Objekt iteriert, so wird die entsprechende Zeile zurückgegeben, deren einzelne Parameter widerum per String-Index referenziert werden können.

Beispiel:

//Gebe den Namen der aktuell gewählte Zeile der Tabelle devices aus
    { "type": "Button", "caption": "Ausgabe", "onClick": "print_r($devices['name']);" }

    //Gebe den Namen der ersten Zeile der Tabelle devices aus
    { "type": "Button", "caption": "Ausgabe", "onClick": "print_r($devices[0]['name']);" }

Individuelle Formulare zum Bearbeiten

Standardmäßig wird beim Bearbeiten oder Hinzufügen einer Zeile ein Formular auf Basis der edit-Parameter der einzelnen Spalten verwendet. Ist allerdings der Parameter "form" gesetzt, so wird stattdessen das davon beschriebene Formular verwendet.
Wird dabei eine Zeile bearbeitet, wird der Wert jedes Formularfeld basierend auf dem Wert mit gleichem Namen in der bearbeiteten Zeile gesetzt, sofern vorhanden. Beim Hinzufügen werden die initialen Werte der Formularfelder stattdessen basierend auf dem add-Wert der Spalte mit gleichem Namen gesetzt, falls solch eine Spalte existiert. Beim Bestätigen des Dialogs werden für die Zeile alle Werte des Dialogs mit dem Namen des Elements gespeichert. Falls dann noch Spalten existieren, deren Namen nicht im Formular vorkommen, wird deren Wert entsprechend des add-Wertes gesetzt.
Beim Übernehmen der Konfiguration werden alle Werte, die zu einer Spalte passen wie üblich basierend auf dem save-Parameter abgespeichert. Passt ein Wert zu keiner Spalte, so wird er auf jeden Fall abgespeichert.
Teile eines individuellen Formulars können wie im regulären Formular via UpdateFormField dynamisch angepasst werden.
Beispiele zur Verwendung des form-Parameters können im Test-Repository gefunden werden.

Werte aus der Tabelle in PHP registrieren und auslesen

Wurde die Tabelle im Konfigurationsformular im Bereich elements definiert, kann die Tabelle durch die Funktion RegisterPropertyString registriert werden. Die Tabelle wird dann als JSON-codierter String gespeichert.

Die Funktion ReadPropertyString kann genutzt werden um den gespeicherten String auszulesen. In einem nächsten Schritt sollte die Funktion __json_decode__ verwendet werden um den eingelesenen String in ein Array zu konvertieren.

Beispiel:

$arrString = $this->ReadPropertyString("devices");
    $arr = json_decode($arrString);

Beispiel

//Einfache editierbare Liste von Instanzen und dazugehörigen Werten
    //Die Liste enthält initial einen Eintrag
    {
        "type": "List",
        "name": "Devices",
        "caption": "Devices",
        "rowCount": 5,
        "add": true,
        "delete": true,
        "sort": {
            "column": "Name",
            "direction": "ascending"
        },
        "columns": [{
            "caption": "InstanceID",
            "name": "InstanceID", 
            "width": "75px",
            "add": 0,
            "edit": {
                "type": "SelectInstance"
            }
        }, {
            "caption": "Name",
            "name": "Name",
            "width": "auto",
            "add": ""
        }, {
            "caption": "State",
            "name": "State",
            "width": "40px",
            "add": "New!"
        }, {
            "caption": "Temperature",
            "name": "Temperature",
            "width": "75px",
            "add": 20.0,
            "edit": {
                "type": "NumberSpinner",
                "digits": 2
            }
        }],
        "values": [{
            "InstanceID": 12435,
            "Name": "ABCD",
            "State": "OK!",
            "Temperature": 23.31,
            "rowColor": "#ff0000" //rot
        }]
    }

Wird in der Beispieltabelle nun der Wert instanceID des ersten Eintrages auf 54321 und temperature auf 37.0 geändert und die Tabelle gespeichert, so werden die neuen Werte für instanceID und temperature als Modul-Eigenschaften persistent gespeichert. Da die weiteren Elemente, also name, state und die Farbe der Zeile rowColor, nicht editierbar sind, werden diese auch nicht gespeichert.

Wird die Tabelle nun erneut geladen, so werden zuerst die gespeicherten Werte für instanceID und temperature geladen. Die nicht-editierbaren Felder name und state werden dann mit den Werten aus values, also "ABCD" und "OK!" gefüllt. Die Farbe wird ebenfalls aus values geladen, wodurch die Zeile einen roten Hintergrund erhält.

Hätte man der Tabelle zusätzlich eine weitere Zeile hinzugefügt und die Werte instanceID und temperature auf 314 bzw. -5.3 gesetzt, so würden diese ebenfalls aus den Modul-Eigenschaften geladen werden. Da sich in values lediglich ein Element befindet, werden die nicht-editierbaren Felder entsprechend der Standardwerte aus add gefüllt. Das Feld name der zweiten Zeile würde leer bleiben und state würde auf "OK!" gesetzt werden. Da keine Farbe definiert ist, wäre der Hintergrund dieser Zeile transparent.

// Liste mit alternativer Sortierung
    {
        "type": "List",
        "name": "sortList",
        "rowCount": 5,
        "add": false,
        "columns": [
            {
                "caption": "Text",
                "name": "Text",
                "width": "auto",
                "sortColumn": "Number"
            },
            {
                "caption": "Number",
                "name": "Number",
                "width": "200px",
                "visible": false
            }
        ],
        "values": [
            {
                "Text": "One",
                "Number": "1"
            },
            {
                "Text": "Two",
                "Number": "2"
            },
            {
                "Text": "Three",
                "Number": "3"
            }
        ]
    }