From ecbda6efba37443d224b7d5be8406b04f561b7b2 Mon Sep 17 00:00:00 2001 From: ljf Date: Mon, 21 Aug 2023 00:50:20 +0200 Subject: [PATCH] [fix] Config panel doc --- .../20.config_panels/config_panels.md | 56 +++++++++++-------- pages/06.contribute/15.dev/03.forms/forms.md | 15 +++-- 2 files changed, 44 insertions(+), 27 deletions(-) diff --git a/pages/06.contribute/10.packaging_apps/60.advanced/20.config_panels/config_panels.md b/pages/06.contribute/10.packaging_apps/60.advanced/20.config_panels/config_panels.md index c88a866c..f9e4cac3 100644 --- a/pages/06.contribute/10.packaging_apps/60.advanced/20.config_panels/config_panels.md +++ b/pages/06.contribute/10.packaging_apps/60.advanced/20.config_panels/config_panels.md @@ -14,14 +14,14 @@ Those panels could aslo be used as interface generator to extend quickly capabil ! Please: Keep in mind the YunoHost spirit, and try to build your panels in such a way as to expose only really useful parameters, and if there are many of them, to relegate those corresponding to rarer use cases to "Advanced" sub-sections. -## How does config_panel.toml work +## How does `config_panel.toml` work Basically, configuration panels for apps uses at least a `config_panel.toml` at the root of your package. For advanced usecases, this TOML file could also be paired with a `config` script inside the scripts directory of your package. The `config_panel.toml` file describes one or several panels, containing some sections, containing some questions generally binded to a params in a configuration file. We supposed we have an upstream app with this simple config.yml file: -``` +```yaml title: 'My dummy apps' theme: 'white' max_rate: 10 @@ -29,7 +29,7 @@ max_age: 365 ``` We could for example create a simple configuration panel for it like this one, by following the syntax `\[PANEL.SECTION.QUESTION\]`: -``` +```toml version = "1.0" [main] @@ -63,7 +63,7 @@ Here we have created one `main` panel, containing the `main` and `limits` sectio For performance reasons, questions short keys should be unique in all the `config_panel.toml` file, not just inside its panel or its section. So you can't have -``` +```toml [manual.vpn.server_ip] [advanced.dns.server_ip] ``` @@ -87,12 +87,12 @@ If you have not defined a specific getter/setter (see bellow), and without `bind If you want to read and save the value into a variable (called like the option name) of a file (json, yaml, ini, php, py ...) you can do: -``` +```toml bind = ":__INSTALL_DIR__/config.yml" ``` If you want to read and save the value into an other variable than the `config_panel.toml` question short key (email in the example) of a file (json, yaml, ini, php, py ...) you can do: -``` +```toml bind = "email:__FINALPATH__/config.yml" ``` @@ -100,14 +100,14 @@ bind = "email:__FINALPATH__/config.yml" Sometimes, you want to read and save a value in a variable name that appears several time in the configuration file (for example variables called `max`). The `bind` property allows you to change the value on the variable following a regex in a the file: -``` +```toml bind = "importExportRateLimiting>max:__INSTALL_DIR__/conf.json" ``` #### Read / write an entire file If you have a question of type file or text you could want to save the content into a specific path on the system. -``` +```toml bind = "__INSTALL_DIR__/img/logo.png" ``` @@ -125,6 +125,19 @@ For all of those use cases, there are the specific getter or setter mechanism fo To create specific getter / setter, you first need to create a `config` script inside the `scripts` directory +scripts/config +```bash +#!/bin/bash +source /usr/share/yunohost/helpers + +ynh_abort_if_errors + +# Put your getter, setter and validator here + +# Keep this last line +ynh_app_config_run $1 +``` + #### Getter A getter is a bash function called `getter_QUESTION_SHORT_KEY()` which returns data through stdout. @@ -135,7 +148,7 @@ Returns could have 2 formats: [details summary="Basic example : Get the login inside the first line of a file " class="helper-card-subtitle text-muted"] scripts/config -``` +```bash get__login_user() { if [ -s /etc/openvpn/keys/credentials ] then @@ -147,7 +160,7 @@ get__login_user() { ``` config_panel.toml -``` +```toml [main.auth.login_user] ask = "Username" type = "string" @@ -156,14 +169,14 @@ type = "string" [details summary="Advanced example 1 : Display a list of available plugins" class="helper-card-subtitle text-muted"] scripts/config -``` +```bash get__plugins() { echo "choices: [$(ls $install_dir/plugins/ | tr '\n' ',')]" } ``` config_panel.toml -``` +```toml [main.plugins.plugins] ask = "Plugin to activate" type = "tags" @@ -173,7 +186,7 @@ config_panel.toml [details summary="Example 2 : Display the status of a VPN" class="helper-card-subtitle text-muted"] scripts/config -``` +```bash get__status() { if [ -f "/sys/class/net/tun0/operstate" ] && [ "$(cat /sys/class/net/tun0/operstate)" == "up" ] then @@ -193,7 +206,7 @@ EOF ``` config_panel.toml -``` +```toml [main.cube.status] ask = "Custom getter alert" type = "alert" @@ -210,7 +223,7 @@ You probably should use `ynh_print_info` in order to display info for user about [details summary="Basic example : Set the login into the first line of a file " class="helper-card-subtitle text-muted"] scripts/config -``` +```bash set__login_user() { if [ -z "${login_user}" ] then @@ -221,7 +234,7 @@ set__login_user() { ``` config_panel.toml -``` +```toml [main.auth.login_user] ask = "Username" type = "string" @@ -232,13 +245,13 @@ type = "string" You will often need to validate data answered by the user before to save it somewhere. Validation can be made with regex through `pattern` argument -``` +```toml pattern.regexp = '^.+@.+$' pattern.error = 'An email is required for this field' ``` You can also restrict several types with a choices list. -``` +```toml choices.option1 = "Plop1" choices.option2 = "Plop2" choices.option3 = "Plop3" @@ -249,11 +262,10 @@ Some other type specific argument exist like | ----- | --------------------------- | | `number`, `range` | `min`, `max`, `step` | | `file` | `accept` | -| `tags` | `limit` | | `boolean` | `yes` `no` | Finally, if you need specific or multi variable validation, you can use custom validators function: -``` +```bash validate__login_user() { if [[ "${#login_user}" -lt 4 ]]; then echo 'Too short user login'; fi } @@ -265,7 +277,7 @@ validate__login_user() { You can use the services key to specify which service need to be reloaded or restarted -``` +```toml services = [ 'nginx', '__APP__' ] ``` @@ -275,7 +287,7 @@ This argument could be on panel, section, or question. All main configuration helpers are overwritable, example: -``` +```bash ynh_app_config_apply() { # Stop vpn client diff --git a/pages/06.contribute/15.dev/03.forms/forms.md b/pages/06.contribute/15.dev/03.forms/forms.md index 1781565c..b7cdd191 100644 --- a/pages/06.contribute/15.dev/03.forms/forms.md +++ b/pages/06.contribute/15.dev/03.forms/forms.md @@ -18,18 +18,18 @@ YunoHost uses a lot of forms. You can found here information on supported types | Property | Scope | Description | Example | |----------|--------------|-------------|---------| -| `type` | Everywhere | Specify the type of the question (see bellow for the list) | | +| `type` | Everywhere | Specify the type of the question (see bellow for the list) | `type = "string"` | | `ask` | Everywhere | The title of the question | `ask.en = "Cats or dogs ?"` | | `help` | Everywhere | An help message | `help.en = "Think carefully!"` | | `optional`| Everywhere | Set true if the question is not mandatory | `optional = true` | | `readonly`| Everywhere | Avoid user to be able to change the value | `readonly = true` | -| `example` | Everywhere | Give an example to help to understand the format of the answer|| -| `pattern.regexp` | Everywhere | Regex to validate the new value|| -| `pattern.error` | Everywhere | Error to display if the pattern doesn't match || +| `example` | Everywhere | Give an example to help to understand the format of the answer| `example = "camille@example.com"` | +| `pattern.regexp` | Everywhere | Regex to validate the new value| `pattern.regexp = "^.+@.+$"` | +| `pattern.error` | Everywhere | Error to display if the pattern doesn't match | | | `redact` | Everywhere | Avoid a confidential value to be logged | `redact = true` | | `default` | Install | A default value for the question | | | `visible` | ConfigPanel | A simple js expression based on other short keys questions to hide or display dynamically the question| `visible = "login && ! private_key"` | -| `bind` | AppConfigPanel | See [App configuration panel doc](/packaging_config_panels) | +| `bind` | AppConfigPanel | See [App configuration panel doc](/packaging_config_panels) | `bind = "__INSTALL_DIR__/config.yml"` | * `help`, `optional`, `readonly` and `visible` are also available on panels and sections entities. * Long help messages could not to be correctly displayed for user using yunohost CLI @@ -110,6 +110,7 @@ By default it ask for a web URL but you can change the `pattern` if you want to. ### `file` File question + | Property | Description | Example | |----------|--------------|---------| | `accept` | Same format than HTML file input | | @@ -117,11 +118,15 @@ File question ! This file type is not made for big files transfer, it's just for small logo, or config files. ### `select` +Dropdown + | Property | Description | Example | |----------|--------------|---------| | `choices` | list or dictionary of choices | | ### `tags` +Multi choices selection. + | Property | Description | Example | |----------|--------------|---------| | `choices` | List or dictionary of choices | |