Configuration

Note that Yadoms has moved, click here for new wiki

Configuration

Plugins and widget can be configured. To prevent developper to manage himself the configuration, a standard configuration process has been defined.
You just have to define the configuration schema in the package.json file

In order to manage configuration, the developer must provide a configuration schema in the description of its package.json file.
This schema describe all parameters which can be configured in the configuration form.

Somme kind of types of parameter are available for plugins and widget and some others are only for plugins or widgets.

Translated fields

There are two fields that are in every type of parameter and have to be translated.

The name and the description.
The name is used to define the visible name of the parameter.
The description is used to define the description of the parameter to help the user to set value.

They must be directly in the parameter description in the package.json like this example

"offsetHour" : {
  "type" : "int",
  "name" : "hour offset",
  "description" : "used to make an offset on the time in hour",
  "defaultValue" : "0",
  "maximumValue" : "23",
  "minimumValue" : "0"
}

In this case the translated fields must be found in all language files except en.json in the following format. This example can be found in the fr.json file

{
   "configurationSchema" : {
      "offsetHour" : {
         "name" : "Offset d'heure",
         "description" : "Permet de faire un offset sur l'heure courante"
      }
      ...
   }
}

Common Types

int

This type describe an integer data.

Non optionnal fields

Type descriptor

This field define the type as int

"type" : "int"

Optionnal fields

Default Value

The defaultValue field permit to set the default value of the parameter it must be set between min and max allowed value if defined.
If not set the default value is 0 rounded by max and min values.

"defaultValue" : "5"

Minimum and Maximum value

It define the min and max values that can be setted in the parameter.

"maximumValue" : "23",
"minimumValue" : "0"

Example

"offsetHour" : {
  "type" : "int",
  "name" : "hour offset",
  "description" : "used to make an offset on the time in hour",
  "defaultValue" : "0",
  "maximumValue" : "23",
  "minimumValue" : "0"
}

decimal

This type describe a decimal data like 5.3. Decimal separator can be a "." or a ",".

Non optionnal fields

Type descriptor

This field define the type as decimal

"type" : "decimal"

Optionnal fields

Default Value

The defaultValue field permit to set the default value of the parameter it must be set between min and max allowed value if defined.
If not set the default value is 0.0 rounded by max and min values.

"defaultValue" : "5.2"

Minimum and Maximum value

It define the min and max values that can be setted in the parameter.

"maximumValue" : "17.8",
"minimumValue" : "0"

Precision

It define the precision of the decimal number. The value correspond to the number of digits after the decimal separator.

"precision" : "2"

Example

"CurrentCoefficient" : {
  "type" : "decimal",
  "name" : "correction coefficient",
  "description" : "Set a correction coefficient to adjust the value",
  "defaultValue" : "0.0",
  "maximumValue" : "1.0",
  "minimumValue" : "-1.0",
  "precision" : "2"
}

enumeration

This type describe a value taken from a list

Non optionnal fields

Type descriptor

This field define the type as enumeration

"type" : "enum"

List of values

This field define the list of values that can be set to the parameter

"values" : {
             "12H" : "12 hours",
             "24H" : "24 hours"
          }

Optionnal fields

Default Value

The defaultValue field permit to set the default value of the parameter.
If not set the default value is the first items in the values list

"defaultValue" : "12H"

Example

"timeFormat" : {
      "name" : "time format",
      "description" : "Permit to change the time format of the clock",
      "type" : "enum",
      "values" : {
         "12H" : "12 hours",
         "24H" : "24 hours"
      },
      "defaultValue" : "12H"
   }

string

This type describe a string data

Non optionnal fields

Type descriptor

This field define the type as string

"type" : "string"

Optionnal fields

Default Value

The defaultValue field permit to set the default value of the parameter.
If not set the default value is an empty string.

"defaultValue" : "john"

Maximum length

It define the max size of the string.

"maximumLength" : "30"

Required field

It defined the field as required. It is not possible to validate the form without have been filling at least one character in this field.

"required" : "true"

Encrypted field

It defined the field as encrypted. It will be shown as a password in the configuration form. The text will be encrypted with a light encrypting algorithm before sending it to the server. There is two kind of password based on usages. You can define decrytable passwords or not.
Encryption method will be chosen depending on the "decryptable" attribute value.
A plugin or a widget can ask for parameters and could decrypt password if "decrytable" attribue is set. If it is not decryptable, the plugin or widget could only encrypt his string using MD5 hex encoding and compare it the the encoded string.

