List

Require: IP-Symcon >= 4.2

Creates a list with the heading caption.
The displayed columns are defined in columns.
Initial entries in the list can be specified via values.

General Parameters

Parameters for Columns

Parameters for edit

If the "type" List or Tree is used, the value of this column is not JSON-coded again. It is only necessary to parse the value of the higher-level list once. Each sub-list or subtree is then directly available as an object. Similarly, the values in "values" do not have to be coded twice.

The "add" parameter of the column is translated according to the localization, provided the "type" of "edit" is ValidationTextBox or PasswordTextBox or "edit" is not set at all

It is possibly to update only specific parts of columns or values with the function UpdateFormField by using a dot notation. In this case, the target is provided as columns.x.y or values.x.y. x refers to the index of the affected column or value and y refers to the name of the updated field. It is also possible to update a single column or value completely by using columns.x or values.x as target. For example, updating the width of the second column can be done via $this->UpdateFormField('list', 'columns.1.width', '200px');.

Parameters for sort

Parameters for values

What the individual colors mean in messages and in the configurator can be read under the color codes for messages and configurators.

Saving and loading lists

When the list is saved, all list elements that can be edited or that have set the save parameter are saved as module properties.
If the list is reloaded and the parameter loadValuesFromConfiguration is not set to false, the values that were saved as module properties are entered first. If loadValuesFromConfiguration is set to false, values are not loaded from the property and only as described in the next steps. If values from the property should be used as basis anyway, they must be provided within the values. The other elements, including the color, are filled with the initial values from values.
If there are more lines than elements in values, elements of the superfluous lines that were not saved as module properties are filled with the initial value add of the corresponding column.

Selected Line as a Variable in on-Actions

In the definition of the configuration form, the values of the table can be used as the variable $Name. The object can be accessed like an array. If the corresponding object is accessed with a string index, the corresponding value is returned as defined in values of the selected line. If a numeric index is accessed or the object is iterated, the corresponding line is returned, the individual parameters of which can in turn be referenced by a string index.

Example:

// Output the name of the currently selected row in the devices table
    { "type": "Button", "caption": "Output", "onClick": "print_r($devices['name']);" }

    // Output the name of the first line of the devices table
    { "type": "Button", "caption": "Output", "onClick": "print_r($devices[0]['name']);" }

Individual Forms for Editing

By default, when editing or adding a new row, a form based on the edit parameters of the individual columns is used. However, if the parameter "form" is set, a form that is described by that parameter is used instead.
If a row is edited, the value of each form field is set depending on the value with the same name of the edited row, if available. During adding, the initial values of the form fields are instead defined by the "add" value of the column with the same name if such a column exists. When the dialog is confirmed, all values of the dialog are saved for the row. If afterwards columns exist, whose name are not contained within the form, their values are set by their "add" value.
When applying the configuration, all values that correspond to a column are saved as usual depending on the "save" parameter. If a value does not fit any column, it is saved in any case.
Parts of an individual form can be updated via UpdateFormField just like within the regular form.
Example for the use of the "form" parameter can be found within the Test Repository.

Register and read out values from the table in PHP

If the table was defined in the configuration form in the elements area, the table can be registered with the RegisterPropertyString function. The table is then saved as a JSON-encoded string.

The ReadPropertyString function can be used to read out the stored string. In a next step the function __json_decode__ should be used to convert the read string into an array.

Example:

$arrString = $this->ReadPropertyString("devices");
    $arr = json_decode($arrString);

Example

// Simple editable list of instances and associated values
    // The list initially contains an entry
    {
        "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
        }]
    }

If the value InstanceID of the first entry in the example table is changed to 54321 and Temperature to 37.0 and the table is saved, the new values for InstanceID and Temperature are persistently saved as module properties. Since the other elements, i.e. name, state and the color of the line rowColor, cannot be edited, they are not saved either.

If the table is now reloaded, the saved values for InstanceID and Temperature are loaded first. The non-editable fields name and state are then assigned the values from values i.e., "ABCD" and "OK!" filled. The color is also loaded from values, which gives the line a red background.

If one has also added another line to the table and set the values InstanceID and Temperature to 314 and -5.3, respectively, then these would also be loaded from the module properties. Since there is only one element in values, the non-editable fields are filled according to the standard values from add. The name field of the second line would remain empty and state would be set to "OK!". Since no color is defined, the background of this line would be transparent.

// List with alternative sorting
    {
        "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"
            }
        ]
    }