« Zurück zu Produkt

Dokumentation

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.

Beispiel

Allgemeine Parameter

Parameter Beschreibung
add (optional) (default: false) Wenn true, dann wird unter der Tabelle ein "Hinzufügen"-Button eingeblendet, welcher der Tabelle ein neues Element mit Standardwerten hinzufügt
caption (optional) Sichtbare Beschriftung der Liste
columns Spalten der Liste
delete (optional) (default: false) Wenn true, dann wird hinter jedem Eintrag in der Liste ein Button eingeblendet, welcher das entsprechende Element löscht
download (optional) (default: "") Ist dieser Parameter nicht leer und beinhaltet die Ausgabe des onAdd, onChangeOrder, onDelete oder onEdit-Skriptes eine Data-URL, so wird die Rückgabe als Textdatei mit dem Namen das download-Parameters heruntergeladen. (ab IP-Symcon 7.0)
form (optional) (default: basierend auf den edit-Parametern von columns) Ein individuelles Formular zum Bearbeiten oder Hinzufügen von Zeilen. Die Definition des Formulars erfolg analog zur Definition des Formulars für Aktionen statisch oder als PHP-Code. Wie das Formular ausgewertet und gefüllt wird ist im Abschnitt Individuelle Formulare zum Bearbeiten erklärt (ab IP-Symcon 7.0)
link (optional) (default: false) Ist dieser Parameter true, dann wird die Ausgabe des onAdd, onChangeOrder, onDelete oder onEdit-Skriptes als Link geöffnet. Ist er false, so wird die Ausgabe als Dialog im Konfigurationsformular angezeigt. (ab IP-Symcon 6.0)
name (optional) Name der Liste / der zu setzenden Eigenschaft
onAdd (optional) (default: "") Skript, welches nach dem Hinzufügen eines Eintrages der Liste ausgeführt wird. Sofern das Skript aus mehreren Zeilen besteht, können die einzelnen Zeilen auch als Array übergeben werden (Arrays werden ab Version 6.0 unterstützt). In dieser Ausführung bietet die Liste als Variablenwert nicht den aktuell ausgewählten Eintrag sondern den hinzugefügten Eintrag, siehe Ausgewählte Zeile als Variable in on-Aktionen. Ansonsten hat es die gleichen Eigenschaften wie onClick des Button (ab IP-Symcon 5.3)
onChangeOrder (optional) (default: "") Skript, welches nach dem Verschieben eines Eintrages der Liste ausgeführt wird. Sofern das Skript aus mehreren Zeilen besteht, können die einzelnen Zeilen auch als Array übergeben werden. In dieser Ausführung bietet die Liste als Variablenwert nicht den aktuell ausgewählten Eintrag sondern den verschobenen Eintrag, siehe Ausgewählte Zeile als Variable in on-Aktionen. Ansonsten hat es die gleichen Eigenschaften wie onClick des Button (ab IP-Symcon 6.3)
onDelete (optional) (default: "") Skript, welches nach dem Löschen eines Eintrages der Liste ausgeführt wird. Sofern das Skript aus mehreren Zeilen besteht, können die einzelnen Zeilen auch als Array übergeben werden (Arrays werden ab Version 6.0 unterstützt). In dieser Ausführung bietet die Liste als Variablenwert nicht den aktuell ausgewählten Eintrag sondern den gelöschten Eintrag, siehe Ausgewählte Zeile als Variable in on-Aktionen. Ansonsten hat es die gleichen Eigenschaften wie onClick des Button (ab IP-Symcon 5.3)
onEdit (optional) (default: "") Skript, welches nach der Bearbeitung eines Eintrages der Liste ausgeführt wird. Sofern das Skript aus mehreren Zeilen besteht, können die einzelnen Zeilen auch als Array übergeben werden (Arrays werden ab Version 6.0 unterstützt). In dieser Ausführung bietet die Liste als Variablenwert nicht den aktuell ausgewählten Eintrag sondern den bearbeiteten Eintrag, siehe Ausgewählte Zeile als Variable in on-Aktionen. Ansonsten hat es die gleichen Eigenschaften wie onClick des Button (ab IP-Symcon 5.3)
rowCount (optional) (default: 0) sichtbare Anzahl von Zeilen; bei mehr Zeilen in der Liste wird ein Scrollbalken eingeblendet - ist der Wert 0, so füllt die Liste den restlichen noch verfügbaren Platz im Instanzeditor. Nur ein Konfigurationselement kann den gesamten restlichen Platz erhalten.
sort (optional) Sortierung der Tabelle. Wird dies nicht gesetzt bleibt die Liste unsortiert
type List
values (optional) Initiale Einträge der Liste
visible (optional) (default: true) Bei true ist die Liste sichtbar, ansonsten ist sie unsichtbar (ab IP-Symcon 5.2)
enabled (optional) (default: true) Bei true kann die Liste verwendet werden, ansonsten wird sie deaktiviert dargestellt (ab IP-Symcon 6.0)
changeOrder (optional) (default: false) Bei true kann die Reihenfolge der Einträge per Drag & Drop verändert werden. Die Sortierung der Liste nach Spalten ist dann allerdings nicht möglich. (ab IP-Symcon 6.0)
loadValuesFromConfiguration (optional) (default: true) Dieser Parameter gibt an, ob die Liste mit den Werten der Eigenschaft gefüllt werden soll, siehe Speichern und Laden von Listen . Wird der Wert auf false gesetzt, so ist es für einen erfolgreichen Review im Module Store erforderlich, die Liste dennoch im Sinne des Benutzers zu füllen, siehe Reviewrichtlinien Punkt 13 (ab IP-Symcon 6.0)