If omitted, the password is decryptable.

"encrypted" : "true",
"decryptable" : "true"

Regular expression

It is possible to set a regex in order to make validation of the field. The regex must be with an error message which can be translated as same as name and description fields.

"regex" : "([0-9]{1,3}\\.){3}[0-9]{1,3}",
"regexErrorMessage" : "Must be an ipv4 adress like 192.168.0.12"

Example

"ipAddress" : {
    "type" : "string",
    "name" : "IP Address",
    "description" : "Set the IP Address of the peripheral",
    "regex" : "([0-9]{1,3}\\.){3}[0-9]{1,3}",
    "regexErrorMessage" : "Must be an ipv4 adress like 192.168.0.12",
    "required" : "true"
}

boolean

This type describe a boolean data

Non optionnal fields

Type descriptor

This field define the type as string

"type" : "bool"

Optionnal fields

Default Value

The defaultValue field permit to set the default value of the parameter.
If not set the default value is false.

"defaultValue" : "true"

Example

"enabled" : {
  "type" : "bool",
  "name" : "enabled",
  "description" : "Permit to enable the widget",
  "defaultValue" : "true"
}

device

This type allow developper to ask for a keyword of a device selection. He can ask for a list of device that match a capacity (ie: device that get temperature) or the list of device that have a keyword type in particular.

[[img alt="TODO"]] (error processing macro)

Non optionnal fields

Type descriptor

This field define the type as device

"type" : "device"

Expected keyword access

This field define the kind of access to the keyword that the device must have at least once. The value can be "get", "set" or "getSet".

"expectedKeywordAccess" : "get"

Expected type

This field define the type of keyword that the device must have at least once. The type can be "numeric", "string", "bool", "nodata" or "json". If this field is not present. It's must have expectedCapacity property. It can be a list.

"expectedKeywordType" : "numeric"

"expectedKeywordType" : ["numeric", "bool"]

Expected capacity

This field define the capacity that the device must have at least once. If this field is not present. It's must have expectedKeywordAccess property. It can be a list.

"expectedCapacity" : "switch"

"expectedCapacity" : ["switch", "dimmable"]

Example

"device" : {
         "name" : "Temp Sensor",
         "description" : "Device which provide switch",
         "type" : "device",
         "expectedCapacity" : ["switch", "dimmable"],
         "expectedKeywordAccess" : "get"
      }

"device" : {
         "name" : "Data to chart",
         "description" : "Data of a device that will be charted",
         "type" : "device",
         "expectedKeywordType" : "numeric",
         "expectedKeywordAccess" : "get"
      }

color

This type describe a color data

Non optionnal fields

Type descriptor

This field define the type as color

"type" : "color"

Optionnal fields

Default Value

The defaultValue field permit to set the default value of the parameter.
If not set the default value is a black color "#000000#.

"defaultValue" : "#FF0000"

Example

"plotColor" : {
                 "name" : "Color of the plot",
                 "description" : "Permit to change the color of the plot",
                 "type" : "color",
                 "defaultValue" : "#0000FF"
              }

section

This type allow user to make sections. They are used to group configuration items.

Non optionnal fields

Type descriptor

This field define the type as a section

"type" : "section"

Content

The content section contains all configuration fields that have to be in the section.

