From e0d46843ff4c1b6ac3a3b57dc896f102874112ec Mon Sep 17 00:00:00 2001
From: Sandro Mani <manisandro@gmail.com>
Date: Fri, 15 Mar 2024 17:55:49 +0100
Subject: [PATCH] Add MapFilter topic

---
 qwc2.yml.in               |  1 +
 src/topics/Interfacing.md |  1 +
 src/topics/MapFilter.md   | 57 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 59 insertions(+)
 create mode 100644 src/topics/MapFilter.md

diff --git a/qwc2.yml.in b/qwc2.yml.in
index e96fc5a5..79a47d6b 100644
--- a/qwc2.yml.in
+++ b/qwc2.yml.in
@@ -18,6 +18,7 @@ nav:
             - Snapping: topics/Snapping.md
             - Temporal layers: topics/TimeManager.md
             - Legend graphics: topics/LegendGraphics.md
+            - Map filtering: topics/MapFilter.md
             - Interfacing with applications: topics/Interfacing.md
             - Multi-tenancy: topics/MultiTenancy.md
         - References: references/index.md
diff --git a/src/topics/Interfacing.md b/src/topics/Interfacing.md
index af559a73..51bfce2b 100644
--- a/src/topics/Interfacing.md
+++ b/src/topics/Interfacing.md
@@ -16,6 +16,7 @@ The following parameters can appear in the URL of the QWC2 application:
 - `hc`: If `c` is specified and `hc` is `true` or `1`, a marker is set at `c` when starting the application. Note: requires the `StartupMarkerPlugin` plugin to be active.
 - `st`: The search text
 - `hp`, `hf`, `ht`: Startup highlight parameters used in conjunction with the `qwc-fulltext-search-service`, see below.
+- `f`: A filter configuration, see [./MapFilter](Map filtering).
 - `localConfig`: Override the name of the loaded config file, i.e. to load `myconfig.json` instead of the default `config.json`, pass `localConfig=myconfig`.
 
 The `l` parameter lists all layers in the map (redlining and background layers) as a comma separated list of entries of the form
diff --git a/src/topics/MapFilter.md b/src/topics/MapFilter.md
new file mode 100644
index 00000000..d62aed35
--- /dev/null
+++ b/src/topics/MapFilter.md
@@ -0,0 +1,57 @@
+The [`MapFilter`](../references/qwc2_plugins.md#mapfilter) plugin allows filtering the map content via QGIS Server WMS FILTER.
+
+You can set predefined filter expressions for a theme item as follows:
+
+```json
+"predefinedFilters": {
+    "id": "<filter_id>",
+    "title": "<filter_title>",
+    "titlemsgid": "<filter_title_msgid>",
+    "filter": {
+        "<layer>": <data_service_filter_expression>
+    },
+    "fields": {
+        "id": "<value_id>",
+        "title": "<value_title">,
+        "titlemsgid": "<value_title_msgid>",
+        "defaultValue": <default_value>,
+        "inputConfig": {<input_field_opts>}
+    }
+}
+```
+
+You can specify any common HTML input element properties in `input_field_opts`, i.e.:
+
+```json
+"inputConfig": {"type": "number", "min": 0}
+```
+
+As a special case, you can define a dropdown list as follows:
+
+```json
+"inputConfig": {"type": "select", "options": [{"value": "<value1>", "label|labelmsgid": "<label(msgid)1>"}, ...]}
+```
+
+It is also possible to pass a flat list as options, i.e. `["<value1>", "<value2>"]` if the value is equal to the label.
+
+The data service filter expressions are of the form `["<name>", "<op>", <value>]`, you can also specify complex expressions concatenated with `and|or` as follows:
+
+```json
+[["<name>", "<op>", <value>],"and|or",["<name>","<op>",<value>],...]
+```
+
+You can set the startup filter configuration by specifying a `f` URL-parameter with a JSON-serialized string as follows:
+
+```
+f={"<filter_id>": {"<field_id>": <value>, ...}, ...}
+```
+
+To control the temporal filter, the filter ID is `__timefilter`, and the field IDs are `tstart` and `tend`, with values an ISO date or datetime string (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SS`).
+
+To control the spatial filter, the syntax is `"__geomfilter": <GeoJSON polygon coodinates array>`.
+
+To specify custom filters, the syntax is `"__custom": [{"title": "<title>", "layer": "<layername>", "expr": <JSON filter expr>}, ...]`.
+
+Whenever an startup filter value is specified, the filter is automatically enabled.
+
+*Note*: When specifying `f`, you should also specify `t` as the startup filter configuraiton needs to match the filters of the desired theme.