Konfigurationsformulare

Benötigt: Symcon >= 4.0

Die Konfigurationsformulare sind JSON Dateien, welche zur Konfiguration der Eigenschaften von IP-Symcon Instanzen genutzt werden.
Diese werden normalerweise von der Verwaltungskonsole geladen und entsprechend angezeigt.

Die JSON-Datei, welche das Konfigurationsformular beschreibt, besitzt bis zu drei Bereiche die unabhängig voneinander individuell beschrieben werden können.

Eine Übersetzung der "caption" und "label" kann über die Lokalisierungen via der locale.json hinzugefügt werden.

Formularbereiche

elements
Im "elements"-Bereich definierte Formularfelder können die Eigenschaften einer Instanz setzen. Der Name eines Formularfeldes, sofern verfügbar, entspricht dem Namen der Eigenschaft, welche über IPS_SetProperty gesetzt wird. Soll der "elements" Bereich nicht sichtbar sein, so ist dieser nicht zu definieren.

actions
Der "actions"-Bereich ist eine sogenannte Testumgebung. Die hier definierten Formularfelder haben nicht die Möglichkeit Eigenschaften der jeweiligen Instanz zu verändern. Soll der "actions" Bereich nicht sichtbar sein, so ist dieser nicht zu definieren.
Generell gilt: Die Testumgebung kann nur genutzt werden, wenn Veränderungen im Elemente-Bereich übernommen wurden. Dadurch wird verhindert, das nicht übernommene Einstellungen getestet werden.

status
Der "status"-Bereich definiert mögliche Statusmeldungen. Im "status"-Bereich sind keine Formularfelder erlaubt, sondern nur Statusmeldungen, welche unter Statusmeldung erklärt werden. Soll das Modul keine Statusmeldungen anzeigen, so ist dieser Bereich nicht zu definieren.

Übersicht der einfügbaren Formularfelder

Beispiele

Grundaufbau der JSON Datei

{
    "elements":
    [
        ... //Hier Formularfelder einfügen
    ],
    "actions":
    [
        ... //Hier Formularfelder einfügen
    ],
    "status":
    [
        ... //Hier Statusmeldungen einfügen
    ]
}

Vollständiges Beispiel anhand eines SMS Moduls

{
    "elements":
    [
        { "type": "ValidationTextBox", "name": "Username", "caption": "Username" },
        { "type": "ValidationTextBox", "name": "Password", "caption": "Password" },
        { "type": "NumberSpinner", "name": "APIID", "caption": "APIID" },
        { "type": "ValidationTextBox", "name": "Sender", "caption": "Sender" },
        { "type": "Select", "name": "SMSType", "caption": "Type",
            "options": [
                { "caption": "SMS", "value": 0 },
                { "caption": "Combi-SMS", "value": 1 },
                { "caption": "MMS", "value": 2 }
        ]}
    ],
    "actions":
    [
        { "type": "ValidationTextBox", "name": "Number", "caption": "Number" },
        { "type": "ValidationTextBox", "name": "Message", "caption": "Message" },
        { "type": "Button", "caption": "Send Message", "onClick": "SMS_Send($id, $Number, $Message);" },
        { "type": "Button", "caption": "Read Balance", "onClick": "echo 'Balance: '.sprintf('%.2f', SMS_RequestBalance($id)).' credits';" }
    ],
    "status":
    [
        { "code": 102, "icon": "active", "caption": "Login information valid" },
        { "code": 201, "icon": "error", "caption": "Authentication failed" },
        { "code": 202, "icon": "error", "caption": "No credits left" }
    ]
}

Validierung

Für Konfigurationsformulare steht ein JSON Schema zur Verfügung: formSchema.json

Das Schema beschreibt alle Formularfelder mit ihren Parametern, so wie sie von der Verwaltungskonsole unterstützt werden. Unbekannte Formularfelder, Tippfehler in Parameternamen, falsche Datentypen (z.B. "digits": "2" statt "digits": 2) und Parameter, die beim jeweiligen Formularfeld keine Wirkung haben, werden als Fehler gemeldet.

Editoren wie Visual Studio Code oder PhpStorm bieten mit dem Schema eine Autovervollständigung und prüfen die form.json bereits beim Bearbeiten. Hierzu wird das Schema in der form.json angegeben:

{
    "$schema": "https://www.symcon.de/assets/files/validation/formSchema.json",
    "elements": [ ... ]
}

Alternativ kann das Schema in den Einstellungen des Editors der Datei form.json zugewiesen werden, in Visual Studio Code z.B. über die Einstellung json.schemas.

Formulare, die über GetConfigurationForm dynamisch erzeugt werden, müssen ebenfalls dem Schema entsprechen. Parameter wie "options" oder "columns", die häufig erst dort ergänzt werden, sind im Schema daher optional.

Die Schemas für die weiteren Dateien eines Moduls sind unter Struktur aufgeführt.