"content" : {
            "booleanParameter" : {
               "type" : "bool",
               "name" : "enabled",
               "description" : "Permit to enable the widget",
               "defaultValue" : "true"
            }

Optionnal fields

Checkbox to enable / disable the section

This parameter permit to add a checkbox at the top of the section that enable or disable the section.
It can be used for example to have an advanced configuration section for expermiented users only.
When the section is disabled, it collapse all the content of the section.
If not set the default value is false.

"enableWithCheckBox" : "true"

Default value for enable / disable checkbox

This parameter permit set the default value of the checkbox that permit you to enable or disable the section.
If not set the default value is false.

"enableWithCheckBoxDefaultValue" : "false"

Example

"advancedParameters" : {
          "type" : "section",
          "name" : "Advanced parameters",
          "description" : "For advanced users only",
          "enableWithCheckBox" : "true",
          "enableWithCheckBoxDefaultValue" : "false",
          "content" : {
             "booleanParameter" : {
                "type" : "bool",
                "name" : "enabled",
                "description" : "Permit to enable the widget",
                "defaultValue" : "true"
             },
             "CurrentCoefficient" : {
                "type" : "decimal",
                "name" : "correction coefficient",
                "description" : "Set a correction coefficient to adjust the value",
                "defaultValue" : "0.0",
                "maximumValue" : "1.0",
                "minimumValue" : "-1.0",
                "precision" : "2"
             }
          }
       }

Selectable sections

This type allow user to have many sections with a radiobutton which can active only once at a time.
It can be used for example if you have many mean of connection to your device. The user can choose the section which corresponding to its and all configuration items are automatically shown.

Non optionnal fields

Type descriptor

This field define the type as a radio section

"type" : "radioSection"

Content

The content section contains all sections that can be selected with all their content.
Be careful ! The first level elements must be sections. If you have string or decimal parameter to ask, use a section to put all your item inside.

"content" : {
             "ethernet" : {
                "type" : "section",
                "name" : "Ethernet",
                "description" : "An ethernet connection",
                "content" : {
                   "ipAddress" : {
                      "type" : "string",
                      "name" : "IP Address",
                      "description" : "Set the IP Address of the peripheral"
                   }
                }
             },
             "serial" : {
                "type" : "section",
                "name" : "Serial",
                "description" : "A serial Connection",
                "content" : {
                   "serialPort" : {
                      "type" : "string",
                      "name" : "Serial Port Name",
                      "description" : "Set the serial port name where the peripheral is plugged on of the peripheral"
                   }
                }
             }
          }

Example

"connection" : {
          "type" : "radioSection",
          "name" : "Connection",
          "description" : "kind of connection used",
          "content" : {
             "ethernet" : {
                "type" : "section",
                "name" : "Ethernet",
                "description" : "An ethernet connection",
                "content" : {
                   "ipAddress" : {
                      "type" : "string",
                      "name" : "IP Address",
                      "description" : "Set the IP Address of the peripheral"
                   }
                }
             },
             "serial" : {
                "type" : "section",
                "name" : "Serial",
                "description" : "A serial Connection",
                "content" : {
                   "serialPort" : {
                      "type" : "string",
                      "name" : "Serial Port Name",
                      "description" : "Set the serial port name where the peripheral is plugged on of the peripheral"
                   }
                }
             }
          }
       }

Binding

Some configuration items or values are dynamic and depends on the instance of a plugin. So there is a mechanism that allow you to fill some fields of configurationSchema dynamically.
You can bind functions of your plugin or system functions that provide dynamic content. this content is added to the configuration schema before applying it.

For more information about binding see: [json-binding]

Full configuration example

This example illustrate a configuration which use most of configuration items

"configurationSchema": {
       "intParameter" : {
          "type" : "int",
          "name" : "int parameter",
          "description" : "test of an int parameter",
          "defaultValue" : "0",
          "maximumValue" : "23"
       },
       "coefficient" : {
          "type" : "decimal",
          "name" : "coeff parameter",
          "description" : "test of an decimal parameter",
          "defaultValue" : "1.23",
          "maximumValue" : "2",
          "minimumValue" : "-2",
          "precision" : "2"
       },
       "timeFormat" : {
          "name" : "time format",
          "description" : "Permit to change the time format of the clock",
          "type" : "enum",
          "values" : {
             "12H" : "12 hours",
             "24H" : "24 hours"
          },
          "defaultValue" : "12H"
       },
       "prefixText" : {
          "name" : "String parameter",
          "description" : "A free text parameter",
          "type" : "string",
          "defaultValue" : "default value",
          "maximumLength" : "30"
       },
       "booleanParameter" : {
          "name" : "Enabled",
          "description" : "Permit to enable the widget",
          "type" : "bool",
          "defaultValue" : "true"
       },
       "advancedParameters" : {
          "type" : "section",
          "name" : "Advanced parameters",
          "description" : "For advanced users only",
          "enableWithCheckBox" : "true",
          "enableWithCheckBoxDefaultValue" : "false",
          "content" : {
             "booleanParameter" : {
                "type" : "bool",
                "name" : "enabled",
                "description" : "Permit to enable the widget",
                "defaultValue" : "true"
             },
             "CurrentCoefficient" : {
                "type" : "decimal",
                "name" : "correction coefficient",
                "description" : "Set a correction coefficient to adjust the value",
                "defaultValue" : "0.0",
                "maximumValue" : "1.0",
                "minimumValue" : "-1.0",
                "precision" : "2"
             }
          }
       }
    }