Tree

Benötigt: Symcon >= 5.0

Erstellt einen Baum mit der Überschrift caption.
Die angezeigten Spalten werden in columns definert.
Initiale Einträge des Baumes 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 des übergeordneten Baumes 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 add

Statt eines festen Wertes kann der Parameter add einer Spalte auch ein Objekt sein, welches beschreibt, mit welcher Strategie der Wert für einen neu hinzugefügten Eintrag automatisch generiert wird (ab Symcon 9.1). Der Wert wird beim Hinzufügen des Eintrages generiert und anschließend wie ein regulärer Wert behandelt. Der generierte Wert ist innerhalb der Spalte eindeutig: Stimmt ein zufälliger Wert mit dem Wert eines bestehenden Eintrages überein, so wird ein neuer Wert generiert. Generierte Werte werden nicht übersetzt.

Damit generierte Werte erhalten bleiben, werden Spalten mit einem solchen add-Wert standardmäßig gespeichert, d.h. der Parameter "save" ist für diese Spalten standardmäßig true. Fehlt einem geladenen Eintrag der Wert in einer solchen Spalte, z.B. weil die Spalte nachträglich hinzugefügt wurde, so wird der Wert beim Laden nach der gleichen Strategie generiert. Auch der Standardwert, den on-Aktionen erhalten, wenn kein Eintrag ausgewählt ist, wird nach der Strategie generiert. Kann kein eindeutiger Wert generiert werden, weil bereits alle möglichen Werte verwendet werden, z.B. bei "random-integer" mit einem kleinen Bereich zwischen min und max, so schlägt das Hinzufügen mit einer Fehlermeldung fehl.

// Spalten mit automatisch generierten Werten
{
    "caption": "ID",
    "name": "ID",
    "width": "50px",
    "add": { "strategy": "increment", "step": 10 }
}, {
    "caption": "Token",
    "name": "Token",
    "width": "auto",
    "add": { "strategy": "random-string", "length": 16 },
    "edit": { "type": "ValidationTextBox" }
}, {
    "caption": "Zufallszahl",
    "name": "Number",
    "width": "100px",
    "add": { "strategy": "random-integer", "min": 1, "max": 100 },
    "edit": { "type": "NumberSpinner" }
}, {
    "caption": "GUID",
    "name": "GUID",
    "width": "300px",
    "add": { "strategy": "guid" }
}

Die strategy "increment" ermittelt den nächsten Wert aus den aktuellen Einträgen. Wird der Eintrag mit dem höchsten Wert gelöscht, so wird dessen Wert beim nächsten Hinzufügen erneut vergeben. Soll ein Wert nie wiederverwendet werden, z.B. weil er als dauerhafte ID gegenüber einem externen System dient, so kann sich das Modul den höchsten jemals vergebenen Wert merken und ihn über start vorgeben.

// Gelöschte IDs werden nicht erneut vergeben
public function GetConfigurationForm(): string
{
    $form = json_decode(file_get_contents(__DIR__ . '/form.json'), true);
    // Das Attribut HighestID wird in ApplyChanges auf den höchsten Wert der Liste aktualisiert, sinkt aber nie
    $form['elements'][0]['columns'][0]['add'] = ['strategy' => 'increment', 'start' => $this->ReadAttributeInteger('HighestID') + 1];
    return json_encode($form);
}

Parameter für sort

Parameter für values

Speichern und Laden von Bäumen

Das Speichern und Laden von Bäumen erfolgt fast analog zu Listen.

In der Eigenschaft werden zusätzlich die Werte für id und parent gespeichert.

Beim Laden ist zu beachten, dass bei der Verwendung von values immer der Identifikator des Knotens angegeben werden muss, damit diese dem passenden Knoten aus der Eigenschaft zugewiesen werden können.

Verwendung des Bauminhaltes in on-Aktionen

Die Verwendung der Werte des Baumes in Skripten erfolgt analog zu Listen. Darüber hinaus beinhaltet jeder Eintrag den Wert "expanded", welcher angibt ob der Eintrag aktuell eingeklappt (false) oder ausgeklappt (true) ist.

Auf die Auswahl reagieren