Parameter für columns

Parameter Beschreibung
add (optional) initialer Wert in dieser Spalte bei einem neu hinzugefügtem Eintrag, notwendig wenn add bei der Liste auf true gesetzt ist
align (optional) (default: "left") Ausrichtung der Spalte (ab IP-Symcon 5.2)
"left": Inhalt wird linksbündig dargestellt
"center": Inhalt wird zentriert dargestellt
"right": Inhalt wird rechtsbündig dargestellt
caption Sichtbare Beschriftung einer Spalte
confirm (optional) (default: "") Abfragetext, bevor eine onClick-Aktion ausgeführt wird. Nur wenn die Abfrage mit "Ja" bestätigt wird, wird die Aktion ausgeführt. Ist kein Abfragetext definiert, so wird die Aktion direkt ausgeführt (ab IP-Symcon 5.2)
download (optional) (default: "") Ist dieser Parameter nicht leer und beinhaltet die Ausgabe des onClick-Skriptes dieser Spalte eine Data-URL, so wird die Rückgabe als Textdatei mit dem Namen das download-Parameters heruntergeladen. (ab IP-Symcon 7.1)
edit (optional) Beschreibung eines editierbaren Elements
label sichtbare Beschriftung einer Spalte (veraltet)
link (optional) (default: false) Ist dieser Parameter true, dann wird die Ausgabe des onClick-Skriptes dieser Spalte als Link geöffnet. Ist er false, so wird die Ausgabe als Dialog im Konfigurationsformular angezeigt. (ab IP-Symcon 7.1)
name Eindeutiger Name einer Spalte um diese zu referenzieren; der Name darf nicht "rowColor", "editable" oder "deletable" sein, da diese Werte für andere Funktionen belegt sind, siehe Parameter für values
onClick (optional) (default: "") Skript, welches bei einem Klick auf ein Feld dieser Spalte ausgeführt wird. Es hat die gleichen Eigenschaften wie onClick des Button. Das Skript wird nur ausgeführt, sofern dieses Feld nicht leer, also 0, false oder "" ist (ab IP-Symcon 5.2)
quickFilter (optional) (default: false) Bei true wird der Text dieser Spalte beim Schnellfilter in der Suche betrachtet. Sollte der Wert bei allen Spalten auf false gesetzt sein, so wird der Schnellfilter ausgeblendet. (ab IP-Symcon 7.2)
sortColumn (optional) Ist sortColumn gesetzt und wird nach dieser Spalte sortiert, so werden statt den Werten dieser Spalte, die Werte der Spalte mit dem Namen dieses Parameters verglichen
save (optional) (default: true, falls das Element editierbar ist, sonst false) Bei true sollen die Werte dieser Spalte als Modul-Eigenschaften gesichert werden, siehe Speichern und Laden von Listen
visible (optional) (default: true) Bei false wird die Spalte nicht angezeigt
width Breite der Spalte in Pixeln, als CSS-String (z.B. "100px"); eine einzige Spalte darf den Wert "auto" haben, wodurch die Breite dieser Spalte den restlich verfügbaren Platz nutzt

Parameter für edit

Parameter Beschreibung
type Typ der Darstellung, entsprechend der möglichen Eingaben:
CheckBox, IntervalBox, NumberSpinner, PasswordTextBox, Select, SelectCategory, SelectColor, SelectEvent, SelectFile, SelectInstance, SelectLink, SelectMedia, SelectObject, SelectScript, SelectVariable, ValidationTextBox, List, Tree
Weitere Parameter Die weiteren Parameter ergeben sich je nach gewähltem Typ; die Parameter "name" und "caption" des Typs werden ignoriert
Warning

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.

Warning

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

Warning

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 Beschreibung
column Name der Spalte, nach welcher die Liste sortiert wird
direction Die Richtung der Sortierung; "ascending" für eine aufsteigende Sortierung und "descending" für eine absteigende Sortierung

Parameter für values

Parameter Beschreibung
deletable (optional) (default: true) Bei false kann die Zeile nicht gelöscht werden (ab IP-Symcon 5.4)
editable (optional) (default: true) Bei false kann die Zeile nicht editiert werden, obwohl die Liste an sich editierbare Spalten besitzt (ab IP-Symcon 5.4)
rowColor (optional) (default: transparent) Hintergrundfarbe der Zeile als Hex-Code (Defaultfarben s.u.), leerer String für Transparenz
Weitere Parameter (optional) (default: "") Für jeden initialen Eintrag der Liste werden hier die Werte zu allen Spalten definiert. Hierfür wird für jede Spalte ein Parameter mit dem Namen der Spalte eingetragen. Die Belegung des Parameters entspricht dem Wert dieser Spalte bei dem entsprechenden Eintrag.
Farbe Hex-Code
Hellgrün #C0FFC0
Lila #C0C0FF
Gelb #FFFFC0
Grau #DFDFDF
Rot #FFC0C0

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"
            }
        ]
    }
Haben Sie noch Fragen?