Was können wir verbessern?

Dokumentation

(Bearbeiten)

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
link (optional) (default: false) Ist dieser Parameter true, dann wird die Ausgabe des onAdd, 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)
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 true 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)
edit (optional) Beschreibung eines editierbaren Elements
label sichtbare Beschriftung einer Spalte (veraltet)
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)
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

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

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 noValuesFromConfiguration nicht auf true gesetzt, so werden zuerst die Werte eingetragen, die als Modul-Eigenschaften gesichert wurden. 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']);" }

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