Über den Parameter onSelectionChanged kann das Modul darauf reagieren, dass der Benutzer einen anderen Eintrag des Baumes auswählt (ab Symcon 9.1). Das Verhalten, die Anwendungsfälle und die Abgrenzung zum onClick einer Spalte entsprechen der List. Für den Baum gilt zusätzlich:

• Auch der Wechsel per Pfeiltaste links zum Elternknoten und per Pfeiltaste rechts zum ersten Kindknoten eines ausgeklappten Eintrages führt onSelectionChanged aus.
• Das Aus- und Einklappen eines Eintrages ändert die Auswahl nicht und führt nur onExpand aus. Wird dabei ein Eintrag verborgen, der ausgewählt ist, so wird die Auswahl ohne onSelectionChanged aufgehoben.
• Nach einer Änderung von values per UpdateFormField bleibt die Auswahl anhand der id des Eintrages erhalten.
• Oft stehen unterschiedliche Arten von Einträgen im Baum, z.B. Räume und Geräte. Anhand der Werte des ausgewählten Eintrages, z.B. $(Name des Baumes)['parent'] oder einer eigenen Spalte, kann das Skript unterscheiden, was ausgewählt wurde.

Beispiel: Ein Baum mit Räumen und Geräten. Wird ein Gerät ausgewählt, so wird sein Ort angezeigt und der Button "Status anzeigen" aktiviert. Wird ein Raum ausgewählt, so wird der Button deaktiviert.

// Beispiel: form.json
{
    "actions": [
        {
            "type": "Tree",
            "name": "Rooms",
            "caption": "Räume und Geräte",
            "rowCount": 6,
            "columns": [
                { "caption": "Name", "name": "Name", "width": "auto", "add": "" },
                { "caption": "InstanceID", "name": "InstanceID", "width": "100px", "add": 0, "visible": false }
            ],
            "values": [
                { "id": 1, "Name": "Wohnzimmer", "InstanceID": 0, "expanded": true },
                { "id": 2, "parent": 1, "Name": "Deckenlicht", "InstanceID": 12345 },
                { "id": 3, "Name": "Küche", "InstanceID": 0 },
                { "id": 4, "parent": 3, "Name": "Dunstabzug", "InstanceID": 23456 }
            ],
            "onSelectionChanged": "ROOM_UISelectNode($id, $Rooms['InstanceID']);"
        },
        { "type": "Label", "name": "NodeDetails", "caption": "Bitte ein Gerät auswählen" },
        {
            "type": "Button",
            "name": "StatusButton",
            "caption": "Status anzeigen",
            "enabled": false,
            "onClick": "ROOM_UIShowStatus($id, $Rooms['InstanceID']);"
        }
    ]
}

// Beispiel: module.php
<?php

declare(strict_types=1);

class RoomOverview extends IPSModule
{
    // onSelectionChanged des Baumes Rooms: Räume haben keine Instanz, nur Geräte
    public function UISelectNode(int $InstanceID)
    {
        $isDevice = IPS_InstanceExists($InstanceID);
        $this->UpdateFormField('NodeDetails', 'caption', $isDevice ? IPS_GetLocation($InstanceID) : 'Bitte ein Gerät auswählen');
        $this->UpdateFormField('StatusButton', 'enabled', $isDevice);
    }

    // onClick des Buttons "Status anzeigen"
    public function UIShowStatus(int $InstanceID)
    {
        if (!IPS_InstanceExists($InstanceID)) {
            echo 'Bitte ein Gerät auswählen';
            return;
        }
        echo (IPS_GetInstance($InstanceID)['InstanceStatus'] == IS_ACTIVE) ? 'Das Gerät ist aktiv' : 'Das Gerät ist nicht aktiv';
    }
}

Beispiel

{
    "type": "Tree",
    "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": [{
            "id": 1,
            "InstanceID": 0,
            "Name": "Kategorie",
            "State": "",
            "Temperature": 0
        },{
            "id": 2,
            "parent": 1,
            "InstanceID": 12435,
            "Name": "ABCD",
            "State": "OK!",
            "Temperature": 23.31,
            "rowColor": "#ff0000"
    }]
}