npm package: @iobroker/json-config
Description: This package contains the ioBroker JSON config UI components
Author: bluefox
Latest version: 8.3.4

# ioBroker JSON Configuration: A Guide for Beginners

This guide explains how to define configuration options for your ioBroker adapter using JSON. This approach offers a more user-friendly and flexible way to manage adapter settings within the ioBroker Admin interface.

## What you'll need

- ioBroker Admin version 6 (or newer)
- Basic understanding of JSON syntax

## Benefits of JSON Configuration

- Improved user experience for configuring adapters
- Easier integration of complex configuration options
- Clear separation between adapter code and configuration

## Getting Started

1. **Define the Configuration File:**

   - Create a file named `jsonConfig.json` or `jsonConfig.json5` in your adapter's admin directory.
   - JSON5 is a superset of JSON that allows for comments, making the configuration file more readable.

2. **Enable JSON Configuration:**

   - In your adapter's `io-package.json` file, add the following line under the `common` section:

   ```json
   {
       "common": {
           "adminUI": {
               "config": "json"
           }
       }
   }
   ```

3. **Structure of the Configuration File:**

   The configuration file defines a hierarchical structure of tabs, panels, and control elements. \
   Each element has specific attributes that determine its behavior and appearance in the Admin interface.

   jsonConfig automatically ensures that the collected data is recorded as configuration data for the adapter and stored internally so that it can be retrieved and further processed in the adapter.

   The following example would create the following configuration object:

```json5
{
  options1: {
    myPort: 1234,
    options: {
      myType: 1,
    },
    myBool: false,
  },
}
```

_If the attribute name starts with "\_", it will not be saved in the object._

## Example of a jsonConfig with multiple tabs

```json5
{
    "type": "tabs",
    "items": {
        "options1": {
            "type": "panel",
            "label": "Tab1",
            "icon": "base64 svg", // optional
            "items": {
                myPort: {
                    "type": "number",
                    "min": 1,
                    "max": 65565,
                    "label": "Number",
                    "sm": 6, // 1 - 12
                    "validator": "!!data.name", // else error
                    "hidden": "data.myType === 1", // hidden if myType is 1
                    "disabled": "data.myType === 2" // disabled if myType is 2
                },
                "options.myType": { // name could support more than one level
                    "newLine": true, // must start from new row
                    "type": "select",
                    "label": "Type",
                    "sm": 6, // 1 - 12
                    "options": [
                        {"label": "option 1", "value": 1},
                        {"label": "option 2", "value": 2}
                    ]
                },
                "myBool": {
                    "type": "checkbox",
                    "label": "My checkbox",
                },
                "_notSaved":"abc"
            }
        },
        "tab2": {
            "label": "Tab2",
            "type": "panel",
            "disabled": "data.myType === 1",
            "hidden": "data.myType === 2",
        }
    },
}
```

Further examples can be found in many other adapters on GitHub in the respective admin directory.

## Support for developing tools

### VS Code

To enable the validation of the jsonConfig in VS code, the following section must be added to the file ".vscode/settings.json".

```json5
    "json.schemas": [
        {
            "fileMatch": ["admin/jsonConfig.json", "admin/jsonCustom.json", "admin/jsonTab.json"],
            "url": "https://raw.githubusercontent.com/ioBroker/ioBroker.admin/master/packages/jsonConfig/schemas/jsonConfig.json"
        }
    ]
```

## Common Control Elements

A jsonConfig consists of several elements that are structured hierarchically. \
Each of the elements can be of one of the following types.\
Some elements can contain additional child elements.

