Technical details for config panel structure and form option types

Doc auto-generated by this script on 02/04/2025 (YunoHost version 12.1.4)

Glossary

You may encounter some named types which are used for simplicity.

Translation: a translated property
- used for properties: ask, help and Pattern.error
- a dict with locales as keys and translations as values:
```
ask.en = "The text in english"
ask.fr = "Le texte en français"
```
  It is not currently possible for translators to translate those string in weblate.
- a single str for a single english default string
```
help = "The text in english"
```
JSExpression: a str JS expression to be evaluated to true or false:
- used for properties: visible and enabled
- operators availables: ==, !=, >, >=, <, <=, !, &&, ||, +, -, *, /, % and match()
Binding: bind a value to a file/property/variable/getter/setter/validator
- save the value in settings.yaml when not defined
- nothing at all with "null"
- a custom getter/setter/validator with "null" + a function starting with get__, set__, validate__ in scripts/config
- a variable/property in a file with :__FINALPATH__/my_file.php
- a whole file with __FINALPATH__/my_file.php

Pattern: a dict with a regex to match the value against and an error message

pattern.regexp = '^[A-F]\d\d$'
pattern.error = "Provide a room number such as F12: one uppercase and 2 numbers"
# or with translated error
pattern.error.en = "Provide a room number such as F12: one uppercase and 2 numbers"
pattern.error.fr = "Entrez un numéro de salle comme F12: une lettre majuscule et deux chiffres."

IMPORTANT: your pattern.regexp should be between simple quote, not double.

Configuration panel structure

ConfigPanel

This is the 'root' level of the config panel toml file

Examples

version = 1.0

[config]
# …refer to Panels doc

Properties

version: float (default: 1.0), version that the config panel supports in terms of features.
i18n (optional): str, an i18n property that let you internationalize options text.
- However this feature is only available in core configuration panel (like yunohost domain config), prefer the use Translation in name, help, etc.

Panel

Panels are, basically, sections grouped together. Panels are dicts defined inside a ConfigPanel file and require a unique id (in the below example, the id is main). Keep in mind that this id will be used in CLI to refer to the panel, so choose something short and meaningfull.

Examples

[main]
name.en = "Main configuration"
name.fr = "Configuration principale"
help = ""
services = ["__APP__", "nginx"]

    [main.customization]
    # …refer to Sections doc

Properties

name: Translation or str, displayed as the panel title
help (optional): Translation or str, text to display before the first section
services (optional): list of services names to reload-or-restart when any option's value contained in the panel changes
- "__APP__ will refer to the app instance name
actions: FIXME not sure what this does

Section

