From ecab03b76ef520633548a06115c1c6e8a317cbdd Mon Sep 17 00:00:00 2001
From: oleole39 <59071673+oleole39@users.noreply.github.com>
Date: Tue, 21 Oct 2025 02:46:37 +0200
Subject: [PATCH 1/2] add usecase bind + custom setter

---
 .../60.advanced/20.config_panels.mdx          | 47 +++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/docs/packaging/60.advanced/20.config_panels.mdx b/docs/packaging/60.advanced/20.config_panels.mdx
index 0e01b5f1cd..2652fdd5b4 100644
--- a/docs/packaging/60.advanced/20.config_panels.mdx
+++ b/docs/packaging/60.advanced/20.config_panels.mdx
@@ -293,6 +293,53 @@ set__timezone() {
 }
 ```
 
+### "`Bind`" statement with custom setters
+
+You may also want to use custom setters to edit the same file that is bound to some config panel entries via the `bind` statement. This can be useful for instance if a portion of the bound config file is not of the format supported by the `bind` statement and thus need to be edited with a custom setter.
+In such cases, bear in mind that when pressing the "Save" button in the config panel, custom setters will be run first, and then the entries with the `bind` property will be saved. Due to this, you will have to run [`ynh_store_file_checksum()`](https://doc.yunohost.org/en/packaging/scripts/helpers_v2.1#backup) in the last setter to be executed before the bind operations start, or the latter [will warn you that the file was changed manually](https://github.com/YunoHost/yunohost/blob/81075f81e9ed527698387d9f23e73eb00dfab54c/helpers/helpers.v2.1.d/config#L96).
+
+<details>
+<summary><i>Basic example : a mixed format config file</i></summary>
+
+`__INSTALL_DIR__/js/config.js`
+
+```js
+const servers = [];
+
+const customPrefs = {
+  "lang": "en",
+  "theme": "auto",
+  "sortAsc": true,
+  "pageSize": 12
+}
+```
+
+`config_panel.toml`
+
+```toml
+[main.server_mode.archives_paths]
+ask.en = "Mastodon archive(s) to display"
+type = "text"
+bind = "null"
+
+[main.default_config.lang]
+ask.en = "UI Language"
+type = "select"
+choices = ["en", "fr", "auto"]
+bind = "lang:__INSTALL_DIR__/js/config.js"
+```
+`scripts/config`
+
+```bash
+set__archives_paths() {
+    # Convert multiline string into one comma-separated line
+    local comma_separated_archives_paths="${archives_paths//[[:space:]]/,}"
+    local comma_separated_archives_paths_quoted="\"${archives_paths//[[:space:]]/\",\"}\""
+
+    ynh_replace --match="^const servers.*" --replace="const servers = [$comma_separated_archives_paths_quoted];" --file="$config_file"
+    ynh_store_file_checksum "$config_file"
+}
+```
 </details>
 
 ## User input validations

From 53c277101e67408a157ae265dd19c712b0a19a0e Mon Sep 17 00:00:00 2001
From: oleole39 <59071673+oleole39@users.noreply.github.com>
Date: Tue, 21 Oct 2025 03:05:09 +0200
Subject: [PATCH 2/2] fix <details> tag

---
 docs/packaging/60.advanced/20.config_panels.mdx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/packaging/60.advanced/20.config_panels.mdx b/docs/packaging/60.advanced/20.config_panels.mdx
index 2652fdd5b4..2e01558842 100644
--- a/docs/packaging/60.advanced/20.config_panels.mdx
+++ b/docs/packaging/60.advanced/20.config_panels.mdx
@@ -292,6 +292,7 @@ set__timezone() {
     ynh_print_info "The timezone has been changed to $timezone"
 }
 ```
+</details>
 
 ### "`Bind`" statement with custom setters