You can see almost all components in action if you test this adapter: [jsonconfig-demo](https://github.com/mcm4iob/ioBroker.jsonconfig-demo).\
You can install it via GitHub icon in admin by entering `iobroker.jsonconfig-demo` on the npm tab.

- [**`accordion`:**](#accordion) Accordion element for collapsible content (Admin 6.6.0 or newer)
- [**`alive`:**](#alive) Displays if an instance is running (read-only)
- [**`autocomplete`:**](#autocomplete) Input field with autocomplete suggestions
- [**`autocompleteSendTo`:**](#autocompletesendto) Autocomplete control with instance values for sending data
- [**`certificate`:**](#certificate) Manages certificates for secure connections
- [**`certificateCollection`:**](#certificatecollection) Selects a collection for Let's Encrypt certificates
- [**`certificates`:**](#certificates) Universal type for managing different certificate types (from Admin 6.4.0)
- [**`checkbox`:**](#checkbox) Checkbox for boolean values
- [**`checkDocker`:**](#checkdocker) Special component to check if the docker available and if yes, you can activate a checkbox (from Admin 7.8.0)
- [**`checkLicense`:**](#checklicense) Very special component to check the license online
- [**`chips`:**](#chips) User can enter words that are added to an array
- [**`color`:**](#color) Color picker
- [**`coordinates`:**](#coordinates) Determines current location and used `system.config` coordinates if not possible in form `latitude,longitude`
- [**`cron`:**](#cron) Configures cron expressions for scheduling tasks
- [**`custom`:**](#custom) Integrates custom components for specific functionalities (Admin 6 only)
- [**`datePicker`:**](#datepicker) Allows users to select a date
- [**`deviceManager`:**](#devicemanager) show device manager
- [**`divider`:**](#divider) Creates a horizontal line separator
- [**`file`:**](#file) Input field with file selection and optional upload/download capabilities (Admin 6 only)
- [**`fileSelector`:**](#fileselector) Allows users to select files from the system (only Admin6)
- [**`func`:**](#func) Selects a function from the enum.func list (Admin 6 only)
- [**`header`:**](#header) Creates a heading with different sizes (h1-h5)
- [**`iframe`:**](#iframe) Show Iframe with given URL (admin >= 7.7.28)
- [**`iframeSendTo`:**](#iframe) Show Iframe with URL from backend (admin >= 7.7.28)
- [**`image`:**](#image) Uploads or displays an image
- [**`imageSendTo`:**](#imagesendto) Displays an image received from the backend and sends data based on a command
- [**`instance`:**](#instance) Selects an adapter instance
- [**`interface`:**](#interface) Selects the interface from of the host, where the instance runs
- [**`ip`:**](#ip) Input field for IP addresses with advanced options
- [**`jsonEditor`:**](#jsoneditor) JSON editor for complex configuration data
- [**`language`:**](#language) Selects the user interface language
- [**`license`:**](#license) shows the license information if not already accepted.
- [**`number`:**](#number) Numeric input field with min/max values and step size
- [**`oauth2`:**](#oauth2) Make OAuth2 authentication for the adapter (Admin 7.6.18 or newer)
- [**`objectId`:**](#objectid) Selects an object ID with name, color, and icon
- [**`panel`:**](#panel) Tab with items
- [**`password`:**](#password) Password input field
- [**`pattern`:**](#pattern) Read-only field showing a pattern (e.g., URL)
- [**`port`:**](#port) Special input for ports
- [**`qrCode`:**](#qrcode) Displays data as a QR code (Admin 7.0.18 or newer)
- [**`qrCodeSendTo`:**](#qrcodesendto) Displays a QR code with data received from the backend
- [**`room`:**](#room) Selects a room from the `enum.room` list (Admin 6 only)
- [**`select`:**](#select) Dropdown menu with predefined options
- [**`selectSendTo`:**](#selectsendto) Dropdown menu with instance values for sending data
- [**`sendTo`:**](#sendto) Button that sends a request to an instance
- [**`setState`:**](#setstate) Button that sets an instance's state
- [**`slider`:**](#slider) Slider for selecting a value within a range (Admin 6 only)
- [**`state`:**](#state) Show control or information from the state (admin >= 7.1.0)
- [**`staticImage`:**](#staticimage) Displays a static image
- [**`staticInfo`:**](#staticinfo) Shows static information in preformatted form, like "Title: value unit" (admin >= 7.3.3)
- [**`staticLink`:**](#staticlink) Creates a static link
- [**`staticText`:**](#statictext) Displays static text (e.g., description)
- [**`table`:**](#table) Table with rows that can be added, deleted, or reordered
- [**`tabs`:**](#tabs) Tabs with items
- [**`text`:**](#text) Single- or multi-line text input field
- [**`textSendTo`:**](#textsendto) Shows readonly control with the given from the instance values.
- [**`timePicker`:**](#timepicker) Allows users to select a time
- [**`user`:**](#user) Selects a user from the `system.user` list
- [**`uuid`:**](#uuid) Show iobroker UUID
- [**`yamlEditor`:**](#yamleditor) YAML editor for complex configuration data (admin >= 7.7.30)

By leveraging JSON configuration, you can create a user-friendly and \
adaptable configuration experience for your ioBroker adapter.

## Example projects

| Type              | Link                                                                                                                                                                                              |
|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Multiple Tabs:    | [`ioBroker.admin`](https://github.com/ioBroker/ioBroker.admin/blob/master/admin/jsonConfig.json5)                                                                                                 |
| Only one Panel:   | [`ioBroker.dwd`](https://github.com/ioBroker/ioBroker.dwd/blob/master/admin/jsonConfig.json)                                                                                                      |
| Custom component: | [`telegram`](https://github.com/iobroker-community-adapters/ioBroker.telegram/tree/master/src-admin) or in [`pushbullet`](https://github.com/Jens1809/ioBroker.pushbullet/tree/master/src-admin)  |
| Validation:       |                                                                                                                                                                                                   |

## Separation of the large Configurations

## Includes

Requires admin 6.17.1 or newer.

To write complex JSON files, you can include other JSON files.
The included file must be in the same directory as the main file.

```json5
{
  tabs: {
    tab1: {
      type: "panel", // data will be combined with the content of "tab1.json". If the same attribute is defined in both files, the value from the included file will be used.
      "#include": "tab1.json",
    },
  },
}
```

## i18n - Internationalization

There are several options to provide the translations. Only the first one is compatible with our Community Translation Tool Weblate, so it should be favored over the others!

To enable the translation feature, you need to provide and enable the i18n property at the top level of the JSON configuration object.

```json5
{
  i18n: true,
}
```

### Translation in separated files: compatible with weblate

By default, the files must be located in the following directories:

```text
admin/i18n/de/translations.json
admin/i18n/en/translations.json
```

or

```text
admin/i18n/de.json
admin/i18n/en.json
```

Additionally, user can provide the path to `i18n` files, `i18n`: `customI18n` and provide files in admin:

```json5
  "i18n": "customI18n",
```

```text
admin/customI18n/de/translations.json
admin/customI18n/en/translations.json
```

or

```text
admin/customI18n/de.json
admin/customI18n/en.json
```

The structure of a file corresponds to the following structure

**en.json:**

```json5
{
  i18nText1: "Open",
  i18nText2: "Close",
  "This is a Text": "This is a Text",
}
```

**de.json:**

```json5
{
  i18nText1: "Öffnen",
  i18nText2: "Schließen",
  "This is a Text": "Dies ist ein Text",
}
```

When searching for a translation, the information in the specific field is used to find the property with the text in the files. If the property is not found, the information from the field remains. It is recommended to enter the text in English.

### Provide translation directly in the fields

Translations can be specified in all fields that can contain text. Examples of fields are label, title, tooltip, text, etc.

```json5
   "type": "text",
   "label: {
        "en": "house",
        "de": "Haus"
    }
}
```

### Provide translation directly in the i18n

The translations can also be provided directly as an object in the `i18n` attribute at the top level of the `jsonConfig` object.

When searching for a translation, the information in the specific field is used to find the property with the text in the i18n object.
If the property is not found, the information from the field remains.
It is recommended to enter the text in English.

## Element types

Each element can have [common attributes](#common-attributes-of-controls) and the special attributes belonging to the respective type as follows

### `tabs`

Tabs with items

| Property        | Description                                                                                    |
|-----------------|------------------------------------------------------------------------------------------------|
| `items`         | Object with panels `{"tab1": {}, "tab2": {}...}`                                               |
| `iconPosition`  | `bottom`, `end`, `start` or `top`. Only for panels that has `icon` attribute. Default: `start` |
| `tabsStyle`     | CSS Styles in React format (`marginLeft` and not `margin-left`) for the Mui-Tabs component     |

### `panel`

Tab with items

| Property      | Description                                                                                                                             |
|---------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| `icon`        | tab can have icon (base64 like `data:image/svg+xml;base64,...`) or `jpg/png` images (ends with `.png`)                                  |
| `label`       | Label of tab                                                                                                                            |
| `items`       | Object `{"attr1": {}, "attr2": {}}...`                                                                                                  |
| `collapsable` | only possible as not part of tabs[jsonConfig.json](..%2F..%2F..%2F..%2F..%2FioBroker.ring%2Fadmin%2FjsonConfig.json)                    |
| `color`       | color of collapsable header `primary` or `secondary` or nothing                                                                         |
| `innerStyle`  | CSS Styles for inner div in React format (`marginLeft` and not `margin-left`) for the Panel component. Not used for collapsable panels. |

### `text`

Text component

| Property          | Description                                                                                            |
|-------------------|--------------------------------------------------------------------------------------------------------|
| `maxLength`       | max length of the text in field                                                                        |
| `readOnly`        | read-only field                                                                                        |
| `copyToClipboard` | show copy to clipboard button, but only if disabled or read-only is true                               |
| `trim`            | default is true. Set this attribute to `false` if trim is not desired.                                 |
| `minRows`         | default is 1. Set this attribute to `2` or more if you want to have a textarea with more than one row. |
| `maxRows`         | max rows of textarea. Used only if `minRows` > 1.                                                      |
| `noClearButton`   | if true, the clear button will not be shown (admin >= 6.17.13)                                         |
| `validateJson`    | if true, the text will be validated as JSON                                                            |
| `allowEmpty`      | if true, the JSON will be validated only if the value is not empty                                     |
| `time`            | the value is time in ms or a string. Used only with readOnly flag                                      |

### `number`

| Property | Description   | Remark         |          
|----------|---------------|----------------|
| `min`    | minimal value |                |
| `max`    | maximal value |                |
| `step`   | step          |                |
| `unit`   | unit          | admin >= 7.4.9 |

### `color`

color picker

| Property        | Description                                                    |
|-----------------|----------------------------------------------------------------|
| `noClearButton` | if true, the clear button will not be shown (admin >= 6.17.13) |

### `checkbox`

show checkbox

### `slider`

show slider (only Admin6)

| Property | Description                   |
|----------|-------------------------------|
| `min`    | (default 0)                   |
| `max`    | (default 100)                 |
| `step`   | (default `(max - min) / 100`) |
| `unit`   | Unit of slider                |

### `qrCode`

show data in a QR Code (admin >= 7.0.18)

| Property  | Description                           |
|-----------|---------------------------------------|
| `data`    | the data to be encoded in the QR Code |
| `size`    | size of the QR code                   |
| `fgColor` | Foreground color                      |
| `bgColor` | Background color                      |
| `level`   | QR code level (`L` `M` `Q` `H`)       |

### `ip`

bind address

| Property           | Description                       |
|--------------------|-----------------------------------|
| `listenOnAllPorts` | add 0.0.0.0 to option             |
| `onlyIp4`          | show only IP4 addresses           |
| `onlyIp6`          | show only IP6 addresses           |
| `noInternal`       | do not show internal IP addresses |

### `user`

lect user from system.user. (With color and icon)

| Property | Description     |
|----------|-----------------|
| `short`  | no system.user. |

### `room`

Select room from `enum.room` (With color and icon) - (only Admin6)

| Property          | Description              |
|-------------------|--------------------------|
| `short`           | no `enum.rooms.`         |
| `allowDeactivate` | allow letting room empty |

### `func`

Select function from `enum.func` (With color and icon) - (only Admin6)

| Property          | Description                       |
|-------------------|-----------------------------------|
| `short`           | no `enum.func.`                   |
| `allowDeactivate` | allow letting functionality empty |

### `select`

| Property        | Description                                                                                                    |
|-----------------|----------------------------------------------------------------------------------------------------------------|
| `options`       | object with labels, optional translations, optional grouping and values                                        |
| `multiple`      | Multiple choice select (From 7.6.5)                                                                            |
| `showAllValues` | show item even if no label was found for it (by multiple), default=`true`                                      |
| `format`        | Render format: `"dropdown"` (default) or `"radio"` to display options as radio buttons instead of a dropdown   |
| `horizontal`    | If `true`, radio buttons are shown horizontally (only applies when `format` is `"radio"`) (from v8.3.3)        |

Each option in `options` can have:

| Property      | Description                                                           |
|---------------|-----------------------------------------------------------------------|
| `label`       | Label of the option (can be a string or translatable object)          |
| `value`       | Value of the option                                                   |
| `color`       | Color of the option text                                              |
| `hidden`      | Formula or boolean value to show or hide the option                   |
| `description` | Description shown below the option label (can be translatable)        |
| `icon`        | Icon URL or base64 string to display next to the option (from v8.3.3) |

#### Example for `select options`

```json5
[
  {"label": {"en": "option 1"}, "value": 1}, //...
]
```
or
```json
[
   {
      "items": [
         {"label": "Val1", "value": 1},
         {"label": "Val2", "value": 2}
         ],
      "name": "group1"
   },
   {
      "items": [
         {"label": "Val3", "value": 3},
         {"label": "Val4", "value": 4}
      ],
      "name": "group2"
   },
   {"label": "Val5", "value": 5}
]
```

### `autocomplete`

| Property   | Description                                                                                                                      |
|------------|----------------------------------------------------------------------------------------------------------------------------------|
| `options`  | `["value1", "value2", ...]` or `[{"value": "value", "label": "Value1"}, "value2", ...]` (keys and names (values) must be unique) |
| `freeSolo` | Set `freeSolo` to `true`, so the textbox can contain any arbitrary value.                                                        |

### `image`

saves image as a file of the `adapter.X` object or as base64 in attribute

| Property     | Description                                                                                                                            |
|--------------|----------------------------------------------------------------------------------------------------------------------------------------|
| `filename`   | name of file is structure name. In the below example `login-bg.png` is file name for `writeFile("myAdapter.INSTANCE", "login-bg.png")` |
| `accept`     | html accept attribute, like `{ 'image/**': [], 'application/pdf': ['.pdf'] }`, default `{ 'image/*': [] }`                             |
| `maxSize`    | maximal size of file to upload                                                                                                         |
| `base64`     | if true the image will be saved as data-url in attribute, elsewise as binary in file storage                                           |
| `crop`       | if true, allow user to crop the image                                                                                                  |
| `!maxWidth`  |                                                                                                                                        |
| `!maxHeight` |                                                                                                                                        |
| `!square`    | width must be equal to height, or crop must allow only square as shape                                                                 |

#### Example for `image`

```json
  "login-bg.png": {
       "type": "image",
       "accept": "image/png",
       "label": {
         "en": "Upload image"
       },
       "crop": true
     },
     "picture": {
       "type": "image",
       "base64": true,
       "accept": "image/*",
       "label": {
         "en": "Upload image"
       },
       "crop": true
     }
  }
```

### `oauth2`
(admin >= 6.17.18)

Shows OAuth2 Authentication button to get the refresh and access tokens for the adapter.

To use this, you must first provide the OAuth2 data (client ID, secret, etc.) to ioBroker maintenance team, so they can add it to the cloud.

| Property       | Description                                                                                                                                                   |
|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `identifier`      | Oauth2 identifier, like `spotify`, `google`, `dropbox`, `microsoft`                                                                                           |
| `saveTokenIn`     | Optional state name where the token will be saved. Default is `oauth2Tokens`. The path is relative to the adapter instance, like `adapterName.X.oauth2Tokens` |
| `scope`           | Optional scopes divided by space, e.g. `user-read-private user-read-email`                                                                                    |
| `refreshLabel`    | Optional button label for refreshing the token                                                                                                                |
| `ownClientId`     | Optional attribute name where the user's own OAuth Client ID will be stored. If set, an input field for Client ID is shown                                    |
| `ownClientSecret` | Optional attribute name where the user's own OAuth Client Secret will be stored. If set, an input field for Client Secret is shown                             |

#### Example for `oauth2`

```json
  "_oauth2": {
       "type": "oauth2",
       "identifier": "spotify",
       "label": "Get Spotify OAuth2 Token",
       "refreshLabel": "Refresh Spotify OAuth2 Token",
       "icon": "data:image/svg+xml;base64,...",
  }
```
See also [OAUTH2.md](OAUTH2.md) for more information.

### `objectId`

object ID: show it with name, color and icon

| Property       | Description                                                                                                                                                                                                                                                                                                          |
|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `types`        | Desired type: `channel`, `device`, ... (has only `state` by default). It is plural, because `type` is already occupied.                                                                                                                                                                                              |
| `root`         | [optional] Show only this root object and its children                                                                                                                                                                                                                                                               |
| `customFilter` | [optional] Cannot be used together with `type` settings. It is an object and not a JSON string.                                                                                                                                                                                                                      |
| `filterFunc`   | [optional] Cannot be used together with `type` settings. It is a function that will be called for every object and must return true or false. Example: `obj.common.type === 'number'`                                                                                                                                |
| `fillOnSelect` | [optional] Fill other config fields when an object ID is selected. Format: `pathInObject=>attr,pathInObject=>attr(X)`. Append `(X)` to overwrite non-empty fields. Example: `common.name=>name,common.color=>color(X)` fills the `name` field with the object's name and overwrites `color` with the object's color. |

#### Examples for `customFilter`

##### show only objects with some custom settings

`{common: {custom: true}}`

##### show only objects with sql.0 custom settings (only of the specific instance)

`{common: {custom: 'sql.0'}}`

##### show only objects of adapters `influxdb` or `sql` or `history`

`{common: {custom: '_dataSources'}}`

##### show only objects of custom settings for a specific adapter (all instances)

`{common: {custom: 'adapterName.'}}`

##### show only channels

`{type: 'channel'}`

##### show only channels and devices

`{type: ['channel', 'device']}`

##### show only states of type 'number'

`{common: {type: 'number'}`

##### show only states of type 'number' and 'string'

`{common: {type: ['number', 'string']}`

##### show only states with roles starting from switch

`{common: {role: 'switch'}`

##### show only states with roles starting from `switch` and `button`

`{common: {role: ['switch', 'button']}`

### `password`

This field-type just has an effect on the UI.
Passwords and other sensitive data should be stored encrypted!
To do this, the key must be provided in the io-package.json under [nativeEncrypted](https://github.com/ioBroker/ioBroker.js-controller#automatically-encryptdecrypt-configuration-fields).
Additionally, you can protect this property from being served to other adapters but `admin` and `cloud` by adding it to `protectedNative` in `io-package.json` file.

| Property    | Description                                                                                             |
|-------------|---------------------------------------------------------------------------------------------------------|
| `repeat`    | repeat password must be compared with password                                                          |
| `visible`   | true if allow viewing the password by toggling the view button (only for a new password while entering) |
| `readOnly`  | the read-only flag. Visible is automatically true if readOnly is true                                   |
| `maxLength` | max length of the text in field                                                                         |

### `instance`

| Property          | Description                                                                                                                                                         |
|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `adapter`         | name of adapter. With special name `_dataSources` you can get all adapters with flag `common.getHistory`.                                                           |
| `adapters`        | optional list of adapters as array of strings, that should be shown. If not defined, all adapters will be shown. Only active if `adapter` attribute is not defined. |
| `allowDeactivate` | if true. Additional option "deactivate" is shown                                                                                                                    |
| `onlyEnabled`     | if true. Only enabled instances will be shown                                                                                                                       |
| `long`            | value will look like `system.adapter.ADAPTER.0` and not `ADAPTER.0`                                                                                                 |
| `short`           | value will look like `0` and not `ADAPTER.0`                                                                                                                        |
| `all`             | Add to the options "all" option with value `*`                                                                                                                      |

### `chips`

User can enter the word, and it will be added (see cloud => services => Whitelist). Output is an array if no `delimiter` defined.

| Property    | Description                                                                                                                                                           |
|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `delimiter` | if it is defined, so the option will be stored as string with delimiter instead of an array. E.g., by `delimiter=;` you will get `a;b;c` instead of `['a', 'b', 'c']` |

### `alive`

just indication if the instance is alive, and it could be used in "hidden" and "disabled" (will not be saved in config)

Just text: Instance is running, Instance is not running

| Property       | Description                                                                                                                         |
|----------------|-------------------------------------------------------------------------------------------------------------------------------------|
| `instance`     | check if the instance is alive. If not defined, it will be used current instance. You can use `${data.number}` pattern in the text. |
| `textAlive`    | default text is `Instance %s is alive`, where %s will be replaced by `ADAPTER.0`. The translation must exist in i18n files          |
| `textNotAlive` | default text is `Instance %s is not alive`, where %s will be replaced by `ADAPTER.0`. The translation must exist in i18n files      |

### `pattern`

The read-only field with a pattern like 'https://${data.ip}:${data.port}' (will not be saved in config)
Text input with the read-only flag, that shows a pattern.

| Property          | Description           |
|-------------------|-----------------------|
| `copyToClipboard` | if true - show button |
| `pattern`         | my pattern            |

### `sendTo`

Button that sends a request to the current instance (<https://github.com/iobroker-community-adapters/ioBroker.email/blob/master/admin/index_m.html#L128>)

| Property        | Description                                                                                                                                                                                                                                  |
|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `command`       | (Default `send`)                                                                                                                                                                                                                             |
| `jsonData`      | string - `"{\"subject1\": \"${data.subject}\", \"options1\": {\"host\": \"${data.host}\"}}"`. You can use special variables `data._origin` and `data._originIp` to send to instance the caller URL, like `http://127.0.0.1:8081/admin`.      |
| `data`          | object - `{"subject1": 1, "data": "static"}`. You can specify jsonData or data, but not both.                                                                                                                                                |
| `result`        | `{result1: {en: 'A'}, result2: {en: 'B'}}`                                                                                                                                                                                                   |
| `error`         | `{error1: {en: 'E'}, error2: {en: 'E2'}}`                                                                                                                                                                                                    |
| `variant`       | `contained`, `outlined` or nothing. Variant of button.                                                                                                                                                                                       |
| `openUrl`       | if true - open URL in new tab, if response contains attribute `openUrl`, like `{"openUrl": "http://1.2.3.4:80/aaa", "window": "_blank", "saveConfig": true}`. If `saveConfig` is true, the user will be requested to save the configuration. |
| `reloadBrowser` | if true - reload the current browser window, if response contains attribute `reloadBrowser`, like `{"reloadBrowser": true}`.                                                                                                                 |
| `window`        | if `openUrl` is true, this is a name of the new window. Could be overwritten if response consist `window` attribute. `this.props.socket.sendTo(adapterName.instance, command \|\| 'send', data, result => {});`                              |
| `icon`          | if icon should be shown: `auth`, `send`, `web`, `warning`, `error`, `info`, `search`. You can use `base64` icons (like `data:image/svg+xml;base64,...`) or `jpg/png` images (ends with `.png`). (Request via issue if you need more icons)   |
| `useNative`     | if adapter returns a result with `native` attribute it will be used for configuration. If `saveConfig` is true, the user will be requested to save the configuration.                                                                        |
| `showProcess`   | Show spinner while request is in progress                                                                                                                                                                                                    |
| `timeout`       | timeout for request in ms. Default: none.                                                                                                                                                                                                    |
| `onLoaded`      | execute the button logic once initially                                                                                                                                                                                                      |
| `controlStyle`  | Styles for the button.                                                                                                                                                                                                                       |

### `setState`

button that sets instance's state

| Property  | Description                                                                                                                       |
|-----------|-----------------------------------------------------------------------------------------------------------------------------------|
| `id`      | `system.adapter.myAdapter.%INSTANCE%.test`, you can use the placeholder `%INSTANCE%` to replace it with the current instance name |
| `ack`     | false (default false)                                                                                                             |
| `val`     | `${data.myText}\_test` or number. Type will be detected automatically from the state type and converting done too                 |
| `okText`  | Alert which will be shown by pressing the button                                                                                  |
| `variant` | `contained`, `outlined`, ''                                                                                                       |

### `staticText`

Static text like description

| Property | Description                                         |
|----------|-----------------------------------------------------|
| `label`  | multi-language text                                 |
| `text`   | same as label                                       |
| `format` | `text` (default), `html` (from admin version 7.8.4) |

exactly one of `label` or `text` must be specified - not both

### `staticLink`

| Property  | Description                                                                                                                                                                                                                                                                     |
|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `label`   | multi-language text                                                                                                                                                                                                                                                             |
| `href`    | link. Link could be dynamic like `#tab-objects/customs/${data.parentId}`                                                                                                                                                                                                        |
| `target`  | `_blank` or `_self` or window name                                                                                                                                                                                                                                              |
| `close`   | if true, the GUI will be closed (used not for JsonConfig in admin, but for dynamic GUI)                                                                                                                                                                                         |
| `button`  | show a link as button                                                                                                                                                                                                                                                           |
| `variant` | type of button (`outlined`, `contained`, `text`)                                                                                                                                                                                                                                |
| `color`   | color of button (e.g. `primary`)                                                                                                                                                                                                                                                |
| `icon`    | if icon should be shown: `auth`, `send`, `web`, `warning`, `error`, `info`, `search`, `book`, `help`, `upload`. You can use `base64` icons (it starts with `data:image/svg+xml;base64,...`) or `jpg/png` images (ends with `.png`) . (Request via issue if you need more icons) |

### `staticImage`

| Property                   | Description                                                                                  |
|----------------------------|----------------------------------------------------------------------------------------------|
| `href`                     | optional HTTP link                                                                           |
| `src`                      | name of picture (from admin directory)                                                       |
| `showInDialog`             | if true, a small thumbnail is shown and clicking it opens a dialog with the full-size image  |
| `showInDialogButtonLabel`  | if `showInDialog`, an optional label for a button that also opens the dialog                 |
| `showInDialogSmallSize`    | if `showInDialog`, the height of the small thumbnail in pixels (default 100)                 |

### `table`

table with items that could be deleted, added, moved up, moved down

| Property              | Description                                                                                                                                     |
|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| `items`               | `[{"type": see above, "width": px or %, "title": {"en": "header"}, "attr": "name", "filter": false, "sort": true, "default": ""}]`              |
| `noDelete`            | boolean if delete or add disabled, If `noDelete` is false, add, delete and move up/down should work                                             |
| `objKeyName`          | (legacy setting, don't use!) - name of the key in `{"192.168.1.1": {delay: 1000, enabled: true}, "192.168.1.2": {delay: 2000, enabled: false}}` |
| `objValueName`        | (legacy setting, don't use!) - name of the value in `{"192.168.1.1": "value1", "192.168.1.2": "value2"}`                                        |
| `allowAddByFilter`    | if add allowed even if filter is set                                                                                                            |
| `showSecondAddAt`     | Number of lines from which the second add button at the bottom of the table will be shown. Default 5                                            |
| `showFirstAddOnTop`   | Show first plus button on top of the first column and not on the left.                                                                          |
| `clone`               | [optional] - if clone button should be shown. If true, the clone button will be shown. If attribute name, this name will be unique.             |
| `export`              | [optional] - if export button should be shown. Export as csv file.                                                                              |
| `import`              | [optional] - if import button should be shown. Import from csv file.                                                                            |
| `uniqueColumns`       | [optional] - specify an array of columns, which need to have unique entries                                                                     |
| `encryptedAttributes` | [optional] - specify an array of columns, which should be encrypted                                                                             |
| `useCardFor`          | [optional] - Breakpoint that will be rendered as cards: ["xs", "sm", "md", "lg", "xl"]                                                          |
| `titleAttribute`      | [optional] - Define the name of the attribute of the item which should be shown as a title of the item in cards mode.                           |
| `compact`             | [optional] - if true, the table will be shown in a compact mode                                                                                 |

### `accordion`

accordion with items that could be deleted, added, moved up, moved down (Admin 6.6.0 and newer)

| Property    | Description                                                                                                                         |
|-------------|-------------------------------------------------------------------------------------------------------------------------------------|
| `items`     | `[{"type": see above, "attr": "name", "default": ""}]` items can be placed like on a `panel` (xs, sm, md, lg and newLine)           |
| `titleAttr` | key of the item's list which should be used as name                                                                                 |
| `noDelete`  | boolean if delete or add disabled, If `noDelete` is false, add, delete and move up/down should work                                 |
| `clone`     | [optional] - if clone button should be shown. If true, the clone button will be shown. If attribute name, this name will be unique. |

### `jsonEditor`

Button to open a JSON(5) editor. JSON5 is supported from admin version 5.7.3

| Property               | Description                                                                             |
|------------------------|-----------------------------------------------------------------------------------------|
| `validateJson`         | if false, the text will be not validated as JSON                                        |
| `allowEmpty`           | if true, the JSON will be validated only if the value is not empty                      |
| `json5`                | if JSON5 format allowed (From 7.5.3)                                                    |
| `doNotApplyWithError`  | Do not allow to save the value if error in JSON or JSON5 (From 7.5.3)                   |
| `readOnly`             | Open the editor in read-only mode - editor can be opened but content cannot be modified |

### `yamlEditor`

Button to open a YAML editor with syntax validation. (From admin version 7.7.30)

| Property               | Description                                                                             |
|------------------------|-----------------------------------------------------------------------------------------|
| `validateYaml`         | if false, the text will be not validated as YAML                                        |
| `allowEmpty`           | if true, the YAML will be validated only if the value is not empty                      |
| `doNotApplyWithError`  | Do not allow to save the value if error in YAML                                         |
| `readOnly`             | Open the editor in read-only mode - editor can be opened but content cannot be modified |

### `language`

select language

| Property | Description                                                                                                          |
|----------|----------------------------------------------------------------------------------------------------------------------|
| `system` | allow the usage of the system language from `system.config` as default (will have an empty string value if selected) |

### `certificate`

| Property   | Description                                                                            |
|------------|----------------------------------------------------------------------------------------|
| `certType` | on of: `public`, `private`, `chained`. But from 6.4.0 you can use `certificates` type. |

### `certificates`

it is a universal type that manages `certPublic`, `certPrivate`, `certChained` and `leCollection` attributes for you.
Example:

```json
{
  "_certs": {
    "type": "certificates",
    "newLine": true,
    "hidden": "!data.secure",
    "sm": 12
  }
}
```

### `certificateCollection`

select a certificate collection or just use all collections or don't use let's encrypt at all.

| Property           | Description                        |
|--------------------|------------------------------------|
| `leCollectionName` | name of the certificate collection |

### `custom`

only Admin6

| Property      | Description                                                                                                                    |
|---------------|--------------------------------------------------------------------------------------------------------------------------------|
| `name`        | Component name that will be provided via props, like `ComponentInstancesEditor`                                                |
| `url`         | Location of the component                                                                                                      |
| `i18n`        | true if `i18n/xx.json` files are located in the same directory as component, or translation object `{"text1": {"en": Text1"}}` |
| `bundlerType` | If module written with TypeScript, set it to `module`. From Admin 7.5.x                                                        |

#### Example for url

- `custom/customComponents.js`: in this case the files will be loaded from `/adapter/ADAPTER_NAME/custom/customComponents.js`
- `https://URL/myComponent`: direct from URL
- `./adapter/ADAPTER_NAME/custom/customComponent.js`: in this case the files will be loaded from `/adapter/ADAPTER_NAME/custom/customComponents.js`

### `datePicker`

allow the user to select a date input the UI format comes from the configured

### `timePicker`

allow the user to select a date input the returned string is a parseable date string or of format `HH:mm:ss`

| Property       | Description                                                                                          |
|----------------|------------------------------------------------------------------------------------------------------|
| `format`       | format passed to the date picker defaults to `HH:mm:ss`                                              |
| `views`        | Configure which views should be shown to the users. Defaults to `['hours', 'minutes', 'seconds']`    |
| `timeSteps`    | Represent the available time steps for each view. Defaults to `{ hours: 1, minutes: 5, seconds: 5 }` |
| `returnFormat` | `fullDate` or `HH:mm:ss`. Defaults to full date for backward compatibility reasons.                  |

### `divider`

horizontal line

| Property | Description                                      |
|----------|--------------------------------------------------|
| `height` | optional height                                  |
| `color`  | optional divider color or `primary`, `secondary` |

### `header`

| Property | Description  |
|----------|--------------|
| `text`   |              |
| `size`   | 1-5 => h1-h5 |

### `cron`

Shows CRON settings. You have 3 options:
- `simple` - shows simple CRON settings
- `complex` - shows CRON with "minutes", "seconds" and so on
- none of `simple` or `complex` - User can switch between simple and complex in the dialog

| Property  | Description                                   |
|-----------|-----------------------------------------------|
| `complex` | show CRON with "minutes", "seconds" and so on |
| `simple`  | show simple CRON settings                     |

### `fileSelector`
Select a file from one folder as a drop-down menu. And if you want, you can upload a new file to this folder.

only Admin6

| Property     | Description                                                                                                                                                                                              |
|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `pattern`    | File extension pattern. Allowed `**/*.ext` to show all files from subfolders too, `*.ext` to show from root folder or `folderName/*.ext` to show all files in sub-folder `folderName`. Default `**/*.*`. |
| `fileTypes`  | [optional] type of files: `audio`, `image`, `text`                                                                                                                                                       |
| `objectID`   | Object ID of type `meta`. You can use special placeholder `%INSTANCE%`: like `myAdapter.%INSTANCE%.files`                                                                                                |
| `upload`     | path, where the uploaded files will be stored. Like `folderName`. If not defined, no upload field will be shown. To upload in the root, set this field to `/`.                                           |
| `refresh`    | Show refresh button near the select.                                                                                                                                                                     |
| `maxSize`    | max file size (default 2MB)                                                                                                                                                                              |
| `withFolder` | show folder name even if all files in same folder                                                                                                                                                        |
| `delete`     | Allow deletion of files                                                                                                                                                                                  |
| `noNone`     | Do not show `none` option                                                                                                                                                                                |
| `noSize`     | Do not show size of files                                                                                                                                                                                |

### `file`
Input field with file selector. It will be shown as a text field with a button aside to open the dialog. 
only Admin6.

| Property            | Description                                                                              |
|---------------------|------------------------------------------------------------------------------------------|
| `disableEdit`       | if user can manually enter the file name and not only through select dialog              |
| `limitPath`         | limit selection to one specific object of type `meta` and following path (not mandatory) |
| `filterFiles`       | like `['png', 'svg', 'bmp', 'jpg', 'jpeg', 'gif']`                                       |
| `allowUpload`       | allowed upload of files                                                                  |
| `allowDownload`     | allowed download of files (default true)                                                 |
| `allowCreateFolder` | allowed creation of folders                                                              |
| `allowView`         | allowed tile view (default true)                                                         |
| `showToolbar`       | show toolbar (default true)                                                              |
| `selectOnlyFolders` | user can select only folders (e.g. for upload path)                                      |
| `trim`              | trim the file name                                                                       |

### `imageSendTo`

shows the image received from the backend as base64 string

| Property           | Description                                                                                                                                                 |
|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `width`            | width of QR code in px                                                                                                                                      |
| `height`           | height of QR code in px                                                                                                                                     |
| `command`          | sendTo command                                                                                                                                              |
| `jsonData`         | string - `{"subject1": "${data.subject}", "options1": {"host": "${data.host}"}}`. This data will be sent to backend                                         |
| `data`             | object - `{"subject1": 1, "data": "static"}`. You can specify jsonData or data, but not both. This data will be sent to backend if jsonData is not defined. |
| `sendFirstByClick` | show image first when clicked. `true` - standard text (Click to show) or specific text                                                                      |

#### Example of code in back-end for `imageSendTo`

```js
adapter.on("message", (obj) => {
  if (obj.command === "send") {
    const QRCode = require("qrcode");
    QRCode.toDataURL(
      "3ca4234a-fd81-fdb8-5584-08c732f70e4d",
      (err, url) =>
        obj.callback && adapter.sendTo(obj.from, obj.command, url, obj.callback)
    );
  }
});
```

### `qrCodeSendTo`

Sends a command to the adapter instance and displays the response string as a QR code.
The backend must return a plain string (the data to encode).

| Property           | Description                                                                                                                                                 |
|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `command`          | sendTo command (default: `"send"`)                                                                                                                          |
| `alsoDependsOn`    | array of attribute names — the QR code is refreshed whenever any of these attributes change                                                                 |
| `jsonData`         | string - `{"subject1": "${data.subject}", "options1": {"host": "${data.host}"}}`. This data will be sent to backend                                         |
| `data`             | object - `{"subject1": 1, "data": "static"}`. You can specify jsonData or data, but not both. This data will be sent to backend if jsonData is not defined. |
| `sendFirstByClick` | load QR code only after a click. `true` — standard text ("Click to show") or a custom string/translation object used as the button label                    |
| `size`             | size of the QR code in px                                                                                                                                   |
| `fgColor`          | foreground color (default: `"#000000"`)                                                                                                                     |
| `bgColor`          | background color (default: `"#ffffff"`)                                                                                                                     |
| `level`            | error correction level: `L`, `M`, `Q`, or `H` (default: `L`)                                                                                                |

#### Example of code in back-end for `qrCodeSendTo`

```js
adapter.on("message", (obj) => {
    if (obj.command === "send") {
        // return the string to be encoded in the QR code
        obj.callback && adapter.sendTo(obj.from, obj.command, "https://example.com/pair?token=abc123", obj.callback);
    }
});
```

### `iframe`

Shows an iframe with the specified URL. (from Admin 7.7.28)

| Property          | Description                                                                              |
|-------------------|------------------------------------------------------------------------------------------|
| `url`             | URL to display in the iframe. If defined, it will be static element                      |
| `allowFullscreen` | Allow fullscreen mode (default: `false`)                                                 |
| `sandbox`         | Sandbox attributes for security restrictions (e.g., `"allow-same-origin allow-scripts"`) |
| `loading`         | Lazy loading: `lazy` or `eager` (default: `lazy`)                                        |
| `frameBorder`     | Frame border width (default: `0`)                                                        |
| `reloadOnShow`    | Reload iframe when it becomes visible in the viewport                                    |

#### Example for `iframe`

```json
{
  "type": "iframe",
  "url": "https://example.com",
  "allowFullscreen": true,
  "sandbox": "allow-same-origin allow-scripts",
  "loading": "lazy",
  "reloadOnShow": false
}
```

### `iframeSendTo`

Shows an iframe with a URL received from the backend. (from Admin 7.7.28)

| Property   | Description                                                                                                                                                 |
|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `command`  | sendTo command                                                                                                                                              |
| `jsonData` | string - `{"subject1": "${data.subject}", "options1": {"host": "${data.host}"}}`. This data will be sent to backend                                         |
| `data`     | object - `{"subject1": 1, "data": "static"}`. You can specify jsonData or data, but not both. This data will be sent to backend if jsonData is not defined. |

The backend must return a URL as a string.

#### Example for `iframeSendTo`

```json
{
  "type": "iframeSendTo",
  "command": "getUrl",
  "jsonData": "{\"param\": \"${data.value}\"}",
  "height": 600
}
```

#### Example of code in