Sections are, basically, options grouped together. Sections are dicts defined inside a Panel and require a unique id (in the below example, the id is customization prepended by the panel's id main). Keep in mind that this combined id will be used in CLI to refer to the section, so choose something short and meaningfull. Also make sure to not make a typo in the panel id, which would implicitly create an other entire panel.

If at least one button is present it then become an action section. Options in action sections are not considered settings and therefor are not saved, they are more like parameters that exists only during the execution of an action. FIXME i'm not sure we have this in code.

Examples

[main]

    [main.customization]
    name.en = "Advanced configuration"
    name.fr = "Configuration avancée"
    help = "Every form items in this section are not saved."
    services = ["__APP__", "nginx"]

        [main.customization.option_id]
        type = "string"
        # …refer to Options doc

Properties

name (optional): Translation or str, displayed as the section's title if any
help: Translation or str, text to display before the first option
services (optional): list of services names to reload-or-restart when any option's value contained in the section changes
- "__APP__ will refer to the app instance name
optional: bool (default: true), set the default optional prop of all Options in the section
visible: bool or JSExpression (default: true), allow to conditionally display a section depending on user's answers to previous questions.
- Be careful that the visible property should only refer to previous options's value. Hence, it should not make sense to have a visible property on the very first section.

List of all option types

Common properties

Options are fields declaration that renders as form items, button, alert or text in the web-admin and printed or prompted in CLI. They are used in app manifests to declare the before installation form and in config panels.

Have a look at the app config panel doc for details about Panels and Sections.

! IMPORTANT: as for Panels and Sections you have to choose an id, but this one should be unique in all this document, even if the question is in an other panel.

Example

[section.my_option_id]
type = "string"
# ask as `str`
ask = "The text in english"
# ask as `dict`
ask.en = "The text in english"
ask.fr = "Le texte en français"
# advanced props
visible = "my_other_option_id != 'success'"
readonly = true
# much advanced: config panel only?
bind = "null"

Properties

type: the actual type of the option, such as 'markdown', 'password', 'number', 'email', ...
ask: Translation (default to the option's id if not defined):
- text to display as the option's label for inputs or text to display for readonly options
- in config panels, questions are displayed on the left side and therefore have not much space to be rendered. Therefore, it is better to use a short question, and use the help property to provide additional details if necessary.
visible (optional): bool or JSExpression (default: true)
- define if the option is diplayed/asked
- if false and used alongside readonly = true, you get a context only value that can still be used in JSExpressions
readonly (optional): bool (default: false, forced to true for readonly types):
- If true for input types: forbid mutation of its value
bind (optional): Binding, config panels only! A powerful feature that let you configure how and where the setting will be read, validated and written
- if not specified, the value will be read/written in the app settings.yml
- if "null":
  - the value will not be stored at all (can still be used in context evaluations)
  - if in scripts/config there's a function named:
    - get__my_option_id: the value will be gathered from this custom getter
    - set__my_option_id: the value will be passed to this custom setter where you can do whatever you want with the value
    - validate__my_option_id: the value will be passed to this custom validator before any custom setter
- if bind is a file path:
  - if the path starts with :, the value be saved as its id's variable/property counterpart
    - this only works for first level variables/properties and simple types (no array)
  - else the value will be stored as the whole content of the file
  - you can use __FINALPATH__ or __INSTALL_DIR__ in your path to point to dynamic install paths
    - FIXME are other global variables accessible?
- refer to bind doc for explaination and examples

Common inputs properties

Rest of the option types available are considered inputs.

Example

[section.my_option_id]
type = "string"
# …any common props… +
optional = false
redact = false
default = "some default string"
help = "You can enter almost anything!"
example = "an example string"
placeholder = "write something…"

Properties

common properties
optional: bool (default: false, but true in config panels)
redact: bool (default: false), to redact the value in the logs when the value contain private information
default: depends on type, the default value to assign to the option
- in case of readonly values, you can use this default to assign a value (or return a dynamic default from a custom getter)
help (optional): Translation, to display a short help message in cli and web-admin
example (optional): str, to display an example value in web-admin only
placeholder (optional): str, shown in the web-admin fields only

`markdown` (readonly)

Display markdown multi-line content. Markdown is currently only rendered in the web-admin

Example

[section.my_option_id]
type = "display_text"
ask = "Text **rendered** in markdown."

Properties

common properties

`alert` (readonly)

Alerts displays a important message with a level of severity. You can use markdown in ask but will only be rendered in the web-admin.

Example

[section.my_option_id]
type = "alert"
ask = "The configuration seems to be manually modified..."
style = "warning"
icon = "warning"

Properties

common properties
style: any of "success|info|warning|danger" (default: "info")
icon (optional): any icon name from Fork Awesome
- Currently only displayed in the web-admin

`button` (readonly)

Triggers actions. Available only in config panels. Renders as a button in the web-admin and can be called with yunohost [app|domain|settings] action run <action_id> in CLI.

Every options defined in an action section (a config panel section with at least one button) is guaranted to be shown/asked to the user and available in scripts/config's scope. check examples in advanced use cases.

Example

[section.my_option_id]
type = "button"
ask = "Break the system"
style = "danger"
icon = "bug"
# enabled only if another option's value (a `boolean` for example) is positive
enabled = "aknowledged"

To be able to trigger an action we have to add a bash function starting with run__ in your scripts/config

run__my_action_id() {
    ynh_print_info "Running 'my_action_id' action"
}

Properties

common properties
- bind: forced to "null"
style: any of "success|info|warning|danger" (default: "success")
enabled: JSExpression or bool (default: true)
- when used with JSExpression you can enable/disable the button depending on context
icon (optional): any icon name from Fork Awesome
- Currently only displayed in the web-admin

`string` (string)

Ask for a simple string.

Example

[section.my_option_id]
type = "string"
default = "E10"
pattern.regexp = '^[A-F]\d\d$'
pattern.error = "Provide a room like F12 : one uppercase and 2 numbers"

Properties

common inputs properties
- default: ""
pattern (optional): Pattern, a regex to match the value against

`text` (string)

Ask for a multiline string. Renders as a textarea in the web-admin and by opening a text editor on the CLI.

Example

[section.my_option_id]
type = "text"
default = "multi\nline\ncontent"

Properties

common inputs properties
- default: ""
pattern (optional): Pattern, a regex to match the value against

`password` (input)

Ask for a password. The password is tested as a regular user password (at least 8 chars)

Example

[section.my_option_id]
type = "password"

Properties

common inputs properties
- default: forced to ""
- redact: forced to true
- example: forbidden

`color` (input)

Ask for a color represented as a hex value (with possibly an alpha channel). Renders as color picker in the web-admin and as a prompt that accept named color like yellow in CLI.

Example

[section.my_option_id]
type = "color"
default = "#ff0"

Properties

common inputs properties
- default: ""

`number` (input)

Ask for a number (an integer).

Example

[section.my_option_id]
type = "number"
default = 100
min = 50
max = 200
step = 5

Properties

common inputs properties
- type: number or range (input or slider in the web-admin)
min (optional): minimal int value inclusive
max (optional): maximal int value inclusive
step (optional): currently only used in the webadmin as the <input/> step jump

`boolean` (input)

Ask for a boolean. Renders as a switch in the web-admin and a yes/no prompt in CLI.

Example

[section.my_option_id]
type = "boolean"
default = 1
yes = "agree"
no = "disagree"

Properties

common inputs properties
- default: 0
yes (optional): (default: 1) define as what the thruthy value should output
- can be true, True, "yes", etc.
no (optional): (default: 0) define as what the thruthy value should output
- can be 0, "false", "n", etc.

`date` (input)

Ask for a date in the form "2025-06-14". Renders as a date-picker in the web-admin and a regular prompt in CLI.

Can also take a timestamp as value that will output as an ISO date string.

Example

[section.my_option_id]
type = "date"
default = "2070-12-31"

Properties

common inputs properties
- default: ""

`time` (input)

Ask for an hour in the form "22:35". Renders as a date-picker in the web-admin and a regular prompt in CLI.

Example

[section.my_option_id]
type = "time"
default = "12:26"

Properties

common inputs properties
- default: ""

`email` (input)

Ask for an email. Validation made with python-email-validator

Example

[section.my_option_id]
type = "email"
default = "Abc.123@test-example.com"

Properties

common inputs properties
- default: ""

`path` (string)

Ask for an web path (the part of an url after the domain). Used by default in app install to define from where the app will be accessible.

Example

[section.my_option_id]
type = "path"
default = "/"

Properties

common inputs properties
- default: ""
pattern (optional): Pattern, a regex to match the value against

`url` (string)

Ask for any url.

Example

[section.my_option_id]
type = "url"
default = "https://example.xn--zfr164b/@handle/"

Properties

common inputs properties
- default: ""
pattern (optional): Pattern, a regex to match the value against

`file` (input)

Ask for file. Renders a file prompt in the web-admin and ask for a path in CLI.

Example

[section.my_option_id]
type = "file"
accept = ".json"
# bind the file to a location to save the file there
bind = "/tmp/my_file.json"

Properties

common inputs properties
- default: ""
accept: a comma separated list of extension to accept like ".conf, .ini
- /!\ currently only work on the web-admin

`select` (choices)

Ask for value from a limited set of values. Renders as a regular <select/> in the web-admin and as a regular prompt in CLI with autocompletion of choices.

Example

[section.my_option_id]
type = "select"
choices = ["one", "two", "three"]
choices = "one,two,three"
default = "two"

Properties

common inputs properties
- default: "", obviously the default has to be empty or an available choices item.
choices: a (coma separated) list of values

`tags` (choices)

Ask for series of values. Optionally from a limited set of values. Renders as a multi select in the web-admin and as a regular prompt in CLI without autocompletion of choices.

This output as a coma separated list of strings "one,two,three"

Example

[section.my_option_id]
type = "tags"
default = "word,another word"

[my_other_option_id]
type = "tags"
choices = ["one", "two", "three"]
# choices = "one,two,three"
default = "two,three"

Properties

common inputs properties
- default: "", obviously the default has to be empty or an available choices item.
pattern (optional): Pattern, a regex to match all the values against
choices (optional): a (coma separated) list of values
icon (optional): any icon name from Fork Awesome
- Currently only displayed in the web-admin

`domain` (choices)

Ask for a user domain. Renders as a select in the web-admin and as a regular prompt in CLI with autocompletion of registered domains.

Example

[section.my_option_id]
type = "domain"

Properties

common inputs properties
- default: forced to the instance main domain

`app` (choices)

Ask for a user app. Renders as a select in the web-admin and as a regular prompt in CLI with autocompletion of installed apps.

Example

[section.my_option_id]
type = "app"
filter = "is_webapp"

Properties

common inputs properties
- default: ""
filter (optional): JSExpression with what yunohost app info <app_id> --full returns as context (only first level keys)

`user` (choices)

Ask for a user. Renders as a select in the web-admin and as a regular prompt in CLI with autocompletion of available usernames.

Example

[section.my_option_id]
type = "user"

Properties

common inputs properties
- default: the first admin user found

`group` (choices)

Ask for a group. Renders as a select in the web-admin and as a regular prompt in CLI with autocompletion of available groups.

Example

[section.my_option_id]
type = "group"
default = "visitors"

Properties

common inputs properties
- default: "all_users", "visitors" or "admins" (default: "all_users")

Glossary​

Configuration panel structure​

ConfigPanel​

Examples​

Properties​

Panel​

Examples​

Properties​

Section​

Examples​

Properties​

List of all option types​

Common properties​

Example​

Properties​

Common inputs properties​

Example​

Properties​

markdown (readonly)​

Example​

Properties​

alert (readonly)​

Example​

Properties​

button (readonly)​

Example​

Properties​

string (string)​

Example​

Properties​

text (string)​

Example​

Properties​

password (input)​

Example​

Properties​

color (input)​

Example​

Properties​

number (input)​

Example​

Properties​

boolean (input)​

Example​

Properties​

date (input)​

Example​

Properties​

time (input)​

Example​

Properties​

email (input)​

Example​

Properties​

path (string)​

Example​

Properties​

url (string)​

Example​

Properties​

file (input)​

Example​

Properties​

select (choices)​

Example​

Properties​

tags (choices)​

Example​

Properties​

domain (choices)​

Example​

Properties​

app (choices)​

Example​

Properties​

user (choices)​

Example​

Properties​

group (choices)​

Example​

Glossary

Configuration panel structure

ConfigPanel

Examples

Properties

Panel

Examples

Properties

Section

Examples

Properties

List of all option types

Common properties

Example

Properties

Common inputs properties

Example

Properties

`markdown` (readonly)

Example

Properties

`alert` (readonly)

Example

Properties

`button` (readonly)

Example

Properties

`string` (string)

Example

Properties

`text` (string)

Example

Properties

`password` (input)

Example

Properties

`color` (input)

Example

Properties

`number` (input)

Example

Properties

`boolean` (input)

Example

Properties

`date` (input)

Example

Properties

`time` (input)

Example

Properties

`email` (input)

Example

Properties

`path` (string)

Example

Properties

`url` (string)

Example

Properties

`file` (input)

Example

Properties

`select` (choices)

Example

Properties

`tags` (choices)

Example

Properties

`domain` (choices)

Example

Properties

`app` (choices)

Example

Properties

`user` (choices)

Example

Properties

`group` (choices)

Example