diff --git a/src/layer/form-layout/index.md b/src/layer/form-layout/index.md index 4ff50dd1..83dd03ca 100644 --- a/src/layer/form-layout/index.md +++ b/src/layer/form-layout/index.md @@ -3,9 +3,6 @@ Collecting and editing data in the field can be more efficient with forms that are easy to navigate. QGIS offers a lot of options for improving the layout of your forms, such as using groups and tabs to keep related fields together, displaying or hiding a group of fields based on conditional visibility, or displaying tips and instructions in the forms. -::: warning -Our mobile app was redesigned. We are in the process of updating this content to reflect these changes. -::: ## QGIS Drag and Drop Designer By default, the form is automatically generated and contains all the fields in the layer. However, you might want to change the order of the fields. Also, there may be some fields that do not need to be displayed during the survey, such as fields with [default values](../settingup_forms_settings/#default-values) that are calculated from the geometry. @@ -45,22 +42,27 @@ The form with tabs and groups will appear in QGIS like this: ![QGIS form conditional visibility](./qgis_forms_layout_attribute.jpg "QGIS form conditional visibility") And this is how the same form looks like in : -![Mergin Maps Input form with tabs and groups](./input_forms_layout2.jpg "Mergin Maps Input form with tabs and groups") +![Mergin Maps Input form with tabs and groups](./mobile-forms-layout.jpg "Mergin Maps Input form with tabs and groups") ## Show and hide fields depending on a field value Conditional visibility can be applied to groups and tabs, meaning they will be displayed or hidden depending on the value of a field. -We can set the visibility of **Location** tab depending on the value of the **survey** field: - - If **survey** is set to **False**, the **Location** tab will not appear in the form, - - If **survey** is set to **True**, the **Location** tab will show up in the form. +We can set the visibility of **Location** tab depending on the value of the `survey` field: + - If `survey` is set to `False`, the **Location** tab will not appear in the form, + - If `survey` is set to `True`, the **Location** tab will show up in the form. 1. Select the **Location** tab in the **Form Layout** column 2. Check the **Control Visibility by Expression** option 3. Type the following expression in the box below: `"survey" IS TRUE` 4. Background colour can be set in the **Style** tab. + ![QGIS form control visibility by expression](./qgis_forms_layout_visibility.jpg "QGIS form control visibility by expression") +In the , the tab **Location** is displayed only when the `survey` field (aliased here as *Does it need surveying*) is toggled to `true`. +![Show fields depending on a field value in the mobile app](./mobile-forms-conditional-visibility.jpg "Show fields depending on a field value in the mobile app") + + ## Display instructions in the form using Text and HTML widget Sometimes, you may want to include instructions or tips for surveyors in your forms. offers Text and HTML widgets that can be used for this purpose. Your text instructions can include [expressions and field values](#using-expressions-in-text-and-html-widgets) as well. The HTML widget supports various [HTML tags](https://doc.qt.io/qt-6/richtext-html-subset.html#supported-tags), so it can be also used, for instance, to display [online images](#using-html-widget-to-display-online-images-and-other-online-resources). @@ -74,7 +76,7 @@ If you prefer your text to be formatted, you may do so in the **HTML** widget. H ![QGIS HTML widget configuration](./qgis-configure-html-widget.jpg "QGIS HTML widget configuration") ...and this is how the Text and HTML widgets look like in the form in QGIS (left) and in the mobile app (right). -![](./qgis-form-text-html.jpg) +![Text and HTML widgets in QGIS and in Mergin Maps mobile app](./qgis-form-text-html.jpg "Text and HTML widgets in QGIS and in Mergin Maps mobile app") ### Using expressions in Text and HTML widgets Expressions and variables can be used both in the Text and the HTML widget. @@ -105,6 +107,10 @@ Clone to follow this examp ### Using HTML widget to display online images and other online resources The **HTML widget** can be also used to display online images in the mobile app or open online resources, such as PDF files, videos or websites, in the browser of your device. +::: tip +Clone to how this works. +::: + Here are HTML samples you can use to [configure the HTML widget](#using-expressions-in-text-and-html-widgets). Your form should contain a text field for storing the full URL link (here: `link`). To use these samples, replace `link` by the name of the appropriate field in your layer. @@ -120,10 +126,39 @@ To use these samples, replace `link` by the name of the appropriate field in you ``` -Make sure that the HTML widget works as intended before taking it to the field - try it out in QGIS and in the . It should look something like this: +Make sure that the HTML widget works before taking it to the field by testing it in the . It should look something like this: ![HTML widget in QGIS and in Mergin Maps mobile app](./qgis-mobile-html-form.jpg "HTML widget in QGIS and in Mergin Maps mobile app") +::: warning Image preview in QGIS 3.36+ +QGIS may not display the preview of the online image if you use QGIS 3.36 or higher. Despite this behaviour, the displays it correctly. Therefore we recommend trying the setup by opening the form in the to make sure it works as intended. +::: + + +### Using HTML widget to open local files +The HTML widget can also be used to open local files: for instance, a locally stored PDF file can be opened from within the form during the survey. + +::: tip +Clone to how this works. +::: + +- A PDF file named `my-pdf.pdf` is stored in the main [project folder](../../manage/project/#mergin-maps-project-folder) as it needs to be packaged with the project. +- The HTML Widget is added to the **Attributes Form** and configured as follows: + ``` + Open File + ``` + +![QGIS attributes form open local file using HTML widget](./qgis-form-open-file-html-widget.jpg "QGIS attributes form open local file using HTML widget") + +In the , you can tap the *Open File* link to open the PDF file using the default application of your device. + +![Open a local PDF file in Mergin Maps mobile app](./mobile-forms-open-file-html-widget.jpg "Open a local PDF file in Mergin Maps mobile app") + +::: tip Open local files using default values +Local files can be displayed in the form also using [default values](../settingup_forms_settings/#open-local-files-using-default-values). + +In the project, you can explore and compare both alternatives. +::: ## Spacer widget diff --git a/src/layer/form-layout/input_forms_layout2.jpg b/src/layer/form-layout/input_forms_layout2.jpg deleted file mode 100644 index f8684fc3..00000000 Binary files a/src/layer/form-layout/input_forms_layout2.jpg and /dev/null differ diff --git a/src/layer/form-layout/input_forms_layout2.xcf b/src/layer/form-layout/input_forms_layout2.xcf deleted file mode 100644 index ce73fef0..00000000 Binary files a/src/layer/form-layout/input_forms_layout2.xcf and /dev/null differ diff --git a/src/layer/form-layout/mobile-forms-conditional-visibility.jpg b/src/layer/form-layout/mobile-forms-conditional-visibility.jpg new file mode 100644 index 00000000..8ca2c824 Binary files /dev/null and b/src/layer/form-layout/mobile-forms-conditional-visibility.jpg differ diff --git a/src/layer/form-layout/mobile-forms-conditional-visibility.xcf b/src/layer/form-layout/mobile-forms-conditional-visibility.xcf new file mode 100644 index 00000000..3160d08b Binary files /dev/null and b/src/layer/form-layout/mobile-forms-conditional-visibility.xcf differ diff --git a/src/layer/form-layout/mobile-forms-layout.jpg b/src/layer/form-layout/mobile-forms-layout.jpg new file mode 100644 index 00000000..05b4cbc7 Binary files /dev/null and b/src/layer/form-layout/mobile-forms-layout.jpg differ diff --git a/src/layer/form-layout/mobile-forms-layout.xcf b/src/layer/form-layout/mobile-forms-layout.xcf new file mode 100644 index 00000000..8062f616 Binary files /dev/null and b/src/layer/form-layout/mobile-forms-layout.xcf differ diff --git a/src/layer/form-layout/mobile-forms-open-file-html-widget.jpg b/src/layer/form-layout/mobile-forms-open-file-html-widget.jpg new file mode 100644 index 00000000..cfdb4307 Binary files /dev/null and b/src/layer/form-layout/mobile-forms-open-file-html-widget.jpg differ diff --git a/src/layer/form-layout/mobile-forms-open-file-html-widget.xcf b/src/layer/form-layout/mobile-forms-open-file-html-widget.xcf new file mode 100644 index 00000000..0fa41723 Binary files /dev/null and b/src/layer/form-layout/mobile-forms-open-file-html-widget.xcf differ diff --git a/src/layer/form-layout/mobile-text-widget-expression.jpg b/src/layer/form-layout/mobile-text-widget-expression.jpg index f72d0632..4215c32a 100644 Binary files a/src/layer/form-layout/mobile-text-widget-expression.jpg and b/src/layer/form-layout/mobile-text-widget-expression.jpg differ diff --git a/src/layer/form-layout/mobile-text-widget-expression.xcf b/src/layer/form-layout/mobile-text-widget-expression.xcf index 89d549b7..a3d95582 100644 Binary files a/src/layer/form-layout/mobile-text-widget-expression.xcf and b/src/layer/form-layout/mobile-text-widget-expression.xcf differ diff --git a/src/layer/form-layout/qgis-form-open-file-html-widget.jpg b/src/layer/form-layout/qgis-form-open-file-html-widget.jpg new file mode 100644 index 00000000..19b2c1ec Binary files /dev/null and b/src/layer/form-layout/qgis-form-open-file-html-widget.jpg differ diff --git a/src/layer/form-layout/qgis-form-open-file-html-widget.xcf b/src/layer/form-layout/qgis-form-open-file-html-widget.xcf new file mode 100644 index 00000000..2ee53c46 Binary files /dev/null and b/src/layer/form-layout/qgis-form-open-file-html-widget.xcf differ diff --git a/src/layer/form-layout/qgis-form-spacer-widget.jpg b/src/layer/form-layout/qgis-form-spacer-widget.jpg index 80b1f736..4f3cbc9e 100644 Binary files a/src/layer/form-layout/qgis-form-spacer-widget.jpg and b/src/layer/form-layout/qgis-form-spacer-widget.jpg differ diff --git a/src/layer/form-layout/qgis-form-text-html.jpg b/src/layer/form-layout/qgis-form-text-html.jpg index 6688db29..d387d1ea 100644 Binary files a/src/layer/form-layout/qgis-form-text-html.jpg and b/src/layer/form-layout/qgis-form-text-html.jpg differ diff --git a/src/layer/form-layout/qgis-form-text-html.xcf b/src/layer/form-layout/qgis-form-text-html.xcf index de1158ee..9e4b91a1 100644 Binary files a/src/layer/form-layout/qgis-form-text-html.xcf and b/src/layer/form-layout/qgis-form-text-html.xcf differ diff --git a/src/layer/form-layout/qgis-mobile-html-form.jpg b/src/layer/form-layout/qgis-mobile-html-form.jpg index 3cb32513..6bb98a70 100644 Binary files a/src/layer/form-layout/qgis-mobile-html-form.jpg and b/src/layer/form-layout/qgis-mobile-html-form.jpg differ diff --git a/src/layer/form-layout/qgis-mobile-html-form.xcf b/src/layer/form-layout/qgis-mobile-html-form.xcf index c79543e1..0ae5097f 100644 Binary files a/src/layer/form-layout/qgis-mobile-html-form.xcf and b/src/layer/form-layout/qgis-mobile-html-form.xcf differ diff --git a/src/layer/form-layout/spacer-widget-forms.jpg b/src/layer/form-layout/spacer-widget-forms.jpg index 8f53a0c9..545a9ebc 100644 Binary files a/src/layer/form-layout/spacer-widget-forms.jpg and b/src/layer/form-layout/spacer-widget-forms.jpg differ diff --git a/src/layer/form-layout/spacer-widget-forms.xcf b/src/layer/form-layout/spacer-widget-forms.xcf index 38ab7b22..577fe798 100644 Binary files a/src/layer/form-layout/spacer-widget-forms.xcf and b/src/layer/form-layout/spacer-widget-forms.xcf differ diff --git a/src/layer/mobile-forms-open-file-default-value.jpg b/src/layer/mobile-forms-open-file-default-value.jpg new file mode 100644 index 00000000..d4d7f568 Binary files /dev/null and b/src/layer/mobile-forms-open-file-default-value.jpg differ diff --git a/src/layer/mobile-forms-open-file-default-value.xcf b/src/layer/mobile-forms-open-file-default-value.xcf new file mode 100644 index 00000000..3cd7beb2 Binary files /dev/null and b/src/layer/mobile-forms-open-file-default-value.xcf differ diff --git a/src/layer/plugin-variables.md b/src/layer/plugin-variables.md index 3515e47b..79f582e3 100644 --- a/src/layer/plugin-variables.md +++ b/src/layer/plugin-variables.md @@ -5,7 +5,7 @@ The adds several variables that can be used in QGIS expressio | Variable name | Sample value | Scope | Description | |-----------------------------|-------------------------------|---------|-------------| | `@mergin_username` | `martin` | global | Name of the user currently logged in to | -| `@mergin_user_email` | `martin@example.com` | global | Email of the user currently logged in to | +| `@mergin_user_email` | `martin@example.com` | global | Email of the user currently logged in to | | `@mergin_url` | `https://app.merginmaps.com` | global | URL of the service | | `@mergin_project_name` | `Tree survey` | project | Name of the active project | | `@mergin_project_owner` | `martin` | project | Name of the owner of the active project | diff --git a/src/layer/qgis-form-open-file-default-value.jpg b/src/layer/qgis-form-open-file-default-value.jpg new file mode 100644 index 00000000..9e95c9a5 Binary files /dev/null and b/src/layer/qgis-form-open-file-default-value.jpg differ diff --git a/src/layer/qgis-form-open-file-default-value.xcf b/src/layer/qgis-form-open-file-default-value.xcf new file mode 100644 index 00000000..9303af2d Binary files /dev/null and b/src/layer/qgis-form-open-file-default-value.xcf differ diff --git a/src/layer/settingup_forms_photo.md b/src/layer/settingup_forms_photo.md index 856283a3..2c5b146a 100644 --- a/src/layer/settingup_forms_photo.md +++ b/src/layer/settingup_forms_photo.md @@ -102,3 +102,6 @@ Now when you click on a feature that contains a photo, it will be displayed in t ![Mergin Maps mobile app photo displayed in form](./qgis-form-view-photo.jpg "Mergin Maps mobile app photo displayed in form") +::: warning Image preview in QGIS 3.36+ +QGIS may not display the preview of the image if you use QGIS 3.36 or higher. Despite this behaviour, the displays it correctly. Therefore we recommend trying the setup by opening the form in the to make sure it works as intended. +::: diff --git a/src/layer/settingup_forms_settings.md b/src/layer/settingup_forms_settings.md index 269edaac..ed2455e3 100644 --- a/src/layer/settingup_forms_settings.md +++ b/src/layer/settingup_forms_settings.md @@ -37,6 +37,47 @@ When you survey a new point in , you will see the values are au ![Mergin Maps mobile app attributes form default value](./input_forms_defaults1.jpg "Mergin Maps mobile app attributes form default value") +### Examples of useful default values +There are some commonly used default values that can be useful in your field survey. As they are filled in automatically, they can be hidden from attributes form. + +* It is convenient to know when a feature was created and when it was last updated. Use fields with **Date** or **Date&Time** data types with the `now()` function to record these information. You can change the formatting using [Date/Time](./settingup_forms/#date-and-time) widget. +* Similarly, the name of the user who created or modified the feature can be recorded using the `@mergin_username` [QGIS plugin variable](./plugin-variables/). These field should have the **Text (string)** data type. +* The coordinates of a point feature can be recorded as well using the `$x` and `$y` function in QGIS. To record the coordinate accurately, these fields should have the **Decimal number (real)** data type. If the coordinates are in meters, values can be rounded to, say, 2-3 decimal places. When working with geographic coordinates that use degrees, you may want to round the coordinates to 8 decimal places. Use the *apply default value on update* option so that you have correct values when the position of the point feature changes. + + +| Variable name | Sample value | Apply default value on update | Description | +|-----------------------------|-------------------------------|---------|-------------| +| `@now` | `2024-06-30 10:00:00` | **no** | The timestamp of when the feature was created. | +| `@now` | `2024-06-30 10:30:00` | **yes** | The timestamp of when the feature was last **updated**. | +| `@mergin_username` | `sarah` | **no** | Name of the user who created this feature.| +| `@mergin_username` | `jack` | **yes** | Name of the user who **updated** this feature last.| +| `round($x,2)` | `1898789.92` | **yes** | The X coordinate of a point feature, rounded to 2 decimal places.| +| `round($y,2)` | `6134520.89` | **yes** | The Y coordinate of a point feature, rounded to 2 decimal places.| + +### Open local files using default values +Default values can also be used to open local files (e.g. a PDF file) from within the form. This file needs to be packaged with the project, so it should be stored somewhere in the [project folder](../manage/project/#mergin-maps-project-folder). + +There is a public project you can download or clone to see how the setup works. +- A PDF file named `my-pdf.pdf` is stored in the main project folder. +- The survey layer has a field named `local-file-default-value` with **Text (string)** data type. + - This field is set to *not editable* (the form will refer to the same file for all features and does not need to be changed). + - This field uses the **Text Edit** widget with the *Multiline* and *HTML* options enabled. + - The **default value** is set to: + ``` + 'Open File' + ``` + +![QGIS attributes form open local file](./qgis-form-open-file-default-value.jpg "QGIS attributes form open local file") + +In the , you can tap the *Open File* link to open the PDF file using the default application of your device. + +![Open a local PDF file in Mergin Maps mobile app](./mobile-forms-open-file-default-value.jpg "Open a local PDF file in Mergin Maps mobile app") + +::: tip Open local files using the HTML widget +Local files can be displayed in the form also using [the HTML widget](./form-layout/#using-html-widget-to-open-local-files). + +In the project, you can explore and compare both alternatives. +::: ## Constraints When collecting data, you may want to apply constraints to certain field(s) to avoid mistakes when the values are filled in in the field.