filtering features

Author: alex-cit

src/field/filtering/index.md

@@ -7,25 +7,70 @@ description: Add custom filters to sort and display only those features that you
 
 Custom filters can be added to the <MobileAppNameShort /> to easily filter features displayed on the map as well as in the [survey layers](../layers/#browsing-features).
 
-## Enable features filtering
-Features filtering needs to be enabled in QGIS
+## Enable and define filtering in QGIS
+Filters can be enabled and defined in QGIS in **Project Properties**.
 
-1. Open your <MainPlatformName /> project in QGIS and navigate to **Project** > **Properties** 
+::: tip Plugin upgrade
+If you do not see the **Filtering** option in the **Project properties**, check for [plugin upgrades](../../setup/install-mergin-maps-plugin-for-qgis/#plugin-upgrade).
+:::
 
-2. In the <MainPlatformName /> tab, check the **Enable map sketching** option.
+Check the :heavy_check_mark: **Enable filtering** option in the <MainPlatformName /> tab, click on the **Add filter** button and select a filter type from the list. The list of available [filter types](#filter-types) and their properties can be found below.
 
-   ::: tip Plugin upgrade
-   If you do not see this option in the **Project properties**, check for [plugin upgrades](../../setup/install-mergin-maps-plugin-for-qgis/#plugin-upgrade).
-   :::
-
-3. Click on the **Add filter** button and select a filter type from the list.
-   ![Enable map sketching in QGIS Mergin Maps project](./qgis-project-properties-enable-filtering.webp "Enable map sketching in QGIS Mergin Maps project")
-   
-4. Define the filter:
-   - **Type** 
+Then, define the filter:
+   - **Type** - the filter type (in general, it should match the widget type of the filtered field)
+   - **Layer** - choose from the project's layers
+   - **Field** - choose from the fields of the layer. Only fields with data types compatible with the selected filter type are offered.
+   - **Title** - the name of the filter, which will be displayed in the <MobileAppNameShort />
 
-5. Save the changes and synchronise your project
+   ![Filtering in QGIS Mergin Maps project](./qgis-project-properties-enable-filtering.webp "Filtering in QGIS Mergin Maps project")
+
+You can add as many filters as you need by using the **Add filter** button.
+
+The order of filters can be changed by selecting a filter and using the **Up** and **Down** buttons. To remove a filter, select it and click the **Remove** button.
+![Filtering in QGIS Mergin Maps project](./qgis-filtering.webp "Filtering in QGIS Mergin Maps project")
+
+qgis-filtering.webp
+Don't forget to save your project and synchronise changes so that you can use the filters in the <MobileAppNameShort />.
+
+
+### Filter types
+
+**Text** filter uses simple text input. Results are filtered based the SQL expression `"field" ILIKE '%input%'`. Available for text and number field types.
+
+**Number** filter provides *from* and *to* number inputs. Results are filtered based on SQL expression `"field" >= 'input_from' AND "field" <= 'input_to'`. Available for text and number field types.
+
+**Date** filter provides *from* and *to* date (calendar) inputs. Results are filtered based on SQL expression `"field" >= 'input_from' AND "field" <= 'input_to'`. Available for date field types configured with the [Date and time widget](../../layer/date-time/).
+
+**Boolean** filter provides a toggle between *all*, *true* and *false* values. Results are filtered based on SQL expression `"field" == 'input'`. Available for Boolean, text and integer field types configured with the [Checkbox widget](../../layer/checkbox/).
 
+**Single select** filter provides a drop-down menu of field values. One value can be selected at once. The results are filtered based on SQL expression `"field" == 'input'`. Available for text and number field types configured with the [Value map or Value relation widget](../../layer/value-select/).
 
+**Multi select** filter provides a drop-down menu of field values. Multiple values can be selected at once. The results are filtered based on SQL expression `"field" IN ('input')`. Available for text and number field types configured with the [Value map or Value relation widget](../../layer/value-select/#value-relation).
+
+In the <MobileAppNameShort />, the filter types looks as follows:
+
+![Filter types in Mergin Maps mobile app](./mobile-filter-types.webp "Filter types in Mergin Maps mobile app") 
 
 ## Filtering features in the mobile app
+Filters defined in [<MainPlatformName /> project in QGIS](#enable-and-define-filtering-in-qgis) can be used in the <MobileAppNameShort />. You can filter features across multiple layers by entering or selecting values in corresponding filters. The filtering affects both the map display and the feature browsing list. 
+
+:::warning Filters reset
+Filters are reset when the project is synced. Also, they do not stay saved when the app is restarted.
+:::
+
+Here is an example of how filtering works:
+
+1. Tap the **Filters** button to open filters defined in the project
+   ![Filtering button in Mergin Maps mobile app](./mobile-open-filters.webp "Filtering button in Mergin Maps mobile app")
+
+2. Enter or select values in the filters. Here, we will use a *Single select* filter on the *trees* layer and select a *tree species* value from the list.
+
+   You can use more filters at once.
+
+   Tap on the **Apply filters** button to confirm the filtering.
+  ![Filtering in Mergin Maps mobile app](./mobile-filter-single-selection.webp "Filtering in Mergin Maps mobile app")
+
+3. With active filters, only features that match the criteria are displayed on the map as well as when [browsing features](../layers/#layers-legend-and-features).
+
+   If filters are applied
+  ![Active filter in Mergin Maps mobile app](./mobile-filtered-features.webp "Active filter in Mergin Maps mobile app")