Configuration Forms

Require: Symcon >= 4.0

The configuration forms are JSON files that are used to configure the properties of IP-Symcon instances.
These are usually loaded from the Management Console and displayed accordingly.

The JSON file describing the configuration form has up to three areas which can, independently of one another, be individually described.

A translation of the "caption" and "label" can be added via the Localizations via the locale.json.

Form areas

elements
Form fields defined in the "elements" area can set the properties of an instance. The name of a form field, if available, corresponds to the name of the property which is set via IPS_SetProperty. If the "elements" area is not to be visible, it must not be defined.

actions
The "actions" area is a so-called test environment. The form fields defined here cannot change the properties of the respective instance. If the "actions" area is not to be visible, it must not be defined.
The general rule: The test environment can only be used if changes have been accepted in the elements area. This prevents settings that have not been accepted from being tested.

status
The "status" area defines possible status messages. No form fields are allowed in the "status" area, only status messages which are explained under Status Message. If the module is not to display any status messages, this area does not have to be defined.

Overview of the insertable form fields

Examples

Basic structure of the JSON file

{
    "elements":
    [
        ... // Insert form fields here
    ],
    "actions":
    [
        ... // Insert form fields here
    ],
    "status":
    [
        ... // Insert status messages here
    ]
}

Complete example using an SMS module

{
    "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" }
    ]
}

Validation

A JSON schema is available for configuration forms: formSchema.json

The schema describes all form fields and their parameters as they are supported by the Management Console. Unknown form fields, typos in parameter names, wrong data types (e.g. "digits": "2" instead of "digits": 2) and parameters that have no effect on the respective form field are reported as errors.

With the schema, editors like Visual Studio Code or PhpStorm offer autocompletion and check the form.json while editing. To do this, the schema is specified in the form.json:

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

Alternatively, the schema can be assigned to the file form.json in the settings of the editor, in Visual Studio Code e.g. via the setting json.schemas.

Forms that are generated dynamically via GetConfigurationForm must also match the schema. Parameters like "options" or "columns", which are often only added there, are therefore optional in the schema.

The schemas for the other files of a module are listed under Structure.