YunoHost/doc
1
0
Fork 0
mirror of https://github.com/YunoHost/doc.git synced 2024-09-03 20:06:26 +02:00
Code Issues Projects Releases Packages Wiki Activity

Merge branch 'YunoHost:master' into master

Browse source
This commit is contained in:
Leandro Noferini 2023-09-02 18:05:31 +02:00 committed by GitHub
commit 2f4f1b13ef
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
10 changed files with 527 additions and 31 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
pages/02.administer/15.admin_guide/20.users/05.groups_and_permissions/groups_and_permissions.fr.md
View file

@ -87,10 +87,10 @@ Pour supprimer un utilisateur, cliquez sur la croix à côté de son nom d'utili
En ligne de commande, utilisez la commande suivante pour ajouter `charlie` et `delphine` au groupe `yolo_crew` :
```shell
$ yunohost user group update yolo_crew --add charlie delphine
$ yunohost user group add yolo_crew charlie delphine
```
(De même, `--remove` peut être utilisé pour retirer des membres d'un groupe.)
(De même, `remove` peut être utilisé pour retirer des membres d'un groupe.)
Dans la liste des groupes, nous devrions voir :
@ -260,4 +260,4 @@ $ yunohost user group info admins
Il est possible de les ajouter avec l'action `add-mailalias` ou de les enlever avec `remove-mailalias`.
```shell
$ yunohost user group add-mailalias <groupe> <adresse@domaine.tld>
```
```

6
pages/02.administer/15.admin_guide/20.users/05.groups_and_permissions/groups_and_permissions.md
View file

@ -90,10 +90,10 @@ To remove a user, click on the cross next to their username, in the group panel.
In CLI, use the following command to add `charlie` and `delphine`to the `yolo_crew` group:
```shell
$ yunohost user group update yolo_crew --add charlie delphine
$ yunohost user group add yolo_crew charlie delphine
```
(similarly, `--remove` can be used to remove members from a group)
(similarly, `remove` can be used to remove members from a group)
Now in the group list we should see:
@ -260,4 +260,4 @@ $ yunohost user group info admins
To add a new mail, use the action `add-mailalias` or `remove-mailalias` to delete it.
```shell
$ yunohost user group add-mailalias <group> <address@domaine.tld>
```
```

2
pages/02.administer/55.providers/05.registrar/gandi/autodns.md
View file

@ -13,7 +13,7 @@ This page is meant to guide you in obtaining an API key from Gandi in order to c
! NB. : **DO NOT share your API tokens with anybody!** A malicious attacker obtaining your tokens could take over your domain, and possibly your server!
1. Go to https://account.gandi.net/
1. Go to [https://account.gandi.net/](https://account.gandi.net/)
2. You should land on this page. Then click on 'Security'

2
pages/04.applications/10.docs/homeassistant/app_homeassistant.md
View file

@ -22,7 +22,7 @@ routes:
## Useful links
+ Website: [homeassistant.eu (en)](https://homeassistant.eu/site/)
+ Website: [home-assistant.io (en)](https://www.home-assistant.io/)
+ Demonstration: [Demo](https://demo.home-assistant.io/#/lovelace/0)
+ Application software repository: [github.com - YunoHost-Apps/homeassistant](https://github.com/YunoHost-Apps/homeassistant_ynh)
+ Fix a bug or an improvement by creating a ticket (issue): [github.com - YunoHost-Apps/homeassistant/issues](https://github.com/YunoHost-Apps/homeassistant_ynh/issues)

4
pages/04.applications/99.wishlist/apps_wishlist.md
View file

@ -98,7 +98,6 @@ You can [contribute to this list by adding something you'd like to be packaged](
| [Firefly-III Data Importer](https://docs.firefly-iii.org/data-importer) | Import data from banks to Firefly | [Upstream](https://github.com/firefly-iii/data-importer) | [Draft Package](https://github.com/marcoil/firefly-iii-di_ynh) |
| [Filestash](https://www.filestash.app/) | | [Upstream](https://github.com/mickael-kerjean/filestash) | |
| [fishnet](https://lichess.org/get-fishnet) | Distributed Stockfish analysis for lichess.org | [Upstream](https://github.com/niklasf/fishnet) | |
| FitTrackee | | [Upstream](https://github.com/SamR1/FitTrackee) | |
| FlareSolverr | Proxy server to bypass Cloudflare protection | [Upstream](https://github.com/FlareSolverr/FlareSolverr) | |
| Flask | Skeleton for flask apps | | [Package Draft](https://github.com/YunoHost-Apps/flask_ynh) |
| [foodsoft](https://foodcoops.github.io/foodsoft-hosting/) | Manage a non-profit food cooperative | | [Package Draft](https://github.com/YunoHost-Apps/foodsoft_ynh) |
@ -139,10 +138,12 @@ You can [contribute to this list by adding something you'd like to be packaged](
| [HistoPad](https://github.com/24eme/histopad) | Web application for logging pads (etherpad) and archiving them in a git repository. | [Upstream](https://github.com/24eme/histopad) | |
| Hometown | A Mastodon fork with local-only posting, support for more content types, and other features and tweaks. | [Upstream](https://github.com/hometown-fork/hometown) | |
| [htpc-manager](https://htpc.io) | Manage your HTPC from anywhere | | [Package Draft](https://github.com/scith/htpc-manager_ynh) |
| [hyperion](https://docs.hyperion-project.org/) | Ambient lightning software | [Upstream](https://github.com/hyperion-project/hyperion.ng) | |
| [Hypothes.is](https://hypothes.is) | Web Annotation server (and client) to crate and share highlights and notes | [Hypothes.is server](https://github.com/hypothesis/h) | |
| [Icecast 2](https://www.icecast.org) | | [Upstream](https://gitlab.xiph.org/xiph/icecast-server/) | |
| [ikiwiki](https://ikiwiki.info) | | | |
| [InfCloud](https://inf-it.com/open-source/clients/infcloud/) | A contacts, calendar and tasks web client for CalDAV and CardDAV | [Upstream](https://inf-it.com/open-source/download/InfCloud_0.13.1.zip) | |
| [Inginious](https://inginious.org) | Secure and automated exercises assessment platform using your own tests, also providing a pluggable interface with your existing LMS. | [Upstream](https://github.com/UCL-INGI/INGInious) ||
| [Inventaire](https://inventaire.io) | a libre collaborative resource mapper powered by open-knowledge, starting with books! 📚 | [Upstream](https://github.com/inventaire/inventaire) | |
| [InvoicePlane](https://invoiceplane.com) | | [Upstream](https://github.com/InvoicePlane/InvoicePlane) | |
| [IPFS](https://ipfs.io) | | [Upstream](https://github.com/ipfs/ipfs) | [Package Draft](https://github.com/YunoHost-Apps/ipfs_ynh) |
@ -256,6 +257,7 @@ You can [contribute to this list by adding something you'd like to be packaged](
| [Raspap](https://raspap.com/) | | [Upstream](https://github.com/RaspAP/raspap-webgui) | |
| Redash | Connect to any data source, easily visualize, dashboard and share your data. | [Upstream](https://github.com/getredash/redash) | |
| remoteStorage | A remoteStorage server implementation written in PHP | [Upstream](https://github.com/fkooman/php-remote-storage) | [Package Draft](https://github.com/YunoHost-Apps/RemoteStorage_ynh) |
| [Renovate](https://www.mend.io/renovate/) | Bot for automating dependency updates on Gitlab / Gitea / Forgejo | [Upstream](https://github.com/renovatebot/renovate)
| [Request Tracker](https://bestpractical.com) | | [Upstream](https://github.com/bestpractical/rt) | |
| [Restya](https://restya.com) | | [Upstream](https://github.com/RestyaPlatform/board/) | |
| [Retroshare](https://retroshare.cc/) | | [Upstream](https://github.com/RetroShare/RetroShare) | |

8
pages/05.community/20.faq/faq.fr.md
View file

@ -110,3 +110,11 @@ Réponse moyenne : Par le passé, les apps étaient gérées via des .deb. C’
<p>Si vous restez persuadé que l’on peut néanmoins bricoler les paquets .deb pour gérer tout cela, voir les réponses précédentes.</p>
</div>
#### Quand est-ce que *cette fonctionnalité* sera ajoutée ? Pourquoi *cette app* n'a pas encore été packagée ? Je n'en reviens pas que vous ne fassiez pas encore *cela* !
Nous ne donnons pas de calendrier.
Nous sommes une poignée de volontaires travaillant sur notre temps libre pour maintenir et développer YunoHost. Nous n'avons pas de responsable produit ou de chef de projet, nous ne sommes pas une entreprise. Nous faisons ce que nous pouvons, parce que nous aimons ce logiciel, quand nous le pouvons.
Si vous souhaitez vraiment voir une fonctionnalité codée ou documentée, ou une application packagée, [envisagez de contributer](/contribute)! Nous adorerions vous aider à vous mettre en selle.

8
pages/05.community/20.faq/faq.md
View file

@ -110,3 +110,11 @@ Medium answer: Apps were packaged in .deb in the past. It was a nightmare. We're
<p>If you still think it's possible to handle everything by fiddling with .deb packages, see previous answers.</p>
</div>
#### When will *this feature* be implemented? Why *that app* has not been packaged yet? I cannot believe you do not do *that* yet!
We do not give timelines.
We are a bunch of volunteers working on our free time to maintain and develop YunoHost. We have no product owner or project manager handling resources, we are not a business. We do what we can, because we love this software, when we can.
If you really want to have a feature implemented or documented, or an app packaged, [consider contributing yourself](/contribute)! We would love helping you get started.

331
pages/06.contribute/10.packaging_apps/60.advanced/20.config_panels/config_panels.md
View file

@ -1,5 +1,5 @@
---
title: Config panels
title: Configuration panel for apps
template: docs
taxonomy:
category: docs
@ -7,4 +7,331 @@ routes:
default: '/packaging_config_panels'
---
TODO / FIXME ...
Configuration panels allow to let admins manage parameters or runs actions for which the upstream's app doesn't provide any appropriate UI itself. It's a good way to reduce manual change on config files and avoid conflicts on it.
Those panels can also be used to quickly create interfaces that extend the capabilities of YunoHost (e.g. VPN Client, Hotspost, Borg, etc.).
! Please: Keep in mind the YunoHost spirit, and try to build your panels in such a way as to expose only really useful, "high-level" parameters, and if there are many of them, to relegate those corresponding to rarer use cases to "Advanced" sub-sections. Keep it simple, focus on common needs, don't expect the admins to have 3 PhDs in computer science.
## `config_panel.toml`'s principle and general format
To create configuration panels for apps, you should at least create a `config_panel.toml` at the root of the package. For more complex cases, this TOML file can be paired with a `config` script inside the scripts directory of your package, which will handle specific controller logic.
The `config_panel.toml` describes one or several panels, containing sections, each containing questions generally binded to a params in the app's actual configuration files.
Let's imagine that the upstream app is configured using this simple `config.yml` file stored in the app's install directory (typically `/var/www/$app/config.yml`):
```yaml
title: 'My dummy app'
theme: 'white'
max_rate: 10
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]
[main.main]
[main.main.title]
ask.en = "Title"
type = "string"
bind = ":__INSTALL_DIR__/config.yml"
[main.main.theme]
ask.en = "Theme"
type = "select"
choices = ["white", "dark"]
bind = ":__INSTALL_DIR__/config.yml"
[main.limits]
[main.limits.max_rate]
ask.en = "Maximum display rate"
type = "number"
bind = ":__INSTALL_DIR__/config.yml"
[main.limits.max_age]
ask.en = "Duration of a dummy"
type = "number"
bind = ":__INSTALL_DIR__/config.yml"
```
Here we have created one `main` panel, containing the `main` and `limits` sections, containing questions according to params name of our `config.yml` file. Thanks to the `bind` properties, all those questions are bind to their values in the `config.yml` file.
### Questions short keys have to be unique
For performance reasons, questions short keys have to be unique in all the `config_panel.toml` file, not just inside its panel or its section. Hence it's not possible to have:
```toml
[manual.vpn.server_ip]
[advanced.dns.server_ip]
```
In which two questions have "real variable name" `is server_ip` and therefore conflict with each other.
### Supported questions types and properties
See [the full list of questions types and properties](/dev/forms)
### Reading and writing values
You can read and write values with 2 mechanisms: the `bind` property in the `config_panel.toml` and for complex use cases the getter/setter in a `config` script.
### `bind` property
The `bind` property allows to define where read and write the value bind to the question.
#### Default behaviour
If you did not define a specific getter/setter (see below), and no `bind` argument was defined, YunoHost will read/write the value from/to the app's `/etc/yunohost/$app/settings.yml` file.
#### Read / write into a var of an actual configuration file
If you want to read/write the value from/to the app's actual configural file (be it `.env`-like, JSON, YAML, INI, PHP, `.py`, ...):
```toml
[main.main.theme]
# (other properties ommited)
bind = ":__INSTALL_DIR__/config.yml"
```
In which case, YunoHost will look for something like a key/value, with the key being `theme`.
If the question id in the config panel (here, `theme`) differs from the key in the actual conf file (let's say it's not `theme` but `css_theme`), then you can write:
```toml
[main.main.theme]
# (other properties ommited)
bind = "css_theme:__FINALPATH__/config.yml"
```
!!!! Note: This mechanism is quasi language agnostic and will use regexes to find something that looks like a key=value or common variants. However, it does assume that the key and value are stored on the same line. It doesn't support multiline text or file in a variable with this method. If you need to save multiline content in a configuration variable, you should create a custom getter/setter (see below).
Nested syntax is also supported, which may be useful for example to remove ambiguities about stuff looking like:
```json
{
"foo": {
"max": 123
},
"bar": {
"max": 456
}
}
```
which we can `bind` to using:
```toml
bind = "foo>max:__INSTALL_DIR__/conf.json"
```
#### Read / write an entire file
Useful when using a question `file` or `text` for which you want to save the raw content directly as a file on the system.
```toml
[main.main.logo]
# (other properties ommited)
bind = "__INSTALL_DIR__/img/logo.png"
```
### Custom getter / setter
Sometimes the `bind` mechanism is not enough:
* the config file format is not supported (e.g. xml, csv)
* the data is not contained in a config file (e.g. database, directory, web resources...)
* the data should be written but not read (e.g. password)
* the data should be read but not written (e.g. fetching status information)
* we want to change other things than the value (e.g. the choices list of a select)
* the question answer contains several values to dispatch in several places
* and so on
You can create specific getter/setters functions inside the `scripts/config` of your app to customize how the information is read/written.
```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 question's getter is the function used to read the current value/state. Custom getters are defined using bash functions called `getter__QUESTION_SHORT_KEY()` which returns data through stdout.
Stdout can generated using one of those formats:
1) either a raw format, in which case the return is binded directly to the value of the question
2) or a yaml format, in this case you dynamically provide properties for your question (for example the `style` of an `alert`, the list of available `choices` of a `select`, etc.)
[details summary="<i>Basic example with raw stdout: get the timezone on the system</i>" class="helper-card-subtitle text-muted"]
`config_panel.toml`
```toml
[main.main.timezone]
ask = "Timezone"
type = "string"
```
`scripts/config`
```bash
get__timezone() {
echo "$(cat /etc/timezone)"
}
```
[/details]
[details summary="<i>Basic example with yaml-formated stdout : Display a list of available plugins</i>" class="helper-card-subtitle text-muted"]
`config_panel.toml`
```toml
[main.plugins.plugins]
ask = "Plugin to activate"
type = "tags"
choices = []
```
`scripts/config`
```bash
get__plugins() {
echo "choices: [$(ls $install_dir/plugins/ | tr '\n' ',')]"
}
```
[/details]
[details summary="<i>Advanced example with yaml-formated stdout : Display the status of a VPN</i>" class="helper-card-subtitle text-muted"]
`config_panel.toml`
```toml
[main.cube.status]
ask = "Custom getter alert"
type = "alert"
style = "info"
bind = "null" # no behaviour on
```
`scripts/config`
```bash
get__status() {
if [ -f "/sys/class/net/tun0/operstate" ] && [ "$(cat /sys/class/net/tun0/operstate)" == "up" ]
then
cat << EOF
style: success
ask:
en: Your VPN is running :)
EOF
else
cat << EOF
style: danger
ask:
en: Your VPN is down
EOF
fi
}
```
[/details]
#### Setter
A question's setter is the function used to set new value/state. Custom setters are defined using bash functions called `setter__QUESTION_SHORT_KEY()`. In the context of the setter function, variables named with the various quetion's short keys are avaible ... for example the user-specified date for question `[main.main.theme]` is available as `$theme`.
When doing non-trivial operations to set a value, you may want to use `ynh_print_info` to inform the admin about what's going on.
[details summary="<i>Basic example : Set the system timezone</i>" class="helper-card-subtitle text-muted"]
`config_panel.toml`
```toml
[main.main.timezone]
ask = "Timezone"
type = "string"
```
`scripts/config`
```bash
set__timezone() {
echo "$timezone" > /etc/timezone
ynh_print_info "The timezone has been changed to $timezone"
}
```
[/details]
## Validation
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.foo = "Foo (some explanation)"
choices.bar = "Bar (moar explanation)"
choices.loremipsum = "Lorem Ipsum Dolor Sit Amet"
```
Some other type specific argument exist like
| type | validation arguments |
| ----- | --------------------------- |
| `number`, `range` | `min`, `max`, `step` |
| `file` | `accept` |
| `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 'User login is too short, should be at least 4 chars'; fi
}
```
## Other actions than read, validate and save
### Restart a service at the end
You can use the services key to specify which service need to be reloaded or restarted.
```toml
services = [ 'nginx', '__APP__' ]
```
This argument can be set on a single question, to a section, or to an entire panel.
### Overwrite config panel mechanism
All main configuration helpers are overwritable, example:
```bash
ynh_app_config_apply() {
# Stop vpn client
touch /tmp/.ynh-vpnclient-stopped
systemctl stop ynh-vpnclient
_ynh_app_config_apply
# Start vpn client
systemctl start ynh-vpnclient
rm -f /tmp/.ynh-vpnclient-stopped
}
```
List of main configuration helpers
* `ynh_app_config_get`
* `ynh_app_config_show`
* `ynh_app_config_validate`
* `ynh_app_config_apply`
* `ynh_app_config_run`
More info on this can be found by reading [vpnclient_ynh config script](https://github.com/YunoHost-Apps/vpnclient_ynh/blob/master/scripts/config)

47
pages/06.contribute/10.packaging_apps/60.advanced/50.hooks/packaging_apps_hooks.md
View file

@ -12,18 +12,25 @@ YunoHost includes a hook mechanism triggered on a lot of operation changing the
The most obvious case is adding a user. If you had a `post_user_create` hook, this hook will be triggered as soon as a user is added.
## How to add a custom hook on a specific instance
!!! Bellow we imagine we want to run a command after each user creation to add the user to samba user.
!!! Below we imagine we want to run a command after each user creation to add the user to samba user.
You should create a directory with the name of the hooks into `/etc/yunohost/hooks.d/`:
```
mkdir -p /etc/yunohost/hooks.d/post_user_create
```
Next create a bash script inside this directory prefixed by 2 numbers and a dash:
```bash
nano /etc/yunohost/hooks.d/post_user_create/05-add-user-to-samba
```
By default, the directory must be readable and traversable by root, but if you notice your hook is not run at all by YunoHost, you can check permissions with `ls -l /etc/yunohost/hooks.d/` and apply these commands if needed:
```
chown root:root /etc/yunohost/hooks.d/post_user_create
chmod u+rx /etc/yunohost/hooks.d/post_user_create
```
## How to add a hook in an app package
If you are packaging an app, you should not set by yourself the hook into `/etc/yunohost/hooks.d` instead you should create a hooks dir at the root of your package.
```
@ -40,7 +47,7 @@ In the hooks dir, create a bash script called with the type of hook you want to
#### post_user_create
[details summary="<i>Triggered after user creation</i>" class="helper-card-subtitle text-muted"]
This hooks is run at the end of the command `yunohost user create` or equivalent action in webadmin.
This hook is run at the end of the command `yunohost user create` or equivalent action in webadmin.
##### Environment variables
@ -80,7 +87,7 @@ echo $message | mail -s "Welcome on $domain !" $YNH_USER_MAIL
#### post_user_delete
[details summary="<i>Triggered at the end of user deletion</i>" class="helper-card-subtitle text-muted"]
This hooks is run at the end of the command `yunohost user delete` or equivalent action in webadmin.
This hook is run at the end of the command `yunohost user delete` or equivalent action in webadmin.
##### No environment variables
@ -104,7 +111,7 @@ This hooks is run at the end of the command `yunohost user delete` or equivalent
### post_user_update
[details summary="<i>Triggered at the end of the user update</i>" class="helper-card-subtitle text-muted"]
This hooks is run at the end of the command `yunohost user update` or equivalent action in webadmin.
This hook is run at the end of the command `yunohost user update` or equivalent action in webadmin.
##### Environment variables
@ -143,7 +150,7 @@ echo $message | mail -s "Your password has been changed on $domain !" $YNH_USER_
### post_app_addaccess
[details summary="<i>Triggered after adding a permission to users or groups </i>" class="helper-card-subtitle text-muted"]
This hooks is run at the end of the command `yunohost user permission add` or equivalent action in webadmin.
This hook is run at the end of the command `yunohost user permission add` or equivalent action in webadmin.
##### No environment variables
@ -164,7 +171,7 @@ This hooks is run at the end of the command `yunohost user permission add` or eq
### post_app_removeaccess
[details summary="<i>Triggered after removing a pemission to users or groups</i>" class="helper-card-subtitle text-muted"]
This hooks is run at the end of the command `yunohost user permission remove` or equivalent action in webadmin.
This hook is run at the end of the command `yunohost user permission remove` or equivalent action in webadmin.
##### No environment variables
@ -190,7 +197,7 @@ This hooks is run at the end of the command `yunohost user permission remove` or
### post_domain_add
[details summary="<i>Triggered at the end of the domain add operation</i>" class="helper-card-subtitle text-muted"]
This hooks is run at the end of the command `yunohost domain add` or equivalent action in webadmin.
This hook is run at the end of the command `yunohost domain add` or equivalent action in webadmin.
##### No environment variable
@ -214,7 +221,7 @@ This hooks is run at the end of the command `yunohost domain add` or equivalent
### post_domain_remove
[details summary="<i>Triggered after removing the domain</i>" class="helper-card-subtitle text-muted"]
This hooks is run at the end of the command `yunohost domain remove` or equivalent action in webadmin.
This hook is run at the end of the command `yunohost domain remove` or equivalent action in webadmin.
##### No environment variable
@ -233,7 +240,7 @@ This hooks is run at the end of the command `yunohost domain remove` or equivale
### post_cert_update
[details summary="<i>Triggered after Let's encrypt certificate update</i>" class="helper-card-subtitle text-muted"]
This hooks is run at the end of the command `yunohost domain cert update` or equivalent action in webadmin.
This hook is run at the end of the command `yunohost domain cert update` or equivalent action in webadmin.
##### No environment variable
@ -258,9 +265,9 @@ systemctl restart gemserv
### custom_dns_rules
[details summary="<i>Customized your DNS rules for your domains</i>" class="helper-card-subtitle text-muted"]
This hooks is run at the end of the command `yunohost domain dns suggest` or equivalent action in webadmin.
This hook is run at the end of the command `yunohost domain dns suggest` or equivalent action in webadmin.
Thanks to this hooks you can customize
Thanks to This hook you can customize
##### No environment variable
@ -309,7 +316,7 @@ fi
### post_app_change_url
[details summary="<i>Triggered after an app has changed of URL</i>" class="helper-card-subtitle text-muted"]
This hooks is run at the end of the command `yunohost app change-url` or equivalent action in webadmin.
This hook is run at the end of the command `yunohost app change-url` or equivalent action in webadmin.
##### Environment variables
@ -328,7 +335,7 @@ This hooks is run at the end of the command `yunohost app change-url` or equival
### post_app_upgrade
[details summary="<i>Triggered on app upgrade</i>" class="helper-card-subtitle text-muted"]
This hooks is run at the end of the command `yunohost app upgrade` or equivalent action in webadmin.
This hook is run at the end of the command `yunohost app upgrade` or equivalent action in webadmin.
##### Environment variables
@ -366,7 +373,7 @@ fi
### post_app_install
[details summary="<i>Triggered at the end of an app installation</i>" class="helper-card-subtitle text-muted"]
This hooks is run at the end of the command `yunohost app install` or equivalent action in webadmin.
This hook is run at the end of the command `yunohost app install` or equivalent action in webadmin.
##### Environment variables
@ -388,7 +395,7 @@ This hooks is run at the end of the command `yunohost app install` or equivalent
### post_app_remove
[details summary="<i>Triggered after removing an app</i>" class="helper-card-subtitle text-muted"]
This hooks is run at the end of the command `yunohost app remove` or equivalent action in webadmin.
This hook is run at the end of the command `yunohost app remove` or equivalent action in webadmin.
##### Environment variables
@ -410,7 +417,7 @@ This hooks is run at the end of the command `yunohost app remove` or equivalent
### backup
[details summary="<i>Add some files to backup</i>" class="helper-card-subtitle text-muted"]
This hooks is run at the end of the command `yunohost backup create` or equivalent action in webadmin.
This hook is run at the end of the command `yunohost backup create` or equivalent action in webadmin.
##### Environment variables
@ -455,7 +462,7 @@ ynh_backup "/etc/yunohost/hooks.d/restore/99-conf_custom"
### restore
[details summary="<i>Restore some files</i>" class="helper-card-subtitle text-muted"]
This hooks is run at the end of the command `yunohost backup restore` or equivalent action in webadmin.
This hook is run at the end of the command `yunohost backup restore` or equivalent action in webadmin.
##### Environment variables
@ -500,7 +507,7 @@ ynh_restore_file "/etc/yunohost/hooks.d/restore/99-conf_custom"
### backup_method
[details summary="<i>Define a new way to backup and restore files</i>" class="helper-card-subtitle text-muted"]
This hooks is run during the command `yunohost backup create` or equivalent action in webadmin.
This hook is run during the command `yunohost backup create` or equivalent action in webadmin.
This hook is called several times with different action keywords.
@ -564,7 +571,7 @@ exit 0
### post_iptable_rules
[details summary="<i>Triggered after reloaded the firewall rules</i>" class="helper-card-subtitle text-muted"]
This hooks is run at the end of the command `yunohost firewall reload` or equivalent action in webadmin.
This hook is run at the end of the command `yunohost firewall reload` or equivalent action in webadmin.
##### No environment variables
@ -589,7 +596,7 @@ iptables -A OUTPUT -p tcp --dport 25 -m tcp -j REJECT --reject-with icmp-port-un
### conf_regen
[details summary="<i>Change configuration suggested as default config in regen-conf mechanism</i>" class="helper-card-subtitle text-muted"]
This hooks is run during the command `yunohost tools regen-conf` or equivalent action in webadmin.
This hook is run during the command `yunohost tools regen-conf` or equivalent action in webadmin.
This hook is called several times with different actions keywords (pre and post operations).

144
pages/06.contribute/15.dev/03.forms/forms.md Normal file
View file

@ -0,0 +1,144 @@
---
title: Forms
template: docs
taxonomy:
category: docs
routes:
default: '/dev/forms'
---
# Forms
YunoHost uses a lot of forms. You can found here information on supported types question and properties.
## Questions
!!! Questions are called `Options` in the code.
### Generic properties
| Property | Scope | Description | Example |
|----------|--------------|-------------|---------|
| `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| `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 = "__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
* For the moment `default` properties are not supported in app config panel and you have to initialize the value by yourself in config file or settings.
### `display_text` (readonly)
Display a simple text.
### `markdown` (readonly)
Display a markdown (if you don't use markdown features, prefer display_text)
### `alert` (readonly)
Display an alert box with different style.
| Property | Description | Default |
|----------|--------------|---------|
| `style` | Style of the alert box (success, info, warning, danger) | info |
### `button`
Display a button with different style (useful for custom actions).
| Property | Description | Default |
|----------|--------------|---------|
| `style` | Style of the alert box (success, info, warning, danger) | success|
| `enabled` | Enable or disable the button | True |
### `string`
Input text monoline.
### `text`
Input text multilines
| Property | Description | Default |
|----------|--------------|---------|
| `redact` | Style of the alert box (success, info, warning, danger) | success|
### `password`
Password input. `{}` chars are forbidden and value is not added to logs.
### `color`
Hexadecimal color starting with # with a color picker.
### `number`
An integer.
| Property | Description | Example |
|----------|--------------|---------|
| `min` | Minimal value | |
| `max` | Maximum value | |
| `step` | Steps between each next possible value | |
### `range`
| Property | Description | Example |
|----------|--------------|---------|
| `min` | Minimal value | |
| `max` | Maximum value | |
| `step` | Steps between each next possible value | |
### `boolean`
| Property | Description | Example |
|----------|--------------|---------|
| `yes` | | |
| `no` | | |
### `date`
A date picker with date in the format YYYY-MM-DD
### `time`
A time picker
### `email`
An email input
### `path`
### `url`
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 | |
! 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 | |
### `domain`
List all added domains
### `app`
List all installed apps
### `user`
List all users
### `group`
List all groups