diff --git a/REDIRECTS b/REDIRECTS index 7d2f454a..806e9bd2 100644 --- a/REDIRECTS +++ b/REDIRECTS @@ -28,7 +28,7 @@ https://help.cloudmergin.com/plugin-installation https://merginmaps.com/docs/set https://help.cloudmergin.com/plugin-logs https://merginmaps.com/docs/misc/troubleshoot/ https://help.cloudmergin.com/plugin-new-project https://merginmaps.com/docs/manage/create-project/ https://help.cloudmergin.com/plugin-sync-project https://merginmaps.com/docs/manage/plugin/ -https://help.cloudmergin.com/plugin-variables https://merginmaps.com/docs/layer/extra-variables/ +https://help.cloudmergin.com/plugin-variables https://merginmaps.com/docs/layer/variables/ https://help.cloudmergin.com/project-advanced https://merginmaps.com/docs/manage/project-advanced/ https://help.cloudmergin.com/project-details https://merginmaps.com/docs/manage/project-history/ https://help.cloudmergin.com/quick-start https://merginmaps.com/docs/tutorials/capturing-first-data/ @@ -62,7 +62,7 @@ https://help.inputapp.io/howto/exif_metadata https://merginmaps.com/docs/layer/e https://help.inputapp.io/howto/external_gps https://merginmaps.com/docs/field/external_gps/ https://help.inputapp.io/howto/gps_accuracy https://merginmaps.com/docs/field/gps_accuracy/ https://help.inputapp.io/howto/package_qgis_project https://merginmaps.com/docs/manage/create-project/ -https://help.inputapp.io/howto/position_variables https://merginmaps.com/docs/layer/extra-variables/ +https://help.inputapp.io/howto/position_variables https://merginmaps.com/docs/layer/variables/ https://help.inputapp.io/howto/proj https://merginmaps.com/docs/gis/proj/ https://help.inputapp.io/howto/project_config https://merginmaps.com/docs/gis/features/ https://help.inputapp.io/howto/registration https://merginmaps.com/docs/setup/sign-up-to-mergin-maps/ @@ -120,7 +120,7 @@ https://merginmaps.com/docs/fieldwork/gps_accuracy/ https://merginmaps.com/docs/ https://merginmaps.com/docs/field/input_features/ https://merginmaps.com/docs/field/mobile-features/ https://merginmaps.com/docs/field/input_ui/ https://merginmaps.com/docs/field/mobile-app-ui/ https://merginmaps.com/docs/gis/enable_browsing/ https://merginmaps.com/docs/gis/search_data/ -https://merginmaps.com/docs/howto/attach-multiple-photos-to-features/ https://merginmaps.com/docs/layer/attach-multiple-photos-to-features/ +https://merginmaps.com/docs/howto/attach-multiple-photos-to-features/ https://merginmaps.com/docs/layer/photos/ https://merginmaps.com/docs/howto/contribute/ https://merginmaps.com/docs/misc/get-involved/ https://merginmaps.com/docs/howto/create-an-organization/ https://merginmaps.com/docs/manage/workspaces/ https://merginmaps.com/docs/howto/create-project/ https://merginmaps.com/docs/manage/create-project/ @@ -140,7 +140,7 @@ https://merginmaps.com/docs/howto/manage/plugin/install/ https://merginmaps.com/ https://merginmaps.com/docs/howto/manage/plugin/plugin-delete-project/ https://merginmaps.com/docs/manage/project-advanced/ https://merginmaps.com/docs/howto/manage/plugin/plugin-new-project/ https://merginmaps.com/docs/manage/create-project/ https://merginmaps.com/docs/howto/manage/plugin/plugin-sync-project/ https://merginmaps.com/docs/manage/plugin/ -https://merginmaps.com/docs/howto/manage/plugin/plugin-variables/ https://merginmaps.com/docs/layer/extra-variables/ +https://merginmaps.com/docs/howto/manage/plugin/plugin-variables/ https://merginmaps.com/docs/layer/variables/ https://merginmaps.com/docs/howto/manage/troubleshoot/ https://merginmaps.com/docs/misc/troubleshoot/ https://merginmaps.com/docs/howto/manage/web/dashboard/ https://merginmaps.com/docs/manage/dashboard/ https://merginmaps.com/docs/howto/manage/web/project-advanced/ https://merginmaps.com/docs/manage/project-advanced/ @@ -151,7 +151,7 @@ https://merginmaps.com/docs/howto/manage/web/web-create-project/ https://merginm https://merginmaps.com/docs/howto/manage/web/working-with-organisations/ https://merginmaps.com/docs/manage/workspaces/ https://merginmaps.com/docs/howto/mergince/ https://merginmaps.com/docs/server/ https://merginmaps.com/docs/howto/mergin-tour/ https://merginmaps.com/docs/tutorials/creating-a-project-in-qgis/ -https://merginmaps.com/docs/howto/position_variables/ https://merginmaps.com/docs/layer/extra-variables/ +https://merginmaps.com/docs/howto/position_variables/ https://merginmaps.com/docs/layer/variables/ https://merginmaps.com/docs/howto/proj/ https://merginmaps.com/docs/gis/proj/ https://merginmaps.com/docs/howto/project/enable_browsing/ https://merginmaps.com/docs/gis/search_data/ https://merginmaps.com/docs/howto/project/enable_digitising/ https://merginmaps.com/docs/gis/enable_digitising/ @@ -172,8 +172,8 @@ https://merginmaps.com/docs/layer/best-practice/ https://merginmaps.com/docs/lay https://merginmaps.com/docs/layer/exif_metadata/ https://merginmaps.com/docs/layer/exif/ https://merginmaps.com/docs/layer/form-configuration/ https://merginmaps.com/docs/layer/overview/ https://merginmaps.com/docs/layer/non-spatial-data/ https://merginmaps.com/docs/layer/overview/ -https://merginmaps.com/docs/layer/position_variables/ https://merginmaps.com/docs/layer/extra-variables/ -https://merginmaps.com/docs/layer/plugin-variables/ https://merginmaps.com/docs/layer/extra-variables/ +https://merginmaps.com/docs/layer/position_variables/ https://merginmaps.com/docs/layer/variables/ +https://merginmaps.com/docs/layer/plugin-variables/ https://merginmaps.com/docs/layer/variables/ https://merginmaps.com/docs/layer/settingup_forms/ https://merginmaps.com/docs/layer/form-widgets/ https://merginmaps.com/docs/layer/settingup_forms_photo/ https://merginmaps.com/docs/layer/photos/ https://merginmaps.com/docs/layer/settingup_forms_settings/ https://merginmaps.com/docs/layer/overview/ diff --git a/src/.vitepress/sidebar/en.js b/src/.vitepress/sidebar/en.js index 8e193570..24847c81 100644 --- a/src/.vitepress/sidebar/en.js +++ b/src/.vitepress/sidebar/en.js @@ -70,7 +70,7 @@ export default { { text: 'Numbers', link: '/layer/numbers/' }, { text: 'Checkbox', link: '/layer/checkbox/' }, { text: 'QR Code', link: '/layer/qr-code/' }, - { text: 'Selecting a Single or Multiple Values', link: '/layer/value-select/' }, + { text: 'Selecting Single or Multiple Values', link: '/layer/value-select/' }, { text: 'Photos', link: '/layer/photos/' }, { text: 'Informational Widgets', link: '/layer/info-widgets/' }, ] }, @@ -78,10 +78,10 @@ export default { collapsed: true, items: [ { text: 'Geotagging', link: '/layer/exif/' }, - { text: 'Extra Variables', link: '/layer/extra-variables/' } + { text: 'Variables', link: '/layer/variables/' } ] }, { text: 'Constraints', link: '/layer/constraints/' }, - { text: 'Attributes Form Layout', link: '/layer/form-layout/', + { text: 'Layout', link: '/layer/form-layout/', collapsed: true, items: [ { text: 'Tabs and Groups', link: '/layer/tabs-and-groups/' }, @@ -90,11 +90,11 @@ export default { { text: 'Use Cases', link: '/layer/use-cases/', collapsed: true, items: [ - { text: 'How to Open a File', link: '/layer/open-file/' }, - { text: 'How to Use Hyperlinks', link: '/layer/external-link/' }, + { text: 'How to Open a File', link: '/layer/open-file/' }, + { text: 'How to Use Hyperlinks', link: '/layer/external-link/' }, + { text: 'How to Open a Link to a Navigation App', link: '/layer/link-to-navigation/' }, { text: 'How to Link Multiple Records to One Feature (1-N Relations)', link: '/layer/one-to-n-relations/' }, { text: 'How to Embed an Image', link: '/layer/embed-image/' }, - { text: 'How to Display Instructions in the Form', link: '/layer/display-instructions/' }, ] }, ] }, { diff --git a/src/field/external_gps/index.md b/src/field/external_gps/index.md index bd69b94c..d700db99 100644 --- a/src/field/external_gps/index.md +++ b/src/field/external_gps/index.md @@ -6,7 +6,7 @@ External GPS receivers can be connected to your mobile device via Bluetooth and used in to achieve higher [GPS accuracy](../gps_accuracy/). -There are several [extra position variables](../../layer/extra-variables/#extra-position-variables) that can be useful to record when doing the survey with external GPS, such as the GPS antenna height, GPS device name as well as metrics like horizontal, vertical or position dilution of precision (HDOP, VDOP, PDOP). +There are several [extra position variables](../../layer/variables/#position-variables) that can be useful to record when doing the survey with external GPS, such as the GPS antenna height, GPS device name as well as metrics like horizontal, vertical or position dilution of precision (HDOP, VDOP, PDOP). Note that external GPS devices usually return orthometric heights (ellipsoid with the geoid separation applied). @@ -29,7 +29,7 @@ If GPS antenna height is set to a non-zero value, it is also displayed next to t ![GPS antenna height setup in Mergin Maps mobile app](./mobile-app-gps-antenna-height.jpg "GPS antenna height setup in Mergin Maps mobile app") :::tip -GPS antenna height can be recorded during the survey by using the [extra position variable](../../layer/extra-variables/#extra-position-variables) `@position_gps_antenna_height` as a [default value](../../layer/default-values/). +GPS antenna height can be recorded during the survey by using the [extra position variable](../../layer/variables/#position-variables) `@position_gps_antenna_height` as a [default value](../../layer/default-values/). ::: ## External GPS on Android diff --git a/src/field/gps_accuracy/index.md b/src/field/gps_accuracy/index.md index cc1a207d..598c1b84 100644 --- a/src/field/gps_accuracy/index.md +++ b/src/field/gps_accuracy/index.md @@ -15,7 +15,7 @@ Tapping the GPS button opens the [GPS info panel](../mobile-app-ui/#current-posi If you'd like to have higher accuracy, you can wait for your device to acquire a better GPS signal. For precise measurements, you may need to connect your device to an [external GPS](../external_gps/). -When assessing the overall quality of the survey, it may be beneficial to record some [extra position variables](../../layer/extra-variables/#extra-position-variables), such as type and name of the used GPS device, the horizontal and vertical accuracy or the horizontal, vertical or position dilution of precision (HDOP, VDOP, PDOP). +When assessing the overall quality of the survey, it may be beneficial to record some [position variables](../../layer/variables/#position-variables), such as type and name of the used GPS device, the horizontal and vertical accuracy or the horizontal, vertical or position dilution of precision (HDOP, VDOP, PDOP). :::tip diff --git a/src/field/tracking/index.md b/src/field/tracking/index.md index f47ade99..4d530c07 100644 --- a/src/field/tracking/index.md +++ b/src/field/tracking/index.md @@ -32,7 +32,7 @@ Enabled tracking means that a new line layer for tracking will be created in you | `total_distance` | Real | `$length` | Tracked distance | | `tracked_by` | String | `@mm_username` | Name of the current user | -You can add new fields as needed, however, they should be set up with automatically generated [default values](../../layer/default-values/) as will not open the form for manual inputs. You may use some of the QGIS functions, [extra position variables](../../layer/extra-variables/#extra-position-variables) or [extra QGIS variables](../../layer/extra-variables/#extra-qgis-variables). +You can add new fields as needed, however, they should be set up with automatically generated [default values](../../layer/default-values/) as will not open the form for manual inputs. You may use some of the QGIS functions, [position variables](../../layer/variables/#position-variables) or [project and user variables ](../../layer/variables/#project-and-user-variables). ## Using position tracking in Mergin Maps mobile app diff --git a/src/index.md b/src/index.md index 6a1e44da..f2fee26c 100644 --- a/src/index.md +++ b/src/index.md @@ -77,13 +77,22 @@ The ecosystem consist of various components: - [Numbers](./layer/numbers/) - [Checkbox](./layer/checkbox/) - [QR code](./layer/qr-code/) - - [Select value from a drop-down menu](./layer/value-select/) + - [Selecting Single or Multiple Values ](./layer/value-select/) - [Photos](./layer/photos/) - [Informational Widgets](./layer/info-widgets/) -- [Default Values](./layer/constraints/) -- [Constraints](./layer/default-values/) -- [Attributes Form Layout](./layer/form-layout/) +- [Default Values](./layer/default-values/) + - [Geotagging](./layer/exif/) + - [Variables](./layer/variables/) +- [Constraints](./layer/constraints/) +- [Layout](./layer/form-layout/) + - [Tabs and Groups](./layer/tabs-and-groups/) + - [Conditional Visibility](./layer/conditional-visibility/) - [Use Cases](./layer/use-cases/) + - [How to Open a File ](./layer/open-file/) + - [How to Use Hyperlinks](./layer/external-link/) + - [How to Open a Link to a Navigation App](./layer/link-to-navigation/) + - [How to Link Multiple Records to One Feature](./layer/one-to-n-relations/) + - [How to Embed an Image](./layer/embed-image/) ## Fieldwork Tips - [ Interface](./field/mobile-app-ui/) diff --git a/src/layer/attach-multiple-photos-to-features/index.md b/src/layer/attach-multiple-photos-to-features/index.md deleted file mode 100644 index 42830141..00000000 --- a/src/layer/attach-multiple-photos-to-features/index.md +++ /dev/null @@ -1,45 +0,0 @@ -# How to Attach Multiple Photos to Features - - -In some situations, it might be useful to take more than one picture of a feature during the field survey. Attaching multiple photos to one feature is a 1-N relation. You can read more about 1-N relations and how they can be used in in [How to link multiple records to one feature](../one-to-n-relations/). - - - -:::tip Example project available -To see this setup in practice, you can download the following project: -. -::: - -To link multiple photos to a single feature, we need a **unique field** to link following tables: -- Survey layer containing spatial information -- A non-spatial table containing path to the photos (see [how to setup simple photo forms](../photos/)) - -:::danger WARNING -**Do not use the FID field to link these tables**. FIDs can be changed during synchronisation, which can result in having photos linked to the incorrect feature. You can learn more about synchronisation in [Behind Data Synchronisation](../../manage/synchronisation/). -::: - -To set 1:N relation between these tables correctly: -1. Create a new text field in the survey layer, here: `unique-id` - ![Adding new text field](./uuid-field.jpg "Adding new text field") -2. Use the `uuid()` as the **default value** for this field in **Layer Properties**. This function assigns a unique identifier to every created feature, even when different surveyors create features simultaneously. - ![UUID as default value in Attributes Form](./uuid-default.jpg "UUID as default value in Attributes Form") -3. Create a new text field in the non-spatial table (here: `photos`) that will be used to store the UUID of features from the survey layer (the foreign key), here: `external-pk`. - -Now we need to configure a [1-N relation](../one-to-n-relations/): -4. From the main menu, select **Project** > **Properties ...** -5. In the **Relations** tab, select **Add Relation** - ![Add relation in Project Properties](./qgis_relation_tab.jpg "Add relation in Project Properties") - -6. Define the parent and child layer and the fields to link these layers. Here: - - **Name** is the name of the relation, can be left blank - - **Referenced (parent)** is the spatial layer `Survey` - - **Field 1** of the **Referenced (parent)** is the field `unique-id` that contains the UUID - - **Referencing (child)** is the non-spatial layer `photos` - - **Field 1** of the **Referencing (child)** layer is the `external-pk` that contains the foreign key to link photos with surveyed features. - ![Surveyed feature and photos relation setup](./qgis_relation_photos.jpg "Surveyed feature and photos relation setup") - -7. Navigate to the **Attributes Form** tab in the **Properties** of the `photos` layer. Set the **Widget Type** of the foreign key `external-pk` to **Relation Reference**: - ![Relation Reference widget in Attributes form](./qgis_relation_form.jpg "Relation Reference widget in Attributes form") - -The detects the type of 1-N relation and displays the image viewer for the relations. -![Many photos to a single feature in Mergin Maps mobile app](./mobile-multiple-photos.jpg "Many photos to a single feature in Mergin Maps mobile app") diff --git a/src/layer/attach-multiple-photos-to-features/mobile-multiple-photos.jpg b/src/layer/attach-multiple-photos-to-features/mobile-multiple-photos.jpg deleted file mode 100644 index ac94cc27..00000000 Binary files a/src/layer/attach-multiple-photos-to-features/mobile-multiple-photos.jpg and /dev/null differ diff --git a/src/layer/attach-multiple-photos-to-features/mobile-multiple-photos.xcf b/src/layer/attach-multiple-photos-to-features/mobile-multiple-photos.xcf deleted file mode 100644 index 6b1e7b2e..00000000 Binary files a/src/layer/attach-multiple-photos-to-features/mobile-multiple-photos.xcf and /dev/null differ diff --git a/src/layer/attach-multiple-photos-to-features/qgis_relation_form.jpg b/src/layer/attach-multiple-photos-to-features/qgis_relation_form.jpg deleted file mode 100644 index 6779bb99..00000000 Binary files a/src/layer/attach-multiple-photos-to-features/qgis_relation_form.jpg and /dev/null differ diff --git a/src/layer/attach-multiple-photos-to-features/qgis_relation_form.xcf b/src/layer/attach-multiple-photos-to-features/qgis_relation_form.xcf deleted file mode 100644 index db21b393..00000000 Binary files a/src/layer/attach-multiple-photos-to-features/qgis_relation_form.xcf and /dev/null differ diff --git a/src/layer/attach-multiple-photos-to-features/qgis_relation_photos.jpg b/src/layer/attach-multiple-photos-to-features/qgis_relation_photos.jpg deleted file mode 100644 index 1962b940..00000000 Binary files a/src/layer/attach-multiple-photos-to-features/qgis_relation_photos.jpg and /dev/null differ diff --git a/src/layer/attach-multiple-photos-to-features/qgis_relation_photos.xcf b/src/layer/attach-multiple-photos-to-features/qgis_relation_photos.xcf deleted file mode 100644 index 43db54bf..00000000 Binary files a/src/layer/attach-multiple-photos-to-features/qgis_relation_photos.xcf and /dev/null differ diff --git a/src/layer/attach-multiple-photos-to-features/qgis_relation_tab.jpg b/src/layer/attach-multiple-photos-to-features/qgis_relation_tab.jpg deleted file mode 100644 index eaacfcf4..00000000 Binary files a/src/layer/attach-multiple-photos-to-features/qgis_relation_tab.jpg and /dev/null differ diff --git a/src/layer/attach-multiple-photos-to-features/qgis_relation_tab.xcf b/src/layer/attach-multiple-photos-to-features/qgis_relation_tab.xcf deleted file mode 100644 index ddfc97ac..00000000 Binary files a/src/layer/attach-multiple-photos-to-features/qgis_relation_tab.xcf and /dev/null differ diff --git a/src/layer/attach-multiple-photos-to-features/uuid-default.jpg b/src/layer/attach-multiple-photos-to-features/uuid-default.jpg deleted file mode 100644 index f9b16777..00000000 Binary files a/src/layer/attach-multiple-photos-to-features/uuid-default.jpg and /dev/null differ diff --git a/src/layer/attach-multiple-photos-to-features/uuid-default.xcf b/src/layer/attach-multiple-photos-to-features/uuid-default.xcf deleted file mode 100644 index 1ce56359..00000000 Binary files a/src/layer/attach-multiple-photos-to-features/uuid-default.xcf and /dev/null differ diff --git a/src/layer/attach-multiple-photos-to-features/uuid-field.jpg b/src/layer/attach-multiple-photos-to-features/uuid-field.jpg deleted file mode 100644 index c1361923..00000000 Binary files a/src/layer/attach-multiple-photos-to-features/uuid-field.jpg and /dev/null differ diff --git a/src/layer/attach-multiple-photos-to-features/uuid-field.xcf b/src/layer/attach-multiple-photos-to-features/uuid-field.xcf deleted file mode 100644 index a98c0275..00000000 Binary files a/src/layer/attach-multiple-photos-to-features/uuid-field.xcf and /dev/null differ diff --git a/src/layer/checkbox/index.md b/src/layer/checkbox/index.md index 9f510e9f..90ed13af 100644 --- a/src/layer/checkbox/index.md +++ b/src/layer/checkbox/index.md @@ -1,43 +1,47 @@ -# Checkbox - -The checkbox widget is handy when you want to set up a field that can have two values, such as true/false, Yes/No, or On/Off. - -|
Widget
|Preview in the | -|:---:|:---:| -| [True/false checkbox](#true-false-checkbox-for-boolean-fields) | ![Mergin Maps mobile app numeric field form](./mobile-form-checkbox-preview.webp "Mergin Maps mobile app numeric field form") | -| [Checkbox with custom values](#checkbox-with-custom-values-yes-no) | ![Mergin Maps mobile app numeric field form](./mobile-form-checkbox-string-preview.webp "Mergin Maps mobile app numeric field form") | - -:::tip Example project available -Checkbox widget is used in this public project . Download or clone it to see the setup. -::: - -Prefer a video? Here is a short tutorial about the checkbox widget: - - - -## True/false checkbox for Boolean fields - -If you have a field with a **Boolean** data type, QGIS assigns the checkbox widget type by default. It is also possible to use it for fields with [other data types](#checkbox-with-custom-values-yes-no). - -1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. -2. In the list of **Available Widgets** select the field you want to work with (here: `checkbox`). -3. In the **Widget Type** tab, the **Checkbox** widget should be set by default (if not, select it from the drop-down menu). -4. **Apply** the changes. Don't forget to save and sync your project! - -![QGIS checkbox field form](./qgis-form-checkbox.jpg "QGIS checkbox field form") - -## Checkbox with custom values (yes/no) -You might want to use the checkbox with custom values, such as Yes/No or On/Off. This is possible for fields with **Text** (string) data type: -1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. -2. In the list of **Available Widgets** select the field you want to work with (here: `checkbox-string`). -3. In the **Widget Type** tab, select the **Checkbox** widget and define values for the *Checked* and for the *Unchecked* state. Here we use `Yes` and `No`. -4. **Apply** the changes. Don't forget to save and sync your project! - -![QGIS checkbox field form](./qgis-form-checkbox-string.jpg "QGIS checkbox field form") - -Similarly, you could set up checkbox for fields with integer data types and use numerical values, e.g. `0` and `1`, for the *Checked* and for the *Unchecked* state. - -In the , the checkbox can be easily toggled on/off. - -![Mergin Maps mobile app checkbox field form](./mobile-form-checkbox.jpg "Mergin Maps mobile app checkbox field form") - +--- +description: The checkbox widget is useful when you need a simple yes/no, true/false, or on/off toggle in the attributes form. +--- + +# Checkbox + +The checkbox widget is handy when you want to set up a field that can have two values, such as true/false, Yes/No, or On/Off. + +|
Widget
|Preview in the | +|:---:|:---:| +| True/false checkbox | ![Mergin Maps mobile app numeric field form](./mobile-form-checkbox-preview.webp "Mergin Maps mobile app numeric field form") | + + +:::tip Example project available +Checkbox widget is used in this public project . Download or clone it to see the setup. +::: + +Prefer a video? Here is a short tutorial about the checkbox widget: + + + +## True/false checkbox for Boolean fields + +If you have a field with a `Boolean` data type, QGIS assigns the checkbox widget type by default. It is also possible to use it for fields with [other data types](#checkbox-with-custom-values-yes-no). + +1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. +2. In the list of **Available Widgets** select the field you want to work with (here: `checkbox`). +3. In the **Widget Type** tab, the **Checkbox** widget should be set by default (if not, select it from the drop-down menu). +4. **Apply** the changes. Don't forget to save and sync your project! + +![QGIS checkbox field form](./qgis-form-checkbox.jpg "QGIS checkbox field form") + +## Checkbox with custom values (yes/no) +You might want to use the checkbox with custom values, such as Yes/No or On/Off. This is possible for fields with `Text (string)` data type: +1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. +2. In the list of **Available Widgets** select the field you want to work with (here: `checkbox-string`). +3. In the **Widget Type** tab, select the **Checkbox** widget and define values for the *Checked* and for the *Unchecked* state. Here we use `Yes` and `No`. +4. **Apply** the changes. Don't forget to save and sync your project! + +![QGIS checkbox field form](./qgis-form-checkbox-string.jpg "QGIS checkbox field form") + +Similarly, you could set up the checkbox widget for fields with integer data types and use numerical values, e.g. `0` and `1`, for the *Checked* and for the *Unchecked* state. + +In the , the checkbox can be easily toggled on/off. + +![Mergin Maps mobile app checkbox field form](./mobile-form-checkbox.jpg "Mergin Maps mobile app checkbox field form") + diff --git a/src/layer/checkbox/mobile-form-checkbox-string-preview.webp b/src/layer/checkbox/mobile-form-checkbox-string-preview.webp deleted file mode 100644 index 3858ab5e..00000000 Binary files a/src/layer/checkbox/mobile-form-checkbox-string-preview.webp and /dev/null differ diff --git a/src/layer/checkbox/mobile-form-checkbox-string-preview.xcf b/src/layer/checkbox/mobile-form-checkbox-string-preview.xcf deleted file mode 100644 index 0c51b73d..00000000 Binary files a/src/layer/checkbox/mobile-form-checkbox-string-preview.xcf and /dev/null differ diff --git a/src/layer/conditional-visibility/index.md b/src/layer/conditional-visibility/index.md index 04be7977..463547ac 100644 --- a/src/layer/conditional-visibility/index.md +++ b/src/layer/conditional-visibility/index.md @@ -1,25 +1,29 @@ -# Conditional Visibility -Conditional visibility can be applied to groups and tabs, so that they will be displayed or hidden depending on the value of a field. - -:::tip Example project available -You can explore this functionality in . -::: - -Here we will use a line layer named `roads and paths`. It is designed for surveying both roads and paths and most of the fields are relevant for every type of feature in this layer. However, there are some attributes that are specific for roads (e.g. the number of lanes) or for paths (e.g. the visibility of the path). - -The form uses the value of the `type` field to display the relevant set of attributes. The `type` field is set up as [value map](../value-select/#value-map) with defined values `road` and `path`. - -![QGIS form value map](./qgis-form-value-map-roads.jpg "QGIS form value map") - -To set the visibility of groups in the attributes form: -1. Click on the **roads** group in the **Form Layout** -2. Check the **Control Visibility by Expression** option :heavy_check_mark: -3. Define the expression. Here we use: `"type" = "road"` - -![QGIS form control visibility by expression](./qgis-form-conditional-visibility.jpg "QGIS form control visibility by expression") - -4. Same steps are used for the **path** group using the expression `"type" = "path"` - -In the , the form displays these groups only when the condition is met. So, there are different sets of attributes depending on the value that is entered in the `type` field. - -![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") +--- +description: Conditional visibility can be applied to groups and tabs, so that they will be displayed or hidden in the form depending on the value of a field. +--- + +# Conditional Visibility +Conditional visibility can be applied to groups and tabs, so that they will be displayed or hidden depending on the value of a field. + +:::tip Example project available +You can explore this functionality in . +::: + +Here we will use a line layer named `roads and paths`. It is designed for surveying both roads and paths and most of the fields are relevant for every type of feature in this layer. However, there are some attributes that are specific for roads (e.g. the number of lanes) or for paths (e.g. the visibility of the path). + +The form uses the value of the `type` field to display the relevant set of attributes. The `type` field is set up as a [value map](../value-select/#value-map) with defined values `road` and `path`. + +![QGIS form value map](./qgis-form-value-map-roads.jpg "QGIS form value map") + +To set the visibility of groups in the attributes form: +1. Click on the **roads** group in the **Form Layout** +2. Check the **Control Visibility by Expression** option :heavy_check_mark: +3. Define the expression. Here we use: `"type" = "road"` + +![QGIS form control visibility by expression](./qgis-form-conditional-visibility.jpg "QGIS form control visibility by expression") + +4. Same steps are used for the **path** group using the expression `"type" = "path"` + +In the , the form displays these groups only when the condition is met. So, there are different sets of attributes depending on the value that is entered in the `type` field. + +![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") diff --git a/src/layer/constraints/index.md b/src/layer/constraints/index.md index 9b2b2c9b..bf59399a 100644 --- a/src/layer/constraints/index.md +++ b/src/layer/constraints/index.md @@ -1,34 +1,38 @@ -# Constraints -Constraints help to avoid mistakes when filling in the values or to highlight mandatory fields. Fields with constraints have a warning displayed next to them in the form. - -There are multiple options of setting up constraints in , such as *Not null* (the field has to be filled in), *Unique* (the field has to have a unique value), or using a custom *expression*. - -Check the **enforce constraint** option :heavy_check_mark: to use a hard constraint, meaning that the feature cannot be saved if the constraints are not met. - -### Using hard and soft constraints in the form - -:::tip Example project available -Constraints are used in this project . Clone or download it to try it to see how it works. -::: - -Here, we will first set up a constraint to a field that represents the facility capacity. The value has to be a number that is higher than 0. This will be a *hard* constraint: if the value is not higher than 0, the feature cannot be saved. - -1. Right-click on a survey layer and select **Properties** -2. In the **Attributes form** tab, select a numeric field in the **Available Widgets** column that you want to use (here: `number`) -3. In the **Constraints** tab: - - Use the following **Expression**: `"number" >= 1` - - Check the **Enforce expression constraint** option :heavy_check_mark: - -![QGIS constraints in attributes form](./qgis-form-constraints.jpg "QGIS constraints in attributes form") - -Now we will set up a *soft* constraint to a photo field. A photo should be taken during the survey, but the feature can be saved without one. - -1. In the **Attributes form** tab, select a photo field in the **Available Widgets** column (here: `photo`) -2. In the **Constraints** tab: - - Check the **Not null** constraint :heavy_check_mark: - - -In the , you will be unable to save a feature unless the field value meets the *enforced* constraint (here: `Capacity`). If the constraint is *not enforced* (here: `photo`), there will be a warning, but the feature can be saved regardless. - -![Mergin Maps mobile app constraints in attributes form](./mobile-form-constaints.jpg "Mergin Maps mobile app constraints in attributes form") - +--- +description: Constraints help to avoid mistakes when filling in the values or to highlight mandatory fields in the attributes form. +--- + +# Constraints +Constraints help to avoid mistakes when filling in the values or to highlight mandatory fields. Fields with constraints have a warning displayed next to them in the form. + +There are multiple options of setting up constraints in , such as *Not null* (the field has to be filled in), *Unique* (the field has to have a unique value), or using a custom *expression*. + +Check the **enforce constraint** option :heavy_check_mark: to use a hard constraint, meaning that the feature cannot be saved if the constraints are not met. + +### Using hard and soft constraints in the form + +:::tip Example project available +Constraints are used in this project . Clone or download it to try it to see how it works. +::: + +Here, we will first set up a constraint to a field that represents the facility capacity. The value has to be a number that is higher than 0. This will be a *hard* constraint: if the value is not higher than 0, the feature cannot be saved. + +1. Right-click on a survey layer and select **Properties** +2. In the **Attributes form** tab, select a numeric field in the **Available Widgets** column that you want to use (here: `number`) +3. In the **Constraints** tab: + - Use the following **Expression**: `"number" >= 1` + - Check the **Enforce expression constraint** option :heavy_check_mark: + +![QGIS constraints in attributes form](./qgis-form-constraints.jpg "QGIS constraints in attributes form") + +Now we will set up a *soft* constraint to a photo field. A photo should be taken during the survey, but the feature can be saved without one. + +1. In the **Attributes form** tab, select a photo field in the **Available Widgets** column (here: `photo`) +2. In the **Constraints** tab: + - Check the **Not null** constraint :heavy_check_mark: + + +In the , you will be unable to save a feature unless the field value meets the *enforced* constraint (here: `Capacity`). If the constraint is *not enforced* (here: `photo`), there will be a warning, but the feature can be saved regardless. + +![Mergin Maps mobile app constraints in attributes form](./mobile-form-constaints.jpg "Mergin Maps mobile app constraints in attributes form") + diff --git a/src/layer/constraints/mobile-drill-down-form.gif b/src/layer/constraints/mobile-drill-down-form.gif deleted file mode 100644 index 6b72ef5e..00000000 Binary files a/src/layer/constraints/mobile-drill-down-form.gif and /dev/null differ diff --git a/src/layer/constraints/mobile-form-default-values-coordinates.jpg b/src/layer/constraints/mobile-form-default-values-coordinates.jpg deleted file mode 100644 index 48924ff0..00000000 Binary files a/src/layer/constraints/mobile-form-default-values-coordinates.jpg and /dev/null differ diff --git a/src/layer/constraints/mobile-form-default-values-coordinates.xcf b/src/layer/constraints/mobile-form-default-values-coordinates.xcf deleted file mode 100644 index d1f4e1a3..00000000 Binary files a/src/layer/constraints/mobile-form-default-values-coordinates.xcf and /dev/null differ diff --git a/src/layer/constraints/mobile-form-default-values-timestamp-username.jpg b/src/layer/constraints/mobile-form-default-values-timestamp-username.jpg deleted file mode 100644 index cafbfb35..00000000 Binary files a/src/layer/constraints/mobile-form-default-values-timestamp-username.jpg and /dev/null differ diff --git a/src/layer/constraints/mobile-form-default-values-timestamp-username.xcf b/src/layer/constraints/mobile-form-default-values-timestamp-username.xcf deleted file mode 100644 index 9c6f7790..00000000 Binary files a/src/layer/constraints/mobile-form-default-values-timestamp-username.xcf and /dev/null differ diff --git a/src/layer/constraints/mobile-forms-open-file-default-value.jpg b/src/layer/constraints/mobile-forms-open-file-default-value.jpg deleted file mode 100644 index d4d7f568..00000000 Binary files a/src/layer/constraints/mobile-forms-open-file-default-value.jpg and /dev/null differ diff --git a/src/layer/constraints/mobile-forms-open-file-default-value.xcf b/src/layer/constraints/mobile-forms-open-file-default-value.xcf deleted file mode 100644 index 3cd7beb2..00000000 Binary files a/src/layer/constraints/mobile-forms-open-file-default-value.xcf and /dev/null differ diff --git a/src/layer/constraints/qgis-drill-down-form.gif b/src/layer/constraints/qgis-drill-down-form.gif deleted file mode 100644 index 8a692150..00000000 Binary files a/src/layer/constraints/qgis-drill-down-form.gif and /dev/null differ diff --git a/src/layer/constraints/qgis-form-default-coordinates.jpg b/src/layer/constraints/qgis-form-default-coordinates.jpg deleted file mode 100644 index 9c9a5fe4..00000000 Binary files a/src/layer/constraints/qgis-form-default-coordinates.jpg and /dev/null differ diff --git a/src/layer/constraints/qgis-form-default-coordinates.xcf b/src/layer/constraints/qgis-form-default-coordinates.xcf deleted file mode 100644 index ad4fc466..00000000 Binary files a/src/layer/constraints/qgis-form-default-coordinates.xcf and /dev/null differ diff --git a/src/layer/constraints/qgis-form-default-inserted-by.jpg b/src/layer/constraints/qgis-form-default-inserted-by.jpg deleted file mode 100644 index 257907ae..00000000 Binary files a/src/layer/constraints/qgis-form-default-inserted-by.jpg and /dev/null differ diff --git a/src/layer/constraints/qgis-form-default-inserted-by.xcf b/src/layer/constraints/qgis-form-default-inserted-by.xcf deleted file mode 100644 index 21be6797..00000000 Binary files a/src/layer/constraints/qgis-form-default-inserted-by.xcf and /dev/null differ diff --git a/src/layer/constraints/qgis-form-default-updated-by.jpg b/src/layer/constraints/qgis-form-default-updated-by.jpg deleted file mode 100644 index aa302e7d..00000000 Binary files a/src/layer/constraints/qgis-form-default-updated-by.jpg and /dev/null differ diff --git a/src/layer/constraints/qgis-form-default-updated-by.xcf b/src/layer/constraints/qgis-form-default-updated-by.xcf deleted file mode 100644 index a2b84828..00000000 Binary files a/src/layer/constraints/qgis-form-default-updated-by.xcf and /dev/null differ diff --git a/src/layer/constraints/qgis-form-default-values.jpg b/src/layer/constraints/qgis-form-default-values.jpg deleted file mode 100644 index 27dd3dde..00000000 Binary files a/src/layer/constraints/qgis-form-default-values.jpg and /dev/null differ diff --git a/src/layer/constraints/qgis-form-default-values.xcf b/src/layer/constraints/qgis-form-default-values.xcf deleted file mode 100644 index 235d6418..00000000 Binary files a/src/layer/constraints/qgis-form-default-values.xcf and /dev/null differ diff --git a/src/layer/constraints/qgis-form-open-file-default-value.jpg b/src/layer/constraints/qgis-form-open-file-default-value.jpg deleted file mode 100644 index 9e95c9a5..00000000 Binary files a/src/layer/constraints/qgis-form-open-file-default-value.jpg and /dev/null differ diff --git a/src/layer/constraints/qgis-form-open-file-default-value.xcf b/src/layer/constraints/qgis-form-open-file-default-value.xcf deleted file mode 100644 index 9303af2d..00000000 Binary files a/src/layer/constraints/qgis-form-open-file-default-value.xcf and /dev/null differ diff --git a/src/layer/constraints/qgis-form-value-relation-expression-subtype.jpg b/src/layer/constraints/qgis-form-value-relation-expression-subtype.jpg deleted file mode 100644 index 83c8b714..00000000 Binary files a/src/layer/constraints/qgis-form-value-relation-expression-subtype.jpg and /dev/null differ diff --git a/src/layer/constraints/qgis-form-value-relation-expression-subtype.xcf b/src/layer/constraints/qgis-form-value-relation-expression-subtype.xcf deleted file mode 100644 index 4d3c95da..00000000 Binary files a/src/layer/constraints/qgis-form-value-relation-expression-subtype.xcf and /dev/null differ diff --git a/src/layer/constraints/qgis-form-value-relation-expression.jpg b/src/layer/constraints/qgis-form-value-relation-expression.jpg deleted file mode 100644 index 3dc1c00d..00000000 Binary files a/src/layer/constraints/qgis-form-value-relation-expression.jpg and /dev/null differ diff --git a/src/layer/constraints/qgis-form-value-relation-expression.xcf b/src/layer/constraints/qgis-form-value-relation-expression.xcf deleted file mode 100644 index 19697b54..00000000 Binary files a/src/layer/constraints/qgis-form-value-relation-expression.xcf and /dev/null differ diff --git a/src/layer/constraints/qgis-form-value-relation.jpg b/src/layer/constraints/qgis-form-value-relation.jpg deleted file mode 100644 index 2d2102ea..00000000 Binary files a/src/layer/constraints/qgis-form-value-relation.jpg and /dev/null differ diff --git a/src/layer/constraints/qgis-form-value-relation.xcf b/src/layer/constraints/qgis-form-value-relation.xcf deleted file mode 100644 index eb31cd1a..00000000 Binary files a/src/layer/constraints/qgis-form-value-relation.xcf and /dev/null differ diff --git a/src/layer/constraints/qgis-table-habitat.jpg b/src/layer/constraints/qgis-table-habitat.jpg deleted file mode 100644 index 1f5c10c0..00000000 Binary files a/src/layer/constraints/qgis-table-habitat.jpg and /dev/null differ diff --git a/src/layer/constraints/qgis-table-habitat.xcf b/src/layer/constraints/qgis-table-habitat.xcf deleted file mode 100644 index aa92df58..00000000 Binary files a/src/layer/constraints/qgis-table-habitat.xcf and /dev/null differ diff --git a/src/layer/constraints/qgis-table-subtype.jpg b/src/layer/constraints/qgis-table-subtype.jpg deleted file mode 100644 index ece624e4..00000000 Binary files a/src/layer/constraints/qgis-table-subtype.jpg and /dev/null differ diff --git a/src/layer/constraints/qgis-table-subtype.xcf b/src/layer/constraints/qgis-table-subtype.xcf deleted file mode 100644 index e04e5c14..00000000 Binary files a/src/layer/constraints/qgis-table-subtype.xcf and /dev/null differ diff --git a/src/layer/constraints/qgis-table-type.jpg b/src/layer/constraints/qgis-table-type.jpg deleted file mode 100644 index 5154b899..00000000 Binary files a/src/layer/constraints/qgis-table-type.jpg and /dev/null differ diff --git a/src/layer/constraints/qgis-table-type.xcf b/src/layer/constraints/qgis-table-type.xcf deleted file mode 100644 index 4238fbcf..00000000 Binary files a/src/layer/constraints/qgis-table-type.xcf and /dev/null differ diff --git a/src/layer/date-time/index.md b/src/layer/date-time/index.md index cfeefd89..e06452dc 100644 --- a/src/layer/date-time/index.md +++ b/src/layer/date-time/index.md @@ -1,50 +1,54 @@ -# Date and time - -**Date** or **Date and Time** fields can be used to record date and time. The most common use is to record when a feature was created or updated. This can be done manually or automatically by using [default values](../default-values/). - -|
Widget
|Preview in the | -|:---:|:---:| -|[Date/time](#date-time-widget) |![Mergin Maps mobile app date time field form](./mobile-form-datetime-preview.jpg "Mergin Maps mobile app date time field form") | - -:::tip Example project available -Various options of setting up Date and Date&Time fields are included in this public project: . Download or clone it to explore it in more detail. -::: - -Prefer a video? Here is a short tutorial about date widgets: - - -## Date/Time widget - -To set up the **Date/Time** widget: - -1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. - -2. In the list of **Available Widgets** select the Date and Time field you want to work with (here: `datetime`). - -3. In the **Widget Type** tab and select the **Date/Time** widget. - - use the default display format or set a custom display format (see [custom date and time formats](#custom-date-and-time-formats)) - - check the **Calendar popup** option :heavy_check_mark: - - use the preview to confirm that this is the format you want to use to store your timestamps - - ![QGIS date time field form](./qgis-form-datetime.jpg "QGIS date time field form") - -4. If you want to automatically insert the date (or date and time) when the feature is created, use `now()` as a [default value](../default-values/) in the **Defaults** tab. - -5. **Apply** the changes. Don't forget to save and sync your project! - -In the , the date can be edited using a calendar pop up. If you tap the icon next to the field, the current date and time will be filled in. - -![Mergin Maps mobile app calendar form date time fields](./mobile-form-datetime.jpg "Mergin Maps mobile app calendar form date time fields") - -## Custom date and time formats -Date and time fields can use custom display format. - -Here are some common examples: - -| Custom Display Format | Preview | -|:-------------------------------:|:-------------------:| -| `dd.MM.yyyy` | 12.01.2024 | -| `MMMM d yyyy` | January 12 2024 | -| `HH:mm:ss` | 12:34:56 | -| `yyyy-MM-dd HH:mm:ss` | 2020-09-09 12:34:56 | -| `dd/MM/yyyy HH-mm-ss` | 09/09/2020 12-34-56 | +--- +description: Date or Date and Time widgets are used to record date and time, e.g. when a feature was created or updated. +--- + +# Date and time + +Fields with `Date` or `Date and Time` data type can be used to record date and time. The most common use is to record when a feature was created or updated. This can be done manually or automatically by using [default values](../default-values/). + +|
Widget
|Preview in the | +|:---:|:---:| +|Date/time |![Mergin Maps mobile app date time field form](./mobile-form-datetime-preview.jpg "Mergin Maps mobile app date time field form") | + +:::tip Example project available +Various options of setting up Date and Date&Time fields are included in this public project: . Download or clone it to explore it in more detail. +::: + +Prefer a video? Here is a short tutorial about date widgets: + + +## Date/Time widget + +To set up the **Date/Time** widget: + +1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. + +2. In the list of **Available Widgets** select the Date and Time field you want to work with (here: `datetime`). + +3. In the **Widget Type** tab and select the **Date/Time** widget. + - use the default display format or set a custom display format (see [custom date and time formats](#custom-date-and-time-formats)) + - check the **Calendar popup** option :heavy_check_mark: + - use the preview to confirm that this is the format you want to use to store your timestamps + + ![QGIS date time field form](./qgis-form-datetime.jpg "QGIS date time field form") + +4. If you want to automatically insert the date (or date and time) when the feature is created, use `now()` as a [default value](../default-values/) in the **Defaults** tab. + +5. **Apply** the changes. Don't forget to save and sync your project! + +In the , the date can be edited using a calendar pop up. If you tap the icon next to the field, the current date and time will be filled in. + +![Mergin Maps mobile app calendar form date time fields](./mobile-form-datetime.jpg "Mergin Maps mobile app calendar form date time fields") + +## Custom date and time formats +Date and time fields can use custom display format. + +Here are some common examples: + +| Custom Display Format | Preview | +|:-------------------------------:|:-------------------:| +| `dd.MM.yyyy` | 12.01.2024 | +| `MMMM d yyyy` | January 12 2024 | +| `HH:mm:ss` | 12:34:56 | +| `yyyy-MM-dd HH:mm:ss` | 2020-09-09 12:34:56 | +| `dd/MM/yyyy HH-mm-ss` | 09/09/2020 12-34-56 | diff --git a/src/layer/default-values/index.md b/src/layer/default-values/index.md index 3954e1f5..c7a33d4b 100644 --- a/src/layer/default-values/index.md +++ b/src/layer/default-values/index.md @@ -1,98 +1,102 @@ -# Default values -Default values can be used to automatically record, e.g, the name of the surveyor, date and time of the survey, latitude and longitude of a feature or to have frequently used values filled in advance (see ). - -Fields with default values can be hidden from the attributes form if they are used to store data that are not expected to be modified manually. - -The default value can be a text, number or a QGIS expression. The data format of the field has to match the result of the default value expression you want to use. - -In QGIS, default values can be set up in the **Attributes Form** tab in **Layer Properties**. In the **Defaults** tab, you can enter the default value of the selected field (manually or using an expression). - -![Default values in QGIS attributes form](./qgis-form-default-values.jpg "Default values in QGIS attributes form") - -Check the option **Apply default value on update** :heavy_check_mark: to update the field value after every change of a feature. Note that this means that the value of this field cannot be changed manually in QGIS or in the as any user input will be overwritten by the default value. - -This option is therefore useful for fields that can be recorded automatically without the need of modification, such as parameters derived from geometry (e.g. [coordinates, length, area](#examples-of-useful-default-values)) or [usernames, dates, times](#recording-usernames-dates-and-times-automatically). - -::: tip Example project available -Various usage of default values can be explored in more detail by downloading or cloning this public project . -::: - -## Useful default values examples {#examples-of-useful-default-values} -There are some commonly used default values that can be useful in your field survey. - -- `uuid()` function generates a unique identifier that is needed to correctly setup [1-N relations](../relations/) or [value relations](../value-select/#value-relation) - -- 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 this information. You can change the formatting using the [Date/Time](../date-time/) widget. - -- The name of the user who created or modified the feature can be recorded using the `@mergin_username` variable. These fields should use **Text (string)** data type. - There are also other [extra QGIS variables](../extra-variables/#extra-qgis-variables) related to your account or service that can be used as default values. - -- 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 metres, 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. - -- Parameters such as **length** of a line feature or **area** of a polygon feature can be calculated from the geometry. These fields should have the **Decimal number (real)** or **Integer** data type. Use the *apply default value on update* option to update the field in case there is a change in the feature. - -- [Extra Position Variables](../extra-variables/#extra-position-variables) can be used to record GPS information from your mobile devices - -Here are some examples: - -| Variable name | Sample value | Apply default value on update | Description | -|-----------------------------|-------------------------------|---------|-------------| -| `uuid()` | `{9d0150eb-a36f-40f1-a768-540db8a36f7c}` | **no** | Generates (Universally Unique Identifier).| -| `@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.| -| `$length` | `123.45` | **yes** | The length of a line feature.| -| `$area` | `1234.56` | **yes** | The area of a polygon feature.| - -## Recording usernames, dates and times automatically - -Let's set up an attributes to record the username of the surveyor who *created* a feature: -1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. -2. In the list of **Available Widgets** select the text field you want to use (here: `inserted_by`) -3. In the **Defaults** tab, define the **Default value** as `@mergin_username`. - Do not check the **Apply default value on update** option :white_large_square:. - -![QGIS attributes form Mergin Maps username default value](./qgis-form-default-inserted-by.jpg "QGIS attributes form Mergin Maps username default value") - -To save the username of the surveyor who *modified* this feature, the steps are similar: -1. In the list of **Available Widgets** select the text field you want to use (here: `updated_by`) -2. In the **Defaults** tab, define the **Default value** as `@mergin_username`. - Check the **Apply default value on update** option :heavy_check_mark:. The field will be updated anytime the feature is modified, saving the name of the surveyor who made the changes. - -![QGIS attributes form Mergin Maps username default value](./qgis-form-default-updated-by.jpg "QGIS attributes form Mergin Maps username default value") - -Follow the same steps for attributes to store the timestamps of when the feature was created and updated (here: `inserted_at`, `updated_at`), using the `now()` expression as **Default value**. - -When the form is opened in the , the default values are automatically filled in: - -![Mergin Maps mobile app attributes form default values](./mobile-form-default-values-timestamp-username.jpg "Mergin Maps mobile app attributes form default values") - -## Automatically transform and record coordinates of a point -Here we are going to set the default values for `x` and `y` field to be longitude and latitude. - -1. Right-click on the survey layer and select **Properties** -2. In the **Attributes form** tab, select the `x` field in the **Available Widgets** column on the left -3. In the **Widget Display**, set the **Alias** to *Longitude* -4. In **Defaults** tab, define the **Default value** as: - ``` - x( transform( $geometry, 'EPSG:3857', 'EPSG:4326')) - ``` - Note that the expression transforms the point from EPSG:3857 (map and layer coordinate reference system) to EPSG:4326. -5. Check the **Apply default value on update** option :heavy_check_mark:. - -![QGIS attributes form transform and record coordinates by default](./qgis-form-default-coordinates.jpg "QGIS attributes form transform and record coordinates by default") - -Repeat the same steps for `y` field and setting the **Alias** to *Latitude* and the default value to - -``` -y( transform( $geometry, 'EPSG:3857', 'EPSG:4326')) -``` - -Don't forget to save and synchronise your project! - -When adding or editing features in the , the coordinates are automatically filled in: - -![Mergin Maps mobile app attributes form default values](./mobile-form-default-values-coordinates.jpg "Mergin Maps mobile app attributes form default values") - +--- +description: Default values can be used to automatically fill in the fields in the form using values, variables or expressions. +--- + +# Default values +Default values can be used to automatically record, e.g. the name of the surveyor, date and time of the survey, latitude and longitude of a feature or to have frequently used values filled in advance (see ). + +Fields with default values can be hidden from the attributes form if they are used to store data that are not expected to be modified manually. + +The default value can be a text, number or a QGIS expression. The data format of the field has to match the result of the default value expression you want to use. + +In QGIS, default values can be set up in the **Attributes Form** tab in **Layer Properties**. In the **Defaults** tab, you can enter the default value of the selected field (manually or using an expression). + +![Default values in QGIS attributes form](./qgis-form-default-values.jpg "Default values in QGIS attributes form") + +Check the option **Apply default value on update** :heavy_check_mark: to update the field value after every change of a feature. Note that this means that the value of this field cannot be changed manually in QGIS or in the as any user input will be overwritten by the default value. + +This option is therefore useful for fields that can be recorded automatically without the need of modification, such as parameters derived from geometry (e.g. [coordinates, length, area](#examples-of-useful-default-values)) or [usernames, dates, times](#recording-usernames-dates-and-times-automatically). + +::: tip Example project available +Various usage of default values can be explored in more detail by downloading or cloning this public project . +::: + +## Useful default values examples {#examples-of-useful-default-values} +There are some commonly used default values that can be useful in your field survey. + +- `uuid()` function generates a unique identifier that is needed to correctly setup [1-N relations](../relations/) or [value relations](../value-select/#value-relation) + +- 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 this information. You can change the formatting using the [Date/Time](../date-time/) widget. + +- The name of the user who created or modified the feature can be recorded using the `@mm_username` variable. These fields should use **Text (string)** data type. + There are also other [project and user variables](../variables/#project-and-user-variables) related to your account or service that can be used as default values. + +- 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 metres, 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. + +- Parameters such as **length** of a line feature or **area** of a polygon feature can be calculated from the geometry. These fields should have the **Decimal number (real)** or **Integer** data type. Use the *apply default value on update* option to update the field in case there is a change in the feature. + +- [Position Variables](../variables/#position-variables) can be used to record GPS information from your mobile devices + +Here are some examples: + +| Variable name | Sample value | Apply default value on update | Description | +|-----------------------------|-------------------------------|---------|-------------| +| `uuid()` | `{9d0150eb-a36f-40f1-a768-540db8a36f7c}` | **no** | Generates (Universally Unique Identifier).| +| `@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**. | +| `@mm_username` | `sarah` | **no** | Name of the user who created this feature.| +| `@mm_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.| +| `$length` | `123.45` | **yes** | The length of a line feature.| +| `$area` | `1234.56` | **yes** | The area of a polygon feature.| + +## Recording usernames, dates and times automatically + +Let's set up an attributes to record the username of the surveyor who *created* a feature: +1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. +2. In the list of **Available Widgets** select the text field you want to use (here: `inserted_by`) +3. In the **Defaults** tab, define the **Default value** as `@mm_username`. + Do not check the **Apply default value on update** option :white_large_square:. + +![QGIS attributes form Mergin Maps username default value](./qgis-form-default-inserted-by.jpg "QGIS attributes form Mergin Maps username default value") + +To save the username of the surveyor who *modified* this feature, the steps are similar: +1. In the list of **Available Widgets** select the text field you want to use (here: `updated_by`) +2. In the **Defaults** tab, define the **Default value** as `@mm_username`. + Check the **Apply default value on update** option :heavy_check_mark:. The field will be updated anytime the feature is modified, saving the name of the surveyor who made the changes. + +![QGIS attributes form Mergin Maps username default value](./qgis-form-default-updated-by.jpg "QGIS attributes form Mergin Maps username default value") + +Follow the same steps for attributes to store the timestamps of when the feature was created and updated (here: `inserted_at`, `updated_at`), using the `now()` expression as **Default value**. + +When the form is opened in the , the default values are automatically filled in: + +![Mergin Maps mobile app attributes form default values](./mobile-form-default-values-timestamp-username.jpg "Mergin Maps mobile app attributes form default values") + +## Automatically transform and record coordinates of a point +Here we are going to set the default values for `x` and `y` field to be longitude and latitude. + +1. Right-click on the survey layer and select **Properties** +2. In the **Attributes form** tab, select the `x` field in the **Available Widgets** column on the left +3. In the **Widget Display**, set the **Alias** to *Longitude* +4. In **Defaults** tab, define the **Default value** as: + ``` + x( transform( $geometry, 'EPSG:3857', 'EPSG:4326')) + ``` + Note that the expression transforms the point from EPSG:3857 (map and layer coordinate reference system) to EPSG:4326. +5. Check the **Apply default value on update** option :heavy_check_mark:. + +![QGIS attributes form transform and record coordinates by default](./qgis-form-default-coordinates.jpg "QGIS attributes form transform and record coordinates by default") + +Repeat the same steps for `y` field and setting the **Alias** to *Latitude* and the default value to + +``` +y( transform( $geometry, 'EPSG:3857', 'EPSG:4326')) +``` + +Don't forget to save and synchronise your project! + +When adding or editing features in the , the coordinates are automatically filled in: + +![Mergin Maps mobile app attributes form default values](./mobile-form-default-values-coordinates.jpg "Mergin Maps mobile app attributes form default values") + diff --git a/src/layer/default-values/qgis-form-open-file-default-value.jpg b/src/layer/default-values/qgis-form-open-file-default-value.jpg deleted file mode 100644 index 9e95c9a5..00000000 Binary files a/src/layer/default-values/qgis-form-open-file-default-value.jpg and /dev/null differ diff --git a/src/layer/default-values/qgis-form-open-file-default-value.xcf b/src/layer/default-values/qgis-form-open-file-default-value.xcf deleted file mode 100644 index 9303af2d..00000000 Binary files a/src/layer/default-values/qgis-form-open-file-default-value.xcf and /dev/null differ diff --git a/src/layer/display-instructions/index.md b/src/layer/display-instructions/index.md deleted file mode 100644 index e10bc0b6..00000000 --- a/src/layer/display-instructions/index.md +++ /dev/null @@ -1,43 +0,0 @@ -# How to Display Instructions in the Form -The HTML and Text widgets can be used to display instructions in the form, as described in [Informational Widgets ](../info-widgets/). - -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). - -These widgets can be found in **Available Widgets** in the **Other Widgets** section when using the [Drag and Drop Designer](../form-layout/#qgis-drag-and-drop-designer). -![QGIS HTML and Text Widget](./qgis-form-html-text-widget.jpg "QGIS HTML and Text Widget") - -To configure the **Text** widget, enter the text you want to display in the form. On the right, you will see the preview. -![QGIS Text widget configuration](./qgis-configure-text-widget.jpg "QGIS Text widget configuration") - -If you prefer your text to be formatted, you may do so in the **HTML** widget. HTML widget supports these [HTML tags](https://doc.qt.io/qt-6/richtext-html-subset.html#supported-tags). -![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). -![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") - -## Expressions in Text and HTML widgets {#using-expressions-in-text-and-html-widgets} -Expressions and variables can be used both in the Text and the HTML widget. - -![QGIS Configure Text Widget Expression Builder](./qgis-text-widget-expression.gif "QGIS Configure Text Widget Expression Builder") - -:::tip -Clone to follow this example. -::: - -1. When configuring the Text or HTML widget, click on the **Expression Builder** button -2. Enter the expression that will be used in your text and click **OK**. - - Field values can be selected from the **Fields and Values** list. There are other variables and expressions that can be used. - -3. Click on the **+** button to add the expression to the text. - - Here, we configured the widget with this text: - `Make sure the number plate [% "VRP" %] is visible in the photo.` - - In this case, `VRP` is the name of a field aliased as `Vehicle Registration Plate` in the form. - -4. Save and synchronise your project. - -... and this is how it works during the field survey. `[% "VRP" %]` expression displays the current value of the `Vehicle Registration Plate` field. -![Mergin Maps mobile app text widget with variable](./mobile-text-widget-expression.jpg "Mergin Maps mobile app text widget with variable") - diff --git a/src/layer/display-instructions/mobile-forms-conditional-visibility.jpg b/src/layer/display-instructions/mobile-forms-conditional-visibility.jpg deleted file mode 100644 index f2ce8450..00000000 Binary files a/src/layer/display-instructions/mobile-forms-conditional-visibility.jpg and /dev/null differ diff --git a/src/layer/display-instructions/mobile-forms-conditional-visibility.xcf b/src/layer/display-instructions/mobile-forms-conditional-visibility.xcf deleted file mode 100644 index 53304a74..00000000 Binary files a/src/layer/display-instructions/mobile-forms-conditional-visibility.xcf and /dev/null differ diff --git a/src/layer/display-instructions/mobile-forms-layout.jpg b/src/layer/display-instructions/mobile-forms-layout.jpg deleted file mode 100644 index 21025a25..00000000 Binary files a/src/layer/display-instructions/mobile-forms-layout.jpg and /dev/null differ diff --git a/src/layer/display-instructions/mobile-forms-layout.xcf b/src/layer/display-instructions/mobile-forms-layout.xcf deleted file mode 100644 index 1c0e554a..00000000 Binary files a/src/layer/display-instructions/mobile-forms-layout.xcf and /dev/null differ diff --git a/src/layer/display-instructions/mobile-forms-open-file-html-widget.jpg b/src/layer/display-instructions/mobile-forms-open-file-html-widget.jpg deleted file mode 100644 index cfdb4307..00000000 Binary files a/src/layer/display-instructions/mobile-forms-open-file-html-widget.jpg and /dev/null differ diff --git a/src/layer/display-instructions/mobile-forms-open-file-html-widget.xcf b/src/layer/display-instructions/mobile-forms-open-file-html-widget.xcf deleted file mode 100644 index 0fa41723..00000000 Binary files a/src/layer/display-instructions/mobile-forms-open-file-html-widget.xcf and /dev/null differ diff --git a/src/layer/display-instructions/mobile-text-widget-expression.jpg b/src/layer/display-instructions/mobile-text-widget-expression.jpg deleted file mode 100644 index 4215c32a..00000000 Binary files a/src/layer/display-instructions/mobile-text-widget-expression.jpg and /dev/null differ diff --git a/src/layer/display-instructions/mobile-text-widget-expression.xcf b/src/layer/display-instructions/mobile-text-widget-expression.xcf deleted file mode 100644 index a3d95582..00000000 Binary files a/src/layer/display-instructions/mobile-text-widget-expression.xcf and /dev/null differ diff --git a/src/layer/display-instructions/qgis-add-group-tab.jpg b/src/layer/display-instructions/qgis-add-group-tab.jpg deleted file mode 100644 index 9b1a3866..00000000 Binary files a/src/layer/display-instructions/qgis-add-group-tab.jpg and /dev/null differ diff --git a/src/layer/display-instructions/qgis-add-group-tab.xcf b/src/layer/display-instructions/qgis-add-group-tab.xcf deleted file mode 100644 index 1be22c3a..00000000 Binary files a/src/layer/display-instructions/qgis-add-group-tab.xcf and /dev/null differ diff --git a/src/layer/display-instructions/qgis-configure-html-widget.jpg b/src/layer/display-instructions/qgis-configure-html-widget.jpg deleted file mode 100644 index 1ce0853d..00000000 Binary files a/src/layer/display-instructions/qgis-configure-html-widget.jpg and /dev/null differ diff --git a/src/layer/display-instructions/qgis-configure-html-widget.xcf b/src/layer/display-instructions/qgis-configure-html-widget.xcf deleted file mode 100644 index b8353f39..00000000 Binary files a/src/layer/display-instructions/qgis-configure-html-widget.xcf and /dev/null differ diff --git a/src/layer/display-instructions/qgis-configure-spacer-widget.jpg b/src/layer/display-instructions/qgis-configure-spacer-widget.jpg deleted file mode 100644 index 6c1543b1..00000000 Binary files a/src/layer/display-instructions/qgis-configure-spacer-widget.jpg and /dev/null differ diff --git a/src/layer/display-instructions/qgis-configure-spacer-widget.xcf b/src/layer/display-instructions/qgis-configure-spacer-widget.xcf deleted file mode 100644 index 8282cdc4..00000000 Binary files a/src/layer/display-instructions/qgis-configure-spacer-widget.xcf and /dev/null differ diff --git a/src/layer/display-instructions/qgis-configure-text-widget.jpg b/src/layer/display-instructions/qgis-configure-text-widget.jpg deleted file mode 100644 index aeb75a7b..00000000 Binary files a/src/layer/display-instructions/qgis-configure-text-widget.jpg and /dev/null differ diff --git a/src/layer/display-instructions/qgis-configure-text-widget.xcf b/src/layer/display-instructions/qgis-configure-text-widget.xcf deleted file mode 100644 index 9b3f2420..00000000 Binary files a/src/layer/display-instructions/qgis-configure-text-widget.xcf and /dev/null differ diff --git a/src/layer/display-instructions/qgis-drag-n-drop.gif b/src/layer/display-instructions/qgis-drag-n-drop.gif deleted file mode 100644 index 466bbbc8..00000000 Binary files a/src/layer/display-instructions/qgis-drag-n-drop.gif and /dev/null differ diff --git a/src/layer/display-instructions/qgis-form-add-group.jpg b/src/layer/display-instructions/qgis-form-add-group.jpg deleted file mode 100644 index 173d8bea..00000000 Binary files a/src/layer/display-instructions/qgis-form-add-group.jpg and /dev/null differ diff --git a/src/layer/display-instructions/qgis-form-add-group.xcf b/src/layer/display-instructions/qgis-form-add-group.xcf deleted file mode 100644 index 717d31bc..00000000 Binary files a/src/layer/display-instructions/qgis-form-add-group.xcf and /dev/null differ diff --git a/src/layer/display-instructions/qgis-form-conditional-visibility.jpg b/src/layer/display-instructions/qgis-form-conditional-visibility.jpg deleted file mode 100644 index 5efa9577..00000000 Binary files a/src/layer/display-instructions/qgis-form-conditional-visibility.jpg and /dev/null differ diff --git a/src/layer/display-instructions/qgis-form-conditional-visibility.xcf b/src/layer/display-instructions/qgis-form-conditional-visibility.xcf deleted file mode 100644 index bbe88b03..00000000 Binary files a/src/layer/display-instructions/qgis-form-conditional-visibility.xcf and /dev/null differ diff --git a/src/layer/display-instructions/qgis-form-html-text-widget.jpg b/src/layer/display-instructions/qgis-form-html-text-widget.jpg deleted file mode 100644 index c26f093d..00000000 Binary files a/src/layer/display-instructions/qgis-form-html-text-widget.jpg and /dev/null differ diff --git a/src/layer/display-instructions/qgis-form-html-text-widget.xcf b/src/layer/display-instructions/qgis-form-html-text-widget.xcf deleted file mode 100644 index 04f2875b..00000000 Binary files a/src/layer/display-instructions/qgis-form-html-text-widget.xcf and /dev/null differ diff --git a/src/layer/display-instructions/qgis-form-layout-add-groups-tabs.jpg b/src/layer/display-instructions/qgis-form-layout-add-groups-tabs.jpg deleted file mode 100644 index f6be2f42..00000000 Binary files a/src/layer/display-instructions/qgis-form-layout-add-groups-tabs.jpg and /dev/null differ diff --git a/src/layer/display-instructions/qgis-form-layout-add-groups-tabs.xcf b/src/layer/display-instructions/qgis-form-layout-add-groups-tabs.xcf deleted file mode 100644 index 176c400e..00000000 Binary files a/src/layer/display-instructions/qgis-form-layout-add-groups-tabs.xcf and /dev/null differ diff --git a/src/layer/display-instructions/qgis-form-open-file-html-widget.jpg b/src/layer/display-instructions/qgis-form-open-file-html-widget.jpg deleted file mode 100644 index 19b2c1ec..00000000 Binary files a/src/layer/display-instructions/qgis-form-open-file-html-widget.jpg and /dev/null differ diff --git a/src/layer/display-instructions/qgis-form-open-file-html-widget.xcf b/src/layer/display-instructions/qgis-form-open-file-html-widget.xcf deleted file mode 100644 index 2ee53c46..00000000 Binary files a/src/layer/display-instructions/qgis-form-open-file-html-widget.xcf and /dev/null differ diff --git a/src/layer/display-instructions/qgis-form-spacer-widget.jpg b/src/layer/display-instructions/qgis-form-spacer-widget.jpg deleted file mode 100644 index 4f3cbc9e..00000000 Binary files a/src/layer/display-instructions/qgis-form-spacer-widget.jpg and /dev/null differ diff --git a/src/layer/display-instructions/qgis-form-spacer-widget.xcf b/src/layer/display-instructions/qgis-form-spacer-widget.xcf deleted file mode 100644 index a91e9a9e..00000000 Binary files a/src/layer/display-instructions/qgis-form-spacer-widget.xcf and /dev/null differ diff --git a/src/layer/display-instructions/qgis-form-tabs-groups.jpg b/src/layer/display-instructions/qgis-form-tabs-groups.jpg deleted file mode 100644 index af397540..00000000 Binary files a/src/layer/display-instructions/qgis-form-tabs-groups.jpg and /dev/null differ diff --git a/src/layer/display-instructions/qgis-form-tabs-groups.xcf b/src/layer/display-instructions/qgis-form-tabs-groups.xcf deleted file mode 100644 index 3623e61c..00000000 Binary files a/src/layer/display-instructions/qgis-form-tabs-groups.xcf and /dev/null differ diff --git a/src/layer/display-instructions/qgis-form-text-html.jpg b/src/layer/display-instructions/qgis-form-text-html.jpg deleted file mode 100644 index d387d1ea..00000000 Binary files a/src/layer/display-instructions/qgis-form-text-html.jpg and /dev/null differ diff --git a/src/layer/display-instructions/qgis-form-value-map-roads.jpg b/src/layer/display-instructions/qgis-form-value-map-roads.jpg deleted file mode 100644 index 7fbac56f..00000000 Binary files a/src/layer/display-instructions/qgis-form-value-map-roads.jpg and /dev/null differ diff --git a/src/layer/display-instructions/qgis-form-value-map-roads.xcf b/src/layer/display-instructions/qgis-form-value-map-roads.xcf deleted file mode 100644 index a9a4663b..00000000 Binary files a/src/layer/display-instructions/qgis-form-value-map-roads.xcf and /dev/null differ diff --git a/src/layer/display-instructions/qgis-mobile-html-form.jpg b/src/layer/display-instructions/qgis-mobile-html-form.jpg deleted file mode 100644 index 6bb98a70..00000000 Binary files a/src/layer/display-instructions/qgis-mobile-html-form.jpg and /dev/null differ diff --git a/src/layer/display-instructions/qgis-mobile-html-form.xcf b/src/layer/display-instructions/qgis-mobile-html-form.xcf deleted file mode 100644 index 0ae5097f..00000000 Binary files a/src/layer/display-instructions/qgis-mobile-html-form.xcf and /dev/null differ diff --git a/src/layer/display-instructions/qgis-text-widget-expression.gif b/src/layer/display-instructions/qgis-text-widget-expression.gif deleted file mode 100644 index 26bb6867..00000000 Binary files a/src/layer/display-instructions/qgis-text-widget-expression.gif and /dev/null differ diff --git a/src/layer/display-instructions/qgis_forms_layout.jpg b/src/layer/display-instructions/qgis_forms_layout.jpg deleted file mode 100644 index ed35c767..00000000 Binary files a/src/layer/display-instructions/qgis_forms_layout.jpg and /dev/null differ diff --git a/src/layer/display-instructions/qgis_forms_layout.xcf b/src/layer/display-instructions/qgis_forms_layout.xcf deleted file mode 100644 index 5a01c56b..00000000 Binary files a/src/layer/display-instructions/qgis_forms_layout.xcf and /dev/null differ diff --git a/src/layer/display-instructions/spacer-widget-forms.jpg b/src/layer/display-instructions/spacer-widget-forms.jpg deleted file mode 100644 index 545a9ebc..00000000 Binary files a/src/layer/display-instructions/spacer-widget-forms.jpg and /dev/null differ diff --git a/src/layer/display-instructions/spacer-widget-forms.xcf b/src/layer/display-instructions/spacer-widget-forms.xcf deleted file mode 100644 index 577fe798..00000000 Binary files a/src/layer/display-instructions/spacer-widget-forms.xcf and /dev/null differ diff --git a/src/layer/embed-image/index.md b/src/layer/embed-image/index.md index c7d28ce1..c9f657e3 100644 --- a/src/layer/embed-image/index.md +++ b/src/layer/embed-image/index.md @@ -1,29 +1,27 @@ -# How to Embed an Image -[[toc]] - - -## Photo -A photo can be displayed in the form as described in [Displaying photos in QGIS](../photos/#displaying-photos-in-qgis). - -## Online image -The [**HTML widget**](../info-widgets/) can be used to display online images in the as described in [Using HTML widget to display online images and other online resources ](../info-widgets/#using-html-widget-to-display-online-images-and-other-online-resources) - -::: tip Example project available -Clone to how this works. -::: - -Your layer should contain a text field for storing the full URL link (here: `link`). - -To show an online image in the form, configure the HTML widget with this expression (replace `link` with the name of the appropriate field in your layer): - -```html - -``` - -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.webp "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. -::: +--- +description: HTML widget can be used to embed an online image in the attributes form of your survey layer. +--- + +# How to Embed an Image + +The [**HTML widget**](../info-widgets/#html-widget) can be used to display online images in the . + +::: tip Example project available +Clone to how this works. +::: + +Your layer should contain a text field for storing the full URL link (here: `link`). + +To show an online image in the form, [add the HTML widget to the form](../info-widgets/) and configure it with this expression (replace `link` with the name of the appropriate field in your layer): + +```html + +``` + +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.webp "HTML widget in QGIS and in Mergin Maps mobile app") + +::: details Image preview in QGIS +Some QGIS versions may not display the preview of the image correctly. This issue does not occur in . Therefore we recommend trying the setup by opening the form in the to make sure it works as intended. +::: diff --git a/src/layer/embed-image/qgis-mobile-html-form.jpg b/src/layer/embed-image/qgis-mobile-html-form.jpg deleted file mode 100644 index 6bb98a70..00000000 Binary files a/src/layer/embed-image/qgis-mobile-html-form.jpg and /dev/null differ diff --git a/src/layer/exif/index.md b/src/layer/exif/index.md index b9ab0309..408b65b8 100644 --- a/src/layer/exif/index.md +++ b/src/layer/exif/index.md @@ -1,70 +1,74 @@ -# Geotagging -[[toc]] - -Geotagging can be achieved through EXIF metadata. EXIF is a file format for storing metadata in image files, such as the camera settings, image metrics, date and time or location information (see, e.g., [Wikipedia](https://en.wikipedia.org/wiki/Exif)). - -The supports some default value expression functions that can be used to read EXIF metadata and store their values in the fields of your survey layer. - -To store GPS EXIF metadata, both the and your camera app have [location permissions](#allowing-location-tags) allowed on your mobile device. - -## Allowing location tags -**Location tags have to be allowed** in the camera settings to store GPS EXIF metadata in the photos. - -- **Android**: Open Camera app -> Camera settings -> Location tags. - ![Allowing location tags in Android](./android_geo_tags.jpg "Allowing location tags in Android") - -- **iOS**: Open Settings -> Privacy -> Location Services -> Camera (app). - ![Allowing location tags in iOS](./ios_geo_tags.jpg "Allowing location tags in iOS") - -## How to use EXIF metadata in Mergin Maps mobile app - -::: tip Example project available -Clone to see how it works! -::: - -To store EXIF metadata values in the fields of your survey layer: -1. In QGIS, open the **Properties** of your survey layer and navigate to the **Attributes Form** tab. -2. Now we need to set the [default values](../default-values/) of fields that should store EXIF metadata. - - [Supported EXIF functions](#supported-exif-functions) are listed below. In general, EXIF functions looks like this: - `read_exif('', '')` - - This expression requires the **absolute path** to an image. The absolute path can be defined using the field where the image is stored (here: `photo`, this is a [text field with attachment widget](../photos/)) and the `@project_home` variable that refers to the project home folder. - - For example, the default value expression for the direction of the image (EXIF tag `GPSImgDirection`) can be defined as follows: - - `read_exif(@project_home + '/' + "photo", 'GPSImgDirection')` - - ![Read exif function as default value in Attributes form](./qgis_form_exif.jpg "Read exif function as default value in Attributes form") - - The preview shows a warning *Function is not known*. **This is OK, will know what to do with it!** - -3. Save and sync your project. - -4. Open the project in . Once you capture a photo during the field survey, the EXIF metadata values will be automatically filled in: - ![Exif metadata in Mergin Maps mobile app](./mobile-exif-metadata.jpg "Exif metadata in Mergin Maps mobile app") - -## Supported EXIF functions -EXIF function supported by : -- `read_exif_img_direction('')` returns the direction of the image when captured. The direction is represented by a number. -- `read_exif_latitude('')` returns GPS Latitude as a decimal number. -- `read_exif_longitude('')` returns GPS Longitude as a decimal number. -- `read_exif('', '')`, where **EXIF tag string** defines the EXIF property, such as: - - `GPSImgDirection` returns the direction of the image when captured as a rational. The direction is represented by a rational, e.g. 350/1. - - `GPSLatitude` returns GPS Latitude as rationals, e.g. 48/1, 6/1, 309275/10000. - - `GPSLongitude` returns GPS Longitude as rationals, e.g. 17/1, 6/1, 244907/10000. - - `ImageWidth` returns the image width in pixels. - -The list of **EXIF tags** can be found in the Android developer documentation for [ ](https://developer.android.com/reference/android/media/ExifInterface) or in [ExifTool documentation](https://exiftool.org/TagNames/EXIF.html). - -Note that some of the tag names listed in [ExifTool documentation](https://exiftool.org/TagNames/EXIF.html) can differ from the EXIF specification. As an example, while `ImageWidth` tag is valid, `ImageHeight` is not and you have to use `ImageLength` tag name (defined by EXIF specification) when [recording EXIF metadata](#how-to-use-exif-metadata-in-mergin-maps-mobile-app) in . - -:::details -EXIF tags that can be retrieved from your images can vary depending on how they were created (e.g. what type of device you used to capture photos). EXIF tags that are recorded in your image can be displayed, e.g., using [ExifTool](https://exiftool.org/): -``` -exiftool -n -S -``` - -However, keep in mind that the EXIF tag names that you get from ExifTool can differ from EXIF specification. To store EXIF metadata using , you have to use the latter. -::: - +--- +description: EXIF is a file format for storing metadata in image files. Mergin Maps mobile app can store EXIF metadata values in the fields of survey layers. +--- + +# Geotagging +[[toc]] + +Geotagging can be achieved through EXIF metadata. EXIF is a file format for storing metadata in image files, such as the camera settings, image metrics, date and time or location information (see, e.g., [Wikipedia](https://en.wikipedia.org/wiki/Exif)). + +The supports some default value expression functions that can be used to read EXIF metadata and store their values in the fields of your survey layer. + +To store GPS EXIF metadata, both the and your camera app have [location permissions](#allowing-location-tags) allowed on your mobile device. + +## Allowing location tags +**Location tags have to be allowed** in the camera settings to store GPS EXIF metadata in the photos. + +- **Android**: Open Camera app -> Camera settings -> Location tags. + ![Allowing location tags in Android](./android_geo_tags.jpg "Allowing location tags in Android") + +- **iOS**: Open Settings -> Privacy -> Location Services -> Camera (app). + ![Allowing location tags in iOS](./ios_geo_tags.jpg "Allowing location tags in iOS") + +## How to use EXIF metadata in Mergin Maps mobile app + +::: tip Example project available +Clone to see how it works! +::: + +To store EXIF metadata values in the fields of your survey layer: +1. In QGIS, open the **Properties** of your survey layer and navigate to the **Attributes Form** tab. +2. Now we need to set the [default values](../default-values/) of fields that should store EXIF metadata. + + [Supported EXIF functions](#supported-exif-functions) are listed below. In general, EXIF functions looks like this: + `read_exif('', '')` + + This expression requires the **absolute path** to an image. The absolute path can be defined using the field where the image is stored (here: `photo`, this is a [text field with attachment widget](../photos/)) and the `@project_home` variable that refers to the project home folder. + + For example, the default value expression for the direction of the image (EXIF tag `GPSImgDirection`) can be defined as follows: + + `read_exif(@project_home + '/' + "photo", 'GPSImgDirection')` + + ![Read exif function as default value in Attributes form](./qgis_form_exif.jpg "Read exif function as default value in Attributes form") + + The preview shows a warning *Function is not known*. **This is OK, will know what to do with it!** + +3. Save and sync your project. + +4. Open the project in . Once you capture a photo during the field survey, the EXIF metadata values will be automatically filled in: + ![Exif metadata in Mergin Maps mobile app](./mobile-exif-metadata.jpg "Exif metadata in Mergin Maps mobile app") + +## Supported EXIF functions +EXIF function supported by : +- `read_exif_img_direction('')` returns the direction of the image when captured. The direction is represented by a number. +- `read_exif_latitude('')` returns GPS Latitude as a decimal number. +- `read_exif_longitude('')` returns GPS Longitude as a decimal number. +- `read_exif('', '')`, where **EXIF tag string** defines the EXIF property, such as: + - `GPSImgDirection` returns the direction of the image when captured as a rational. The direction is represented by a rational, e.g. 350/1. + - `GPSLatitude` returns GPS Latitude as rationals, e.g. 48/1, 6/1, 309275/10000. + - `GPSLongitude` returns GPS Longitude as rationals, e.g. 17/1, 6/1, 244907/10000. + - `ImageWidth` returns the image width in pixels. + +The list of **EXIF tags** can be found in the Android developer documentation for [ ](https://developer.android.com/reference/android/media/ExifInterface) or in [ExifTool documentation](https://exiftool.org/TagNames/EXIF.html). + +Note that some of the tag names listed in [ExifTool documentation](https://exiftool.org/TagNames/EXIF.html) can differ from the EXIF specification. As an example, while `ImageWidth` tag is valid, `ImageHeight` is not and you have to use `ImageLength` tag name (defined by EXIF specification) when [recording EXIF metadata](#how-to-use-exif-metadata-in-mergin-maps-mobile-app) in . + +:::details +EXIF tags that can be retrieved from your images can vary depending on how they were created (e.g. what type of device you used to capture photos). EXIF tags that are recorded in your image can be displayed, e.g., using [ExifTool](https://exiftool.org/): +``` +exiftool -n -S +``` + +However, keep in mind that the EXIF tag names that you get from ExifTool can differ from EXIF specification. To store EXIF metadata using , you have to use the latter. +::: + diff --git a/src/layer/external-link/index.md b/src/layer/external-link/index.md index ea91e5dd..3e0279b3 100644 --- a/src/layer/external-link/index.md +++ b/src/layer/external-link/index.md @@ -1,54 +1,32 @@ -# How to Use Hyperlinks -[[toc]] - -Attributes forms can include clickable links that can be used to [open a link in a browser](#open-link-in-a-browser) or [open a navigation app](#open-link-to-a-navigation-app) directly from the form in . - -## Open link in a browser - -1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. -2. In the list of **Available Widgets** select the field you want to work with. -3. In the **Widget Type** tab: - - Ensure that **Text Edit** is selected - - Check the **Multiline** and **HTML** options -4. In the **Defaults** tab, use a string such as this as **Default value**: - `'Open link'` - :::details - The default value defines the hyperlink and how it will be displayed in the form using HTML: - `display text` - Individual links can be generated for each feature based on a value from another field. Let's say there is a field called **name** with a sample value *my-page*: - `'Open link'` will result in *www.web-page.com/my-page*. - ::: -5. If the link changes based on a value from a different field, check the **Apply default value on update** option. -6. **Apply** the changes. Don't forget to save and sync your project! - -![Hyperlink as default value in Attribute form](./qgis-link.jpg "Hyperlink as default value in Attribute form") - -When you click on a feature in , the form will contain a clickable link. -![Hyperlink in Mergin Maps mobile app form](./mobile-form-link.jpg "Hyperlink in Mergin Maps mobile app form") - -## Open link to a navigation app - -:::tip -Clone to follow this example! -::: - -Let's say you want to find your surveyed features on Google Maps. It is possible to do so directly from , you just need to set up a **text field** that will open Google Maps and enter the coordinates of the feature to the Google Maps search bar. - -1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. -2. In the list of **Available Widgets** select the field you want to work with. -3. In the **Widget Display** tab: - - Ensure that **Text Edit** is selected - - Check the **Multiline** and **HTML** options -4. In the **Defaults** tab, use this string as **Default value**: - `'Open Google Map'` -5. Check the **Apply default value on update** option -6. **Apply** the changes. Don't forget to save and sync your project! - -![Link to Google maps in QGIS Attributes form](./qgis-google-maps.jpg "Link to Google Maps in QGIS Attributes form") - -When you tap a feature in the , the form will display a clickable link **Open Google Map** that opens the Google Map app at the position of the feature. - -![Open Google map from Mergin Maps mobile app](./mobile-form-link-to-navigation-app.jpg "Open Google map from Mergin Maps mobile app") - - - +--- +description: Hyperlinks can be used in the attributes form in Mergin Maps mobile app to open a link in a browser directly from the feature's form. +--- + +# How to Use Hyperlinks + +Attributes forms can include clickable links that can be used to open a link in a browser directly from the form in . + +1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. +2. In the list of **Available Widgets** select the field you want to work with. +3. In the **Widget Type** tab: + - Ensure that **Text Edit** is selected + - Check the **Multiline** and **HTML** options +4. In the **Defaults** tab, use a string such as this as **Default value**: + `'Open link'` + :::details + The default value defines the hyperlink and how it will be displayed in the form using HTML: + `display text` + Individual links can be generated for each feature based on a value from another field. Let's say there is a field called **name** with a sample value *my-page*: + `'Open link'` will result in *www.web-page.com/my-page*. + ::: +5. If the link changes based on a value from a different field, check the **Apply default value on update** option. +6. **Apply** the changes. Don't forget to save and sync your project! + +![Hyperlink as default value in Attribute form](./qgis-link.jpg "Hyperlink as default value in Attribute form") + +When you click on a feature in , the form will contain a clickable link. +![Hyperlink in Mergin Maps mobile app form](./mobile-form-link.jpg "Hyperlink in Mergin Maps mobile app form") + +:::tip +Hyperlinks can be used in the attributes form also to open a [link to a navigation app](../link-to-navigation/). +::: diff --git a/src/layer/form-layout/index.md b/src/layer/form-layout/index.md index cb171450..dbbc0e51 100644 --- a/src/layer/form-layout/index.md +++ b/src/layer/form-layout/index.md @@ -1,33 +1,37 @@ -# Attributes Form Layout -[[toc]] - -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 [tabs and groups](../tabs-and-groups/) to keep related fields together, displaying or hiding a group of fields based on [conditional visibility](../conditional-visibility/), or displaying tips and instructions in the forms using the [Text or HTML widget](../info-widgets/). The starting point for creating a form is [QGIS Drag and Drop Designer](#qgis-drag-and-drop-designer). - - -## 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](../default-values) that are calculated from the geometry. - -QGIS Drag and Drop designer is an easy tool for defining the form layouts: -1. Open your project in QGIS -2. Right-click on a layer and select **Properties** -3. Navigate to the **Attributes form** tab. Here, switch to **Drag and Drop Designer** -4. Fields can be added and removed from the **Form Layout**. The order of the fields can be changed by simply dragging them higher or lower in the list. - - Only fields that are in the **Form layout** will appear in the form. - -5. Click **OK** to confirm your changes. - -![QGIS drag and drop form designer](./qgis-drag-n-drop.gif "QGIS drag and drop form designer") - -## Spacer widget - -The Spacer widget can be useful if you want to have some space between the fields in your form or add a horizontal line. - -It can be found in *Available Widgets* in the *Other Widgets* section when using the [Drag and Drop Designer](#qgis-drag-and-drop-designer). -![QGIS forms Spacer Widget](./qgis-form-spacer-widget.jpg "QGIS Spacer Widget") - -When adding the spacer widget to the form, there is an option to check the **Draw horizontal line** option. Otherwise, a vertical space will be added to the form. -![QGIS Spacer Widget configuration](./qgis-configure-spacer-widget.jpg "QGIS Spacer Widget configuration") - -And this is how the spacer widget looks like in the form in QGIS (left) and in the mobile app (right). -![Spacer widget in QGIS and mobile app form](./spacer-widget-forms.jpg "Spacer widget in QGIS and mobile app form") +--- +description: Use QGIS drag and drop designer, conditional visibility, and widgets to create attributes forms tailored to your Mergin Maps project needs. +--- + +# Attributes Form Layout +[[toc]] + +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 [tabs and groups](../tabs-and-groups/) to keep related fields together, displaying or hiding a group of fields based on [conditional visibility](../conditional-visibility/), or displaying tips and instructions in the forms using the [Text or HTML widget](../info-widgets/). The starting point for creating a form is [QGIS Drag and Drop Designer](#qgis-drag-and-drop-designer). + + +## 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](../default-values) that are calculated from the geometry. + +QGIS Drag and Drop designer is an easy tool for defining the form layouts: +1. Open your project in QGIS +2. Right-click on a layer and select **Properties** +3. Navigate to the **Attributes form** tab. Here, switch to **Drag and Drop Designer** +4. Fields can be added and removed from the **Form Layout**. The order of the fields can be changed by simply dragging them higher or lower in the list. + + Only fields that are in the **Form layout** will appear in the form. + +5. Click **OK** to confirm your changes. + +![QGIS drag and drop form designer](./qgis-drag-n-drop.gif "QGIS drag and drop form designer") + +## Spacer widget + +The Spacer widget can be useful if you want to have some space between the fields in your form or add a horizontal line. + +It can be found in *Available Widgets* in the *Other Widgets* section when using the [Drag and Drop Designer](#qgis-drag-and-drop-designer). +![QGIS forms Spacer Widget](./qgis-form-spacer-widget.jpg "QGIS Spacer Widget") + +When adding the spacer widget to the form, there is an option to check the **Draw horizontal line** option. Otherwise, a vertical space will be added to the form. +![QGIS Spacer Widget configuration](./qgis-configure-spacer-widget.jpg "QGIS Spacer Widget configuration") + +And this is how the spacer widget looks like in the form in QGIS (left) and in the mobile app (right). +![Spacer widget in QGIS and mobile app form](./spacer-widget-forms.jpg "Spacer widget in QGIS and mobile app form") diff --git a/src/layer/form-widgets/index.md b/src/layer/form-widgets/index.md index 3a717db2..6bd86fc8 100644 --- a/src/layer/form-widgets/index.md +++ b/src/layer/form-widgets/index.md @@ -1,40 +1,30 @@ -# Form Widgets - -Form widgets define the way you can enter values in the form, both in QGIS and in the . The configuration of form widgets in your project is done in QGIS. - -Do you prefer a video? Check out this tutorial on how to configure QGIS widgets for survey forms. - - -## Setting up form widgets - -Attributes forms can be configured using in the **Attributes Form** tab in the **Layer Properties**. Note that the widget has to be compatible with the field data type. - -Each data type has a default widget: for instance, text fields use *Text edit* widget by default and are filled in by manually typing the value, while date fields use *Date/Time* widget and the value is selected using a calendar pop-up. - -![QGIS Layer Properties Attributes Form tab](./qgis-attributes-form.gif "QGIS Layer Properties Attributes Form tab") - - -## Widget gallery - -Here is an overview of widgets that are commonly used both in QGIS and the . - -::: tip Public project available -:bulb: These widgets can be explored in this project: . -::: - -|QGIS widget | Description |
Preview in
| -|:---:|:---:|:---:| -|Text Edit |[Text](../text) | ![Mergin Maps mobile app text field form](./mobile-form-text-preview.jpg "Mergin Maps mobile app text field form") | -|Text Edit |[Multiline Text](../text#multiline-text) | ![Mergin Maps mobile app text field form](./mobile-form-text-multiline-preview.jpg "Mergin Maps mobile app text field form") | -|Date/Time |[Calendar with time](../date-time) |![Mergin Maps mobile app date time field form](./mobile-form-datetime-preview.jpg "Mergin Maps mobile app date time field form") | -|Relations |[Multiple records linked to one feature](../relations/) | ![Mergin Maps mobile app 1-N relations attributes form](./mobile-form-relations-preview.jpg "Mergin Maps mobile app 1-N relations attributes form") | -|Relation reference | [Reference to feature from another layer](../relations/) | ![Mergin Maps mobile app relation reference form](./mobile-form-relation-reference-preview.webp "Mergin Maps mobile app relation reference form") | -|Range - Editable |[Enter a number](../numbers) | ![Mergin Maps mobile app numeric field form](./mobile-form-number-editable-preview.jpg "Mergin Maps mobile app numeric field form") | -|Range - Slider |[Select a number using the slider](../numbers#slider) | ![Mergin Maps mobile app slider field form](./mobile-form-number-slider-preview.jpg "Mergin Maps mobile app slider field form") | -|Checkbox |[Checkbox](../checkbox) |![Mergin Maps mobile app checkbox field form](./mobile-form-checkbox-preview.jpg "Mergin Maps mobile app checkbox field form") | -|QR & barcode scanner |[Camera to scan QR and barcode](../qr-code) | ![Mergin Maps mobile app QR code field form](./mobile-form-qrcode-preview.jpg "Mergin Maps mobile app QR code field form") | -|Value Map |[Drop-down menu with predefined values](../value-select/#value-map) |![Mergin Maps mobile app value map field form](./mobile-form-valuemap-preview.jpg "Mergin Maps mobile app value map field form") | -|Value Relation |[Drop-down menu with values from another table](../value-select/#value-relation) |![Mergin Maps mobile app value relation field form](./mobile-form-value-relation-preview.jpg "Mergin Maps mobile app value relation field form") | -|Attachment |[Photos from device's camera or gallery](../photos) | ![Mergin Maps mobile app attachment field form](./mobile-form-photo-preview.jpg "Mergin Maps mobile app attachment field form") ![Mergin Maps mobile app attachment field form](./mobile-form-photo-preview2.jpg "Mergin Maps mobile app attachment field form") | -|Relations - Gallery |[Multiple photos from device's camera or gallery](../photos/#how-to-attach-multiple-photos-to-one-feature) | ![Mergin Maps mobile app multiple photos attributes form](./mobile-form-multiple-photo-preview.jpg "Mergin Maps mobile app multiple photos attributes form") | -| Text and HTML Widgets |[Informational Widgets](../info-widgets/) | ![Mergin Maps mobile app HTML and Text widgets in attributes form](./mobile-form-info-widgets.webp "Mergin Maps mobile app HTML and Text widgets in attributes form") | +--- +description: Our Widget Gallery provides an overview of QGIS form widgets supported by the Mergin Maps mobile app. Find the best widget for your survey form! +--- + +# Form Widgets Gallery + +Form widgets define the way you can enter values in the form, both in QGIS and in the . The configuration of form widgets in your project is done in QGIS. + +Here is an overview of widgets that are commonly used both in QGIS and the . + +::: tip Public project available +:bulb: These widgets can be explored in this project: . +::: + +|QGIS widget | Description |
Preview in
| +|:---:|:---:|:---:| +|Text Edit |[Text](../text) | ![Mergin Maps mobile app text field form](./mobile-form-text-preview.jpg "Mergin Maps mobile app text field form") | +|Text Edit |[Multiline Text](../text#multiline-text) | ![Mergin Maps mobile app text field form](./mobile-form-text-multiline-preview.jpg "Mergin Maps mobile app text field form") | +|Date/Time |[Calendar with time](../date-time) |![Mergin Maps mobile app date time field form](./mobile-form-datetime-preview.jpg "Mergin Maps mobile app date time field form") | +|Relations |[Multiple records linked to one feature](../relations/) | ![Mergin Maps mobile app 1-N relations attributes form](./mobile-form-relations-preview.jpg "Mergin Maps mobile app 1-N relations attributes form") | +|Relation reference | [Reference to feature from another layer](../relations/) | ![Mergin Maps mobile app relation reference form](./mobile-form-relation-reference-preview.webp "Mergin Maps mobile app relation reference form") | +|Range - Editable |[Enter a number](../numbers) | ![Mergin Maps mobile app numeric field form](./mobile-form-number-editable-preview.jpg "Mergin Maps mobile app numeric field form") | +|Range - Slider |[Select a number using the slider](../numbers#slider) | ![Mergin Maps mobile app slider field form](./mobile-form-number-slider-preview.jpg "Mergin Maps mobile app slider field form") | +|Checkbox |[Checkbox](../checkbox) |![Mergin Maps mobile app checkbox field form](./mobile-form-checkbox-preview.jpg "Mergin Maps mobile app checkbox field form") | +|QR & barcode scanner |[Camera to scan QR and barcode](../qr-code) | ![Mergin Maps mobile app QR code field form](./mobile-form-qrcode-preview.jpg "Mergin Maps mobile app QR code field form") | +|Value Map |[Drop-down menu with predefined values](../value-select/#value-map) |![Mergin Maps mobile app value map field form](./mobile-form-valuemap-preview.jpg "Mergin Maps mobile app value map field form") | +|Value Relation |[Drop-down menu with values from another table](../value-select/#value-relation) |![Mergin Maps mobile app value relation field form](./mobile-form-value-relation-preview.jpg "Mergin Maps mobile app value relation field form") | +|Attachment |[Photos from device's camera or gallery](../photos) | ![Mergin Maps mobile app attachment field form](./mobile-form-photo-preview.jpg "Mergin Maps mobile app attachment field form") ![Mergin Maps mobile app attachment field form](./mobile-form-photo-preview2.jpg "Mergin Maps mobile app attachment field form") | +|Relations - Gallery |[Multiple photos from device's camera or gallery](../photos/#how-to-attach-multiple-photos-to-one-feature) | ![Mergin Maps mobile app multiple photos attributes form](./mobile-form-multiple-photo-preview.jpg "Mergin Maps mobile app multiple photos attributes form") | +| Text and HTML Widgets |[Informational Widgets](../info-widgets/) | ![Mergin Maps mobile app HTML and Text widgets in attributes form](./mobile-form-info-widgets.webp "Mergin Maps mobile app HTML and Text widgets in attributes form") | diff --git a/src/layer/info-widgets/form-html-widget.webp b/src/layer/info-widgets/form-html-widget.webp new file mode 100644 index 00000000..372206a6 Binary files /dev/null and b/src/layer/info-widgets/form-html-widget.webp differ diff --git a/src/layer/info-widgets/qgis-form-text-html.xcf b/src/layer/info-widgets/form-html-widget.xcf similarity index 92% rename from src/layer/info-widgets/qgis-form-text-html.xcf rename to src/layer/info-widgets/form-html-widget.xcf index 9e4b91a1..e9dc4012 100644 Binary files a/src/layer/info-widgets/qgis-form-text-html.xcf and b/src/layer/info-widgets/form-html-widget.xcf differ diff --git a/src/layer/info-widgets/form-text-widget.webp b/src/layer/info-widgets/form-text-widget.webp new file mode 100644 index 00000000..d1a6f41d Binary files /dev/null and b/src/layer/info-widgets/form-text-widget.webp differ diff --git a/src/layer/display-instructions/qgis-form-text-html.xcf b/src/layer/info-widgets/form-text-widget.xcf similarity index 89% rename from src/layer/display-instructions/qgis-form-text-html.xcf rename to src/layer/info-widgets/form-text-widget.xcf index 9e4b91a1..c2e9eb4d 100644 Binary files a/src/layer/display-instructions/qgis-form-text-html.xcf and b/src/layer/info-widgets/form-text-widget.xcf differ diff --git a/src/layer/info-widgets/index.md b/src/layer/info-widgets/index.md index 8c515eda..40e22de0 100644 --- a/src/layer/info-widgets/index.md +++ b/src/layer/info-widgets/index.md @@ -1,109 +1,67 @@ -# Informational Widgets -[[toc]] - - also offers widgets that can be added to the form to display values or text, but are not connected to a specific field of the layer. supports the HTML, Text and [Spacer](../form-layout/#spacer-widget) widget. - -HTML and Text widgets can be used, e.g., to [display instructions](#text-and-html-widget) in the form. 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) or [open local files](#using-html-widget-to-open-local-files). - -|
Widget
|Preview in the | -|:---:|:---:| -[Text and HTML Widgets](#text-and-html-widget) | ![Mergin Maps mobile app HTML and Text widgets in attributes form](../form-widgets/mobile-form-info-widgets.webp "Mergin Maps mobile app HTML and Text widgets in attributes form") | - - -## Text and HTML widget -The **Text** and **HTML widgets** provide an option to include instructions or tips for surveyors in your attributes forms. These text instructions can include [expressions and field values](#using-expressions-in-text-and-html-widgets) as well. - -These widgets can be found in **Available Widgets** in the **Other Widgets** section when using the [Drag and Drop Designer](../form-layout/#qgis-drag-and-drop-designer). -![QGIS HTML and Text Widget](./qgis-form-html-text-widget.jpg "QGIS HTML and Text Widget") - -To configure the **Text** widget, enter the text you want to display in the form. On the right, you will see the preview. -![QGIS Text widget configuration](./qgis-configure-text-widget.jpg "QGIS Text widget configuration") - -If you prefer your text to be formatted, you may do so in the **HTML** widget. HTML widget supports these [HTML tags](https://doc.qt.io/qt-6/richtext-html-subset.html#supported-tags). -![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). -![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. - -:::tip Example project available -Clone to follow this example. -::: - -![QGIS Configure Text Widget Expression Builder](./qgis-text-widget-expression.gif "QGIS Configure Text Widget Expression Builder") - -1. When configuring the Text or HTML widget, click on the **Expression Builder** button -2. Enter the expression that will be used in your text and click **OK**. - - Field values can be selected from the **Fields and Values** list. There are other variables and expressions that can be used. - -3. Click on the **+** button to add the expression to the text. - - Here, we configured the widget with this text: - - `Make sure the number plate [% "VRP" %] is visible in the photo.` - - In this case, `VRP` is the name of a field aliased as `Vehicle Registration Plate` in the form. - -4. Save and synchronise your project. - -... and this is how it works during the field survey. `[% "VRP" %]` expression displays the current value of the `Vehicle Registration Plate` field. -![Mergin Maps mobile app text widget with variable](./mobile-text-widget-expression.jpg "Mergin Maps mobile app text widget with variable") - -## Display online images and other online resources using HTML widget {#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. - -- show image in the form - -```html - -``` - -- display a text (`here is your link`) with a link that can be opened in a browser -```html - -``` - -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. -::: - - -## Open local files using HTML widget {#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](../open-file/#open-local-files-using-default-values). - -In the project, you can explore and compare both alternatives. -::: +--- +description: HTML and Text widgets are not connected to a specific field of the layer and can be configured to display instructions, online images or open local files. +--- + +# Informational Widgets +[[toc]] + + also offers widgets that can be added to the form to display values or text, but are not connected to a specific field of the layer, such as the Text or HTML widget. These widgets are also supported by . + +HTML and Text widgets can be used, e.g., to display instructions in the form. They 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 also be used, for instance, to display [online images](../embed-image/) or [open local files](../open-file/). + +|
Widget
|Preview in the | +|:---:|:---:| +Text | ![Mergin Maps mobile app Text widget in attributes form](./mobile-text-widget-preview.webp "Mergin Maps mobile app Text widget in attributes form") | +HTML Widget | ![Mergin Maps mobile app HTML widget in attributes form](../form-widgets/mobile-form-info-widgets.webp "Mergin Maps mobile app HTML widget in attributes form") | + +These widgets can be found in **Available Widgets** in the **Other Widgets** section when using the [Drag and Drop Designer](../form-layout/#qgis-drag-and-drop-designer). Simply add them to the form layout and double click to configure them as needed. + +![QGIS HTML and Text Widget](./qgis-form-html-text-widget.jpg "QGIS HTML and Text Widget") + +![QGIS Configure Text Widget Expression Builder](./qgis-text-widget-expression.gif "QGIS Configure Text Widget Expression Builder") + +## Text widget + +To configure the **Text** widget, enter the text you want to display in the form. On the right, you will see the preview. +![QGIS Text widget configuration](./qgis-configure-text-widget.jpg "QGIS Text widget configuration") + +...and this is how the Text widget looks like in the form in QGIS (left) and in the mobile app (right): +![Text widget in QGIS and in Mergin Maps mobile app attributes form](./form-text-widget.webp "Text widget in QGIS and in Mergin Maps mobile app attributes form") + +## HTML Widget +The **HTML** widget offers the option to format the text as needed. HTML widget supports these [HTML tags](https://doc.qt.io/qt-6/richtext-html-subset.html#supported-tags). + +![QGIS HTML widget configuration](./qgis-configure-html-widget.jpg "QGIS HTML widget configuration") + +...and this is how the HTML widget looks like in the form in QGIS (left) and in the mobile app (right): +![HTML widget in QGIS and in Mergin Maps mobile app attributes form](./form-html-widget.webp "HTML widget in QGIS and in Mergin Maps mobile app attributes form") + +## Using expressions in Text and HTML widgets +Expressions and variables can be used in the Text and the HTML widget. + +:::tip Example project available +Clone to follow this example. +::: + +![QGIS Configure Text Widget Expression Builder](./qgis-text-widget-expression.gif "QGIS Configure Text Widget Expression Builder") + +1. When configuring the Text or HTML widget, click on the **Expression Builder** button + +2. Enter the expression that will be used in your text and click **OK**. + + Field values can be selected from the **Fields and Values** list. There are other variables and expressions that can be used. + +3. Click on the **+** button to add the expression to the text. + + Here, we configured the widget with this text: + + `Make sure the number plate [% "VRP" %] is visible in the photo.` + + In this case, `VRP` is the name of a field aliased as `Vehicle Registration Plate` in the form. + +4. Save and synchronise your project. + +... and this is how it works during the field survey. `[% "VRP" %]` expression displays the current value of the `Vehicle Registration Plate` field. +![Mergin Maps mobile app text widget with variable](./mobile-text-widget-expression.jpg "Mergin Maps mobile app text widget with variable") + + diff --git a/src/layer/info-widgets/mobile-forms-conditional-visibility.jpg b/src/layer/info-widgets/mobile-forms-conditional-visibility.jpg deleted file mode 100644 index f2ce8450..00000000 Binary files a/src/layer/info-widgets/mobile-forms-conditional-visibility.jpg and /dev/null differ diff --git a/src/layer/info-widgets/mobile-forms-conditional-visibility.xcf b/src/layer/info-widgets/mobile-forms-conditional-visibility.xcf deleted file mode 100644 index 53304a74..00000000 Binary files a/src/layer/info-widgets/mobile-forms-conditional-visibility.xcf and /dev/null differ diff --git a/src/layer/info-widgets/mobile-forms-layout.jpg b/src/layer/info-widgets/mobile-forms-layout.jpg deleted file mode 100644 index 21025a25..00000000 Binary files a/src/layer/info-widgets/mobile-forms-layout.jpg and /dev/null differ diff --git a/src/layer/info-widgets/mobile-forms-layout.xcf b/src/layer/info-widgets/mobile-forms-layout.xcf deleted file mode 100644 index 1c0e554a..00000000 Binary files a/src/layer/info-widgets/mobile-forms-layout.xcf and /dev/null differ diff --git a/src/layer/info-widgets/mobile-forms-open-file-html-widget.jpg b/src/layer/info-widgets/mobile-forms-open-file-html-widget.jpg deleted file mode 100644 index cfdb4307..00000000 Binary files a/src/layer/info-widgets/mobile-forms-open-file-html-widget.jpg and /dev/null differ diff --git a/src/layer/info-widgets/mobile-forms-open-file-html-widget.xcf b/src/layer/info-widgets/mobile-forms-open-file-html-widget.xcf deleted file mode 100644 index 0fa41723..00000000 Binary files a/src/layer/info-widgets/mobile-forms-open-file-html-widget.xcf and /dev/null differ diff --git a/src/layer/info-widgets/mobile-text-widget-preview.webp b/src/layer/info-widgets/mobile-text-widget-preview.webp new file mode 100644 index 00000000..49a1e4de Binary files /dev/null and b/src/layer/info-widgets/mobile-text-widget-preview.webp differ diff --git a/src/layer/info-widgets/mobile-text-widget-preview.xcf b/src/layer/info-widgets/mobile-text-widget-preview.xcf new file mode 100644 index 00000000..5edafc8b Binary files /dev/null and b/src/layer/info-widgets/mobile-text-widget-preview.xcf differ diff --git a/src/layer/info-widgets/qgis-add-group-tab.jpg b/src/layer/info-widgets/qgis-add-group-tab.jpg deleted file mode 100644 index 9b1a3866..00000000 Binary files a/src/layer/info-widgets/qgis-add-group-tab.jpg and /dev/null differ diff --git a/src/layer/info-widgets/qgis-add-group-tab.xcf b/src/layer/info-widgets/qgis-add-group-tab.xcf deleted file mode 100644 index 1be22c3a..00000000 Binary files a/src/layer/info-widgets/qgis-add-group-tab.xcf and /dev/null differ diff --git a/src/layer/info-widgets/qgis-configure-spacer-widget.jpg b/src/layer/info-widgets/qgis-configure-spacer-widget.jpg deleted file mode 100644 index 6c1543b1..00000000 Binary files a/src/layer/info-widgets/qgis-configure-spacer-widget.jpg and /dev/null differ diff --git a/src/layer/info-widgets/qgis-configure-spacer-widget.xcf b/src/layer/info-widgets/qgis-configure-spacer-widget.xcf deleted file mode 100644 index 8282cdc4..00000000 Binary files a/src/layer/info-widgets/qgis-configure-spacer-widget.xcf and /dev/null differ diff --git a/src/layer/info-widgets/qgis-drag-n-drop.gif b/src/layer/info-widgets/qgis-drag-n-drop.gif deleted file mode 100644 index 466bbbc8..00000000 Binary files a/src/layer/info-widgets/qgis-drag-n-drop.gif and /dev/null differ diff --git a/src/layer/info-widgets/qgis-form-add-group.jpg b/src/layer/info-widgets/qgis-form-add-group.jpg deleted file mode 100644 index 173d8bea..00000000 Binary files a/src/layer/info-widgets/qgis-form-add-group.jpg and /dev/null differ diff --git a/src/layer/info-widgets/qgis-form-add-group.xcf b/src/layer/info-widgets/qgis-form-add-group.xcf deleted file mode 100644 index 717d31bc..00000000 Binary files a/src/layer/info-widgets/qgis-form-add-group.xcf and /dev/null differ diff --git a/src/layer/info-widgets/qgis-form-conditional-visibility.jpg b/src/layer/info-widgets/qgis-form-conditional-visibility.jpg deleted file mode 100644 index 5efa9577..00000000 Binary files a/src/layer/info-widgets/qgis-form-conditional-visibility.jpg and /dev/null differ diff --git a/src/layer/info-widgets/qgis-form-conditional-visibility.xcf b/src/layer/info-widgets/qgis-form-conditional-visibility.xcf deleted file mode 100644 index bbe88b03..00000000 Binary files a/src/layer/info-widgets/qgis-form-conditional-visibility.xcf and /dev/null differ diff --git a/src/layer/info-widgets/qgis-form-layout-add-groups-tabs.jpg b/src/layer/info-widgets/qgis-form-layout-add-groups-tabs.jpg deleted file mode 100644 index f6be2f42..00000000 Binary files a/src/layer/info-widgets/qgis-form-layout-add-groups-tabs.jpg and /dev/null differ diff --git a/src/layer/info-widgets/qgis-form-layout-add-groups-tabs.xcf b/src/layer/info-widgets/qgis-form-layout-add-groups-tabs.xcf deleted file mode 100644 index 176c400e..00000000 Binary files a/src/layer/info-widgets/qgis-form-layout-add-groups-tabs.xcf and /dev/null differ diff --git a/src/layer/info-widgets/qgis-form-open-file-html-widget.jpg b/src/layer/info-widgets/qgis-form-open-file-html-widget.jpg deleted file mode 100644 index 19b2c1ec..00000000 Binary files a/src/layer/info-widgets/qgis-form-open-file-html-widget.jpg and /dev/null differ diff --git a/src/layer/info-widgets/qgis-form-open-file-html-widget.xcf b/src/layer/info-widgets/qgis-form-open-file-html-widget.xcf deleted file mode 100644 index 2ee53c46..00000000 Binary files a/src/layer/info-widgets/qgis-form-open-file-html-widget.xcf and /dev/null differ diff --git a/src/layer/info-widgets/qgis-form-spacer-widget.jpg b/src/layer/info-widgets/qgis-form-spacer-widget.jpg deleted file mode 100644 index 4f3cbc9e..00000000 Binary files a/src/layer/info-widgets/qgis-form-spacer-widget.jpg and /dev/null differ diff --git a/src/layer/info-widgets/qgis-form-spacer-widget.xcf b/src/layer/info-widgets/qgis-form-spacer-widget.xcf deleted file mode 100644 index a91e9a9e..00000000 Binary files a/src/layer/info-widgets/qgis-form-spacer-widget.xcf and /dev/null differ diff --git a/src/layer/info-widgets/qgis-form-tabs-groups.jpg b/src/layer/info-widgets/qgis-form-tabs-groups.jpg deleted file mode 100644 index af397540..00000000 Binary files a/src/layer/info-widgets/qgis-form-tabs-groups.jpg and /dev/null differ diff --git a/src/layer/info-widgets/qgis-form-tabs-groups.xcf b/src/layer/info-widgets/qgis-form-tabs-groups.xcf deleted file mode 100644 index 3623e61c..00000000 Binary files a/src/layer/info-widgets/qgis-form-tabs-groups.xcf and /dev/null differ diff --git a/src/layer/info-widgets/qgis-form-text-html.jpg b/src/layer/info-widgets/qgis-form-text-html.jpg deleted file mode 100644 index d387d1ea..00000000 Binary files a/src/layer/info-widgets/qgis-form-text-html.jpg and /dev/null differ diff --git a/src/layer/info-widgets/qgis-form-value-map-roads.jpg b/src/layer/info-widgets/qgis-form-value-map-roads.jpg deleted file mode 100644 index 7fbac56f..00000000 Binary files a/src/layer/info-widgets/qgis-form-value-map-roads.jpg and /dev/null differ diff --git a/src/layer/info-widgets/qgis-form-value-map-roads.xcf b/src/layer/info-widgets/qgis-form-value-map-roads.xcf deleted file mode 100644 index a9a4663b..00000000 Binary files a/src/layer/info-widgets/qgis-form-value-map-roads.xcf and /dev/null differ diff --git a/src/layer/info-widgets/qgis-mobile-html-form.jpg b/src/layer/info-widgets/qgis-mobile-html-form.jpg deleted file mode 100644 index 6bb98a70..00000000 Binary files a/src/layer/info-widgets/qgis-mobile-html-form.jpg and /dev/null differ diff --git a/src/layer/info-widgets/qgis-mobile-html-form.xcf b/src/layer/info-widgets/qgis-mobile-html-form.xcf deleted file mode 100644 index 0ae5097f..00000000 Binary files a/src/layer/info-widgets/qgis-mobile-html-form.xcf and /dev/null differ diff --git a/src/layer/info-widgets/qgis_forms_layout.jpg b/src/layer/info-widgets/qgis_forms_layout.jpg deleted file mode 100644 index ed35c767..00000000 Binary files a/src/layer/info-widgets/qgis_forms_layout.jpg and /dev/null differ diff --git a/src/layer/info-widgets/qgis_forms_layout.xcf b/src/layer/info-widgets/qgis_forms_layout.xcf deleted file mode 100644 index 5a01c56b..00000000 Binary files a/src/layer/info-widgets/qgis_forms_layout.xcf and /dev/null differ diff --git a/src/layer/info-widgets/spacer-widget-forms.jpg b/src/layer/info-widgets/spacer-widget-forms.jpg deleted file mode 100644 index 545a9ebc..00000000 Binary files a/src/layer/info-widgets/spacer-widget-forms.jpg and /dev/null differ diff --git a/src/layer/info-widgets/spacer-widget-forms.xcf b/src/layer/info-widgets/spacer-widget-forms.xcf deleted file mode 100644 index 577fe798..00000000 Binary files a/src/layer/info-widgets/spacer-widget-forms.xcf and /dev/null differ diff --git a/src/layer/link-to-navigation/index.md b/src/layer/link-to-navigation/index.md new file mode 100644 index 00000000..a48e980f --- /dev/null +++ b/src/layer/link-to-navigation/index.md @@ -0,0 +1,31 @@ +--- +description: Hyperlinks can be used in the attributes form in Mergin Maps mobile app to open a link to a navigation app directly from the feature's form. +--- + +# How to Open a Link to a Navigation App +[[toc]] + +Attributes forms can include clickable links that can be used to open a navigation app directly from the form in . + +:::tip +Clone to follow this example! +::: + +Let's say you want to find your surveyed features on Google Maps. It is possible to do so directly from , you just need to set up a **text field** that will open Google Maps and enter the coordinates of the feature to the Google Maps search bar. + +1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. +2. In the list of **Available Widgets** select the field you want to work with. +3. In the **Widget Display** tab: + - Ensure that **Text Edit** is selected + - Check the **Multiline** and **HTML** options +4. In the **Defaults** tab, use this string as **Default value**: + `'Open Google Map'` +5. Check the **Apply default value on update** option +6. **Apply** the changes. Don't forget to save and sync your project! + +![Link to Google maps in QGIS Attributes form](./qgis-google-maps.jpg "Link to Google Maps in QGIS Attributes form") + +When you tap a feature in the , the form will display a clickable link **Open Google Map** that opens the Google Map app at the position of the feature. + +![Open Google map from Mergin Maps mobile app](./mobile-form-link-to-navigation-app.jpg "Open Google map from Mergin Maps mobile app") + diff --git a/src/layer/external-link/mobile-form-link-to-navigation-app.jpg b/src/layer/link-to-navigation/mobile-form-link-to-navigation-app.jpg similarity index 100% rename from src/layer/external-link/mobile-form-link-to-navigation-app.jpg rename to src/layer/link-to-navigation/mobile-form-link-to-navigation-app.jpg diff --git a/src/layer/external-link/mobile-form-link-to-navigation-app.xcf b/src/layer/link-to-navigation/mobile-form-link-to-navigation-app.xcf similarity index 100% rename from src/layer/external-link/mobile-form-link-to-navigation-app.xcf rename to src/layer/link-to-navigation/mobile-form-link-to-navigation-app.xcf diff --git a/src/layer/external-link/qgis-google-maps.jpg b/src/layer/link-to-navigation/qgis-google-maps.jpg similarity index 100% rename from src/layer/external-link/qgis-google-maps.jpg rename to src/layer/link-to-navigation/qgis-google-maps.jpg diff --git a/src/layer/external-link/qgis-google-maps.xcf b/src/layer/link-to-navigation/qgis-google-maps.xcf similarity index 100% rename from src/layer/external-link/qgis-google-maps.xcf rename to src/layer/link-to-navigation/qgis-google-maps.xcf diff --git a/src/layer/numbers/index.md b/src/layer/numbers/index.md index 04460852..d7d41c5d 100644 --- a/src/layer/numbers/index.md +++ b/src/layer/numbers/index.md @@ -1,47 +1,51 @@ -# Numbers - -Number fields can be handled by the **Range** widget. Two options are supported by the : [editable range](#range) and [slider](#slider). - -|
Widget
|Preview in the | -|:---:|:---:| -| [Editable range](#range) | ![Mergin Maps mobile app numeric field form](./mobile-form-number-editable-preview.jpg "Mergin Maps mobile app numeric field form") | -| [Slider](#slider) | ![Mergin Maps mobile app slider field form](./mobile-form-number-slider-preview.jpg "Mergin Maps mobile app slider field form") | - -:::tip Example project available -This public project: uses various options for entering numbers. Download or clone it to see this setup. -::: - -Prefer a video? Here is a short tutorial about number widgets: - - -## Range -To set up the **editable range widget**: - -1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. -2. In the list of **Available Widgets** select the integer field you want to work with (here: `numbers-range-editable`). -3. In the **Widget Type** tab the **Range** widget and the **Editable** option should be selected by default. If this is not the case, select these options from the drop-down menus. -4. **Apply** the changes. Don't forget to save and sync your project! - -![QGIS number editable range field form](./qgis-form-number-range-editable.jpg "QGIS number editable range field form") - -In the , the numbers can be entered manually or by using the +/- buttons: - -![Mergin Maps mobile app number range field form](./mobile-form-editable-range.jpg "Mergin Maps mobile app number range field form") - -## Slider -To set up the **Slider**: - -1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. -2. In the list of **Available Widgets** select the numeric field you want to work with (here: `numbers-range-slider`). -3. In the **Widget Type** tab: - - the **Range** widget should be selected by default (if not, select it from the menu) - - set the edit widget to **Slider** - - set the **Minimum**, **Maximum** and **Step** values of the slider -4. **Apply** the changes. Don't forget to save and sync your project! - -![QGIS number range field form](./qgis-form-number-range-slider.jpg "QGIS number range field form") - -In the , the **Slider** looks like this. The number can be filled in by moving the slider: - -![Mergin Maps mobile app number range field form](./mobile-form-range-slider.jpg "Mergin Maps mobile app number range field form") - +--- +description: See how to set up Editable Range or Range Slider to record numbers in the forms in Mergin Maps mobile app. +--- + +# Numbers + +Number fields can be handled by the **Range** widget that offers two options supported by the : [editable range](#range) and [slider](#slider). + +|
Widget
|Preview in the | +|:---:|:---:| +| Editable range | ![Mergin Maps mobile app numeric field form](./mobile-form-number-editable-preview.jpg "Mergin Maps mobile app numeric field form") | +| Slider | ![Mergin Maps mobile app slider field form](./mobile-form-number-slider-preview.jpg "Mergin Maps mobile app slider field form") | + +:::tip Example project available +This public project: uses various options for entering numbers. Download or clone it to see this setup. +::: + +Prefer a video? Here is a short tutorial about number widgets: + + +## Range +To set up the **editable range widget**: + +1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. +2. In the list of **Available Widgets** select the integer field you want to work with (here: `numbers-range-editable`). +3. In the **Widget Type** tab the **Range** widget and the **Editable** option should be selected by default. If this is not the case, select these options from the drop-down menus. +4. **Apply** the changes. Don't forget to save and sync your project! + +![QGIS number editable range field form](./qgis-form-number-range-editable.jpg "QGIS number editable range field form") + +In the , the numbers can be entered manually or by using the +/- buttons: + +![Mergin Maps mobile app number range field form](./mobile-form-editable-range.jpg "Mergin Maps mobile app number range field form") + +## Slider +To set up the **Slider**: + +1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. +2. In the list of **Available Widgets** select the numeric field you want to work with (here: `numbers-range-slider`). +3. In the **Widget Type** tab: + - the **Range** widget should be selected by default (if not, select it from the menu) + - set the edit widget to **Slider** + - set the **Minimum**, **Maximum** and **Step** values of the slider +4. **Apply** the changes. Don't forget to save and sync your project! + +![QGIS number range field form](./qgis-form-number-range-slider.jpg "QGIS number range field form") + +In the , the **Slider** looks like this. The number can be filled in by moving the slider: + +![Mergin Maps mobile app number range field form](./mobile-form-range-slider.jpg "Mergin Maps mobile app number range field form") + diff --git a/src/layer/one-to-n-relations/index.md b/src/layer/one-to-n-relations/index.md index 07c95f12..86c0a1ef 100644 --- a/src/layer/one-to-n-relations/index.md +++ b/src/layer/one-to-n-relations/index.md @@ -1,58 +1,69 @@ -# How to Link Multiple Records to One Feature -[[toc]] - -It is often the case that you have a set of spatial features and you want to record their status every now and then. - -For example, there is a GIS layer representing the manholes and the surveyors carry out regular inspections of the manholes using . Instead of duplicating the manhole layer and recording each inspection as a new feature, inspections can be recorded in a non-spatial table that is linked to the spatial layer. This way, multiple records can be linked to one feature as a [one to many relation](../relations/). - -The image below shows the manhole locations and a form with listed inspections in . - -![Multiple inspections linked to one point in Mergin Maps mobile app](./mobile-1-n-relation.jpg "Multiple inspections linked to one point in Mergin Maps mobile app") - - -:::tip Example project available -You can follow this example by cloning . -::: - -The manhole point layer has the following attribute table: - -| fid | Manhole | Manhole UUID | -|:---:|:---:|:---:| -| 1 | 1 | `{70c59616-492e-4757-aa9a-ee61b207ce94}` | -| 2 | 2 | `{be01b98f-3585-49d4-be74-4cf3530a2989}` | -| 3 | 3 | `{03178264-0070-45c8-a981-b2474627d7e0}` | - -This layer contains only information about the manholes. `Manhole UUID` values are generated using the [`uuid()` function](../relations/#generating-unique-ids-uuid) when a feature is created. This ensures that these values are **unique** even when multiple surveyors capture new features at the same time. This field will be used to link inspections and manholes. - -:::danger Using UUID -**Why UUID?** FID can be changed during [synchronisation](../../manage/synchronisation/). As a result, records can end up being linked to wrong features. - -On the other hand, (Universally Unique Identifier) is generated to be unique and will not be changed when synced. Therefore, we recommend always using UUID to link layers. -::: - -To configure 1-N relations in QGIS: -1. From the main menu, select **Projects** > **Properties ...** -2. In the **Relations** tab, select **Add Relation** - ![Layer properties in QGIS with highlighted Relations tab and Add Relation button](../attach-multiple-photos-to-features/qgis_relation_tab.jpg "Layer properties in QGIS with highlighted Relations tab and Add Relation button") -3. A new window will appear, where we can define the parent and child layers and the fields to link the two layers: - - **Name** is the name of the relation, e.g. `Inspection` - - **Referenced (parent)** is the spatial layer `manhole_locations` - - **Field 1** of the **Referenced (parent)** is the field `Manhole UUID` that contains the **unique** UUID - - **Referencing (child)** is the non-spatial layer `inspections` - - **Field 1** of the **Referencing (child)** layer is the `Manhole UUID`, which acts as a foreign key to link inspections to spatial features - - ![Add Relation form in QGIS with defined 1-N relation between the parent and the child layer](./qgis-add-relation.jpg "Add Relation form in QGIS with defined 1-N relation between the parent and the child layer") - -4. Right-click on the survey layer, select **Properties** and go to the **Attributes** form tab. -5. Drag and drop the **Inspections** relation to the **Form Layout**. - ![Relation added to the Drag and Drop Form Layout in QGIS](./qgis-forms-relations-setup.jpg "Relation added to the Drag and Drop Form Layout in QGIS") - -Now you can add multiple inspections for each manhole location. The inspections records will be stored in the `inspections` table. - -When you open the form for an existing record in the `manhole_locations` point layer, it will display existing inspection records and you can also add, delete or edit the records: -![Form view of a feature with 1-N relation in QGIS](./qgis-1-N-form.jpg "Form view of a feature with 1-N relation in QGIS") - -In the , the form will display all linked inspection records. Tapping the **+** button opens the inspection form and a new inspection record can be added. - -![Form view of a feature with 1-N relation in Mergin Maps mobile app](./mobile-form-1-n-relation.jpg "Form view of a feature with 1-N relation in Mergin Maps mobile app") - +--- +description: Do you need to link multiple records to one feature in Mergin Maps? Set up 1-N relations for your layers in QGIS. +--- + +# How to Link Multiple Records to One Feature +[[toc]] + +It is often the case that you have a set of spatial features and you want to record their status every now and then. + +For example, there is a GIS layer representing the manholes and the surveyors carry out regular inspections of the manholes using . Instead of duplicating the manhole layer and recording each inspection as a new feature, inspections can be recorded in a non-spatial table that is linked to the spatial layer. This way, multiple records can be linked to one feature as a [one to many relation](../relations/). + +The image below shows the manhole locations and a form with listed inspections in . + +![Multiple inspections linked to one point in Mergin Maps mobile app](./mobile-1-n-relation.webp "Multiple inspections linked to one point in Mergin Maps mobile app") + + +:::tip Example project available +Clone our public project to follow this setup. The project includes a data sample. +::: + +The **manhole point layer** has the following attribute table: + +| fid | Manhole | Manhole uuid (`uuid`) | +|:---:|:---:|:---:| +| 1 | 1 | `{db908450-4265-4070-a3f7-1d73705df8bf}` | +| 2 | 2 | `{aeea4c7d-e7c5-4638-8207-53fa469ccddd}` | +| 3 | 3 | `{042a715a-73ac-4bff-9bb0-7f598d216ec9}` | + +This layer contains only information about the manholes. **Manhole uuid** (`uuid`) values are unique values generated using the [`uuid()` function](../relations/#generating-unique-ids-uuid) when a feature is created. This field will be used to link inspections and manholes. + +:::danger Using UUID +**Why UUID?** FID can be changed during [synchronisation](../../manage/synchronisation/). As a result, records can end up being linked to wrong features. + +On the other hand, (Universally Unique Identifier) is generated to be unique and will not be changed when synced. Therefore, we recommend always using UUID to link layers. +::: + +The **non-spatial inspections table** has the following attributes. **Manhole uuid** (`parent-uuid`) are references to manholes. +| fid | Date | Blocked? | Flooded? | Inspector | Manhole uuid (`parent-uuid`) | +|:---:|:---:|:---:|:---:|:---:|:---:| +| 8 | 2025-11-20 | false |false| | `{db908450-4265-4070-a3f7-1d73705df8bf}` | +| 9 | 2025-11-28 | false |true | | `{db908450-4265-4070-a3f7-1d73705df8bf}` | +| 10 | 2025-12-01 | true |true| | `{aeea4c7d-e7c5-4638-8207-53fa469ccddd}` | +| 11 | 2025-12-03 | false |false| | `{042a715a-73ac-4bff-9bb0-7f598d216ec9}` | + +To configure 1-N relations in QGIS (detailed steps can be found in [Relations](../relations/#setting-up-relation-in-qgis)): +1. From the main menu, select **Projects** > **Properties ...** +2. In the **Relations** tab, select **Add Relation** +3. Define the parent and child layers and the fields to link the two layers: + - **Name** is the name of the relation, e.g. `Inspection` + - **Referenced (parent)** is the spatial layer `manhole_locations` + - **Field 1** of the **Referenced (parent)** is the field `Manhole UUID` that contains the **unique** UUID + - **Referencing (child)** is the non-spatial layer `inspections` + - **Field 1** of the **Referencing (child)** layer is the `Manhole UUID`, which acts as a foreign key to link inspections to spatial features + + ![Add Relation form in QGIS with defined 1-N relation between the parent and the child layer](./qgis-add-relation.jpg "Add Relation form in QGIS with defined 1-N relation between the parent and the child layer") + +4. Navigate to the **Attributes form** tab in Layer **Properties** of the survey layer (`manhole_locations`) +5. Add the **Inspections** relation to the **Form Layout** + ![Relation added to the Drag and Drop Form Layout in QGIS](./qgis-forms-relations-setup.webp "Relation added to the Drag and Drop Form Layout in QGIS") + +Now you can add multiple inspections for each manhole location. The inspections records will be stored in the `inspections` table. + +When you open the form for an existing record in the `manhole_locations` point layer, it will display existing inspection records and you can also add, delete or edit the records: +![Form view of a feature with 1-N relation in QGIS](./qgis-1-N-form.webp "Form view of a feature with 1-N relation in QGIS") + +In the , the form will display all linked inspection records. Tapping the **+** button opens the inspection form and a new inspection record can be added. + +![Form view of a feature with 1-N relation in Mergin Maps mobile app](./mobile-form-1-n-relation.webp "Form view of a feature with 1-N relation in Mergin Maps mobile app") + diff --git a/src/layer/one-to-n-relations/mobile-1-n-relation.jpg b/src/layer/one-to-n-relations/mobile-1-n-relation.jpg deleted file mode 100644 index 624cda6d..00000000 Binary files a/src/layer/one-to-n-relations/mobile-1-n-relation.jpg and /dev/null differ diff --git a/src/layer/one-to-n-relations/mobile-1-n-relation.webp b/src/layer/one-to-n-relations/mobile-1-n-relation.webp new file mode 100644 index 00000000..75ff64c3 Binary files /dev/null and b/src/layer/one-to-n-relations/mobile-1-n-relation.webp differ diff --git a/src/layer/one-to-n-relations/mobile-1-n-relation.xcf b/src/layer/one-to-n-relations/mobile-1-n-relation.xcf index 0f987e1a..f6b67239 100644 Binary files a/src/layer/one-to-n-relations/mobile-1-n-relation.xcf and b/src/layer/one-to-n-relations/mobile-1-n-relation.xcf differ diff --git a/src/layer/one-to-n-relations/mobile-form-1-n-relation.jpg b/src/layer/one-to-n-relations/mobile-form-1-n-relation.jpg deleted file mode 100644 index bf1af5b0..00000000 Binary files a/src/layer/one-to-n-relations/mobile-form-1-n-relation.jpg and /dev/null differ diff --git a/src/layer/one-to-n-relations/mobile-form-1-n-relation.webp b/src/layer/one-to-n-relations/mobile-form-1-n-relation.webp new file mode 100644 index 00000000..89599364 Binary files /dev/null and b/src/layer/one-to-n-relations/mobile-form-1-n-relation.webp differ diff --git a/src/layer/one-to-n-relations/mobile-form-1-n-relation.xcf b/src/layer/one-to-n-relations/mobile-form-1-n-relation.xcf index 116b8686..e4ebaad7 100644 Binary files a/src/layer/one-to-n-relations/mobile-form-1-n-relation.xcf and b/src/layer/one-to-n-relations/mobile-form-1-n-relation.xcf differ diff --git a/src/layer/one-to-n-relations/mobile-multiple-photos.jpg b/src/layer/one-to-n-relations/mobile-multiple-photos.jpg deleted file mode 100644 index ac94cc27..00000000 Binary files a/src/layer/one-to-n-relations/mobile-multiple-photos.jpg and /dev/null differ diff --git a/src/layer/one-to-n-relations/mobile-multiple-photos.xcf b/src/layer/one-to-n-relations/mobile-multiple-photos.xcf deleted file mode 100644 index 6b1e7b2e..00000000 Binary files a/src/layer/one-to-n-relations/mobile-multiple-photos.xcf and /dev/null differ diff --git a/src/layer/one-to-n-relations/qgis-1-N-form.jpg b/src/layer/one-to-n-relations/qgis-1-N-form.jpg deleted file mode 100644 index 77b91108..00000000 Binary files a/src/layer/one-to-n-relations/qgis-1-N-form.jpg and /dev/null differ diff --git a/src/layer/one-to-n-relations/qgis-1-N-form.webp b/src/layer/one-to-n-relations/qgis-1-N-form.webp new file mode 100644 index 00000000..7bcd7735 Binary files /dev/null and b/src/layer/one-to-n-relations/qgis-1-N-form.webp differ diff --git a/src/layer/one-to-n-relations/qgis-1-N-form.xcf b/src/layer/one-to-n-relations/qgis-1-N-form.xcf index 8e2ae1b0..f7446599 100644 Binary files a/src/layer/one-to-n-relations/qgis-1-N-form.xcf and b/src/layer/one-to-n-relations/qgis-1-N-form.xcf differ diff --git a/src/layer/one-to-n-relations/qgis-forms-relations-setup.jpg b/src/layer/one-to-n-relations/qgis-forms-relations-setup.jpg deleted file mode 100644 index 2952a80c..00000000 Binary files a/src/layer/one-to-n-relations/qgis-forms-relations-setup.jpg and /dev/null differ diff --git a/src/layer/one-to-n-relations/qgis-forms-relations-setup.webp b/src/layer/one-to-n-relations/qgis-forms-relations-setup.webp new file mode 100644 index 00000000..5b94f8be Binary files /dev/null and b/src/layer/one-to-n-relations/qgis-forms-relations-setup.webp differ diff --git a/src/layer/one-to-n-relations/qgis-forms-relations-setup.xcf b/src/layer/one-to-n-relations/qgis-forms-relations-setup.xcf index 74258348..c8751a77 100644 Binary files a/src/layer/one-to-n-relations/qgis-forms-relations-setup.xcf and b/src/layer/one-to-n-relations/qgis-forms-relations-setup.xcf differ diff --git a/src/layer/one-to-n-relations/qgis_relation_form.jpg b/src/layer/one-to-n-relations/qgis_relation_form.jpg deleted file mode 100644 index 6779bb99..00000000 Binary files a/src/layer/one-to-n-relations/qgis_relation_form.jpg and /dev/null differ diff --git a/src/layer/one-to-n-relations/qgis_relation_form.xcf b/src/layer/one-to-n-relations/qgis_relation_form.xcf deleted file mode 100644 index db21b393..00000000 Binary files a/src/layer/one-to-n-relations/qgis_relation_form.xcf and /dev/null differ diff --git a/src/layer/one-to-n-relations/qgis_relation_photos.jpg b/src/layer/one-to-n-relations/qgis_relation_photos.jpg deleted file mode 100644 index 1962b940..00000000 Binary files a/src/layer/one-to-n-relations/qgis_relation_photos.jpg and /dev/null differ diff --git a/src/layer/one-to-n-relations/qgis_relation_photos.xcf b/src/layer/one-to-n-relations/qgis_relation_photos.xcf deleted file mode 100644 index 43db54bf..00000000 Binary files a/src/layer/one-to-n-relations/qgis_relation_photos.xcf and /dev/null differ diff --git a/src/layer/one-to-n-relations/qgis_relation_tab.jpg b/src/layer/one-to-n-relations/qgis_relation_tab.jpg deleted file mode 100644 index eaacfcf4..00000000 Binary files a/src/layer/one-to-n-relations/qgis_relation_tab.jpg and /dev/null differ diff --git a/src/layer/one-to-n-relations/qgis_relation_tab.xcf b/src/layer/one-to-n-relations/qgis_relation_tab.xcf deleted file mode 100644 index ddfc97ac..00000000 Binary files a/src/layer/one-to-n-relations/qgis_relation_tab.xcf and /dev/null differ diff --git a/src/layer/one-to-n-relations/uuid-default.jpg b/src/layer/one-to-n-relations/uuid-default.jpg deleted file mode 100644 index f9b16777..00000000 Binary files a/src/layer/one-to-n-relations/uuid-default.jpg and /dev/null differ diff --git a/src/layer/one-to-n-relations/uuid-default.xcf b/src/layer/one-to-n-relations/uuid-default.xcf deleted file mode 100644 index 1ce56359..00000000 Binary files a/src/layer/one-to-n-relations/uuid-default.xcf and /dev/null differ diff --git a/src/layer/one-to-n-relations/uuid-field.jpg b/src/layer/one-to-n-relations/uuid-field.jpg deleted file mode 100644 index c1361923..00000000 Binary files a/src/layer/one-to-n-relations/uuid-field.jpg and /dev/null differ diff --git a/src/layer/one-to-n-relations/uuid-field.xcf b/src/layer/one-to-n-relations/uuid-field.xcf deleted file mode 100644 index a98c0275..00000000 Binary files a/src/layer/one-to-n-relations/uuid-field.xcf and /dev/null differ diff --git a/src/layer/open-file/index.md b/src/layer/open-file/index.md index 9eba18fe..a97080a9 100644 --- a/src/layer/open-file/index.md +++ b/src/layer/open-file/index.md @@ -1,50 +1,55 @@ -# How to Open a File -[[toc]] - -A local file, e.g. a PDF stored in the project folder, can be opened from within the form. This can be achieved by using [the HTML widget](#using-html-widget-to-open-local-files) or setting up [default values](#open-local-files-using-default-values). - -::: tip Public project available -Download or clone our public project to explore both options and see what works the best for you. -::: - -## Using HTML widget to open local files -The HTML widget can be used to open local files: for instance, a locally stored PDF file can be opened from within the form during the survey. - -::: tip Example project available -This setup is used in our public project . -::: - -- 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") - -## 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). - -::: tip Example project available -This setup is used in our public project . -::: - -- 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") - +--- +description: A local file, e.g. a PDF stored in the project folder, can be opened from within the form using the HTML widget. +--- + +# How to Open a File +[[toc]] + +A local file, e.g. a PDF stored in the project folder, can be opened from within the form using [the HTML widget](../info-widgets/#html-widget). There is an alternative setting that uses [default values](#open-local-files-using-default-values) that may be useful for specific scenarios. + +::: tip Public project available +Download or clone our public project to explore both options and see what works the best for you. +::: + +## Using HTML widget to open local files +The HTML widget can be used to open local files: for instance, a locally stored PDF file can be opened from within the form during the survey. + +::: tip Example project available +This setup is used in our public project . +::: + +- 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") + +## Open local files using default values + +Local files (e.g. a PDF file) can also be opened from within the form using default values. 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). + +::: tip Example project available +This setup is used in our public project . +::: + +- 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") + diff --git a/src/layer/overview/index.md b/src/layer/overview/index.md index cec24d7e..42f8905a 100644 --- a/src/layer/overview/index.md +++ b/src/layer/overview/index.md @@ -1,17 +1,38 @@ ---- -description: In the Configure forms section, you will find everything you need to set up attributes forms for spatial and non-spatial layers in your Mergin Maps project. ---- - -# Overview -[[toc]] - -Capturing field data includes recording some information about surveyed points, lines, polygons or non-spatial features by filling in attributes form. This section will guide you through various settings of attributes forms for spatial and non-spatial layers. - -There are various widgets available to use in the attributes form depending on the field data type and preferred type of data input. [Widgets](../form-widgets/) provide a comprehensive overview of and their use in . - -Extra configuration of attribute forms can be done to make data collection easier and more consistent, such as: -- using [default values](../default-values/) to automatically record attribute's values -- setting [constraints](../constraints/) to define valid inputs for the attributes -- designing the [attributes forms layout](../form-layout/) so that the forms are easy to work with - -In [Use Cases](../use-cases), you can find step-by-step guides to deal with specific scenarios, such as [opening files](../open-file/) from within the form, [using hyperlinks](../external-link/), [displaying instructions](../display-instructions/) in the form and much more. +--- +description: In the Configure forms section, you will find everything you need to set up attributes forms for spatial and non-spatial layers in your Mergin Maps project. +--- + +# Configure Forms Overview + +Capturing field data includes recording some information about surveyed points, lines, polygons or non-spatial features by filling in attributes form. This section will guide you through various settings of attributes forms for spatial and non-spatial layers. + +:::tip Mergin Maps project setup in QGIS +In this section, we focus specifically on configuring forms for field survey layers. We recommend using **GeoPackage** format for your layers. + +To learn how to create your project and add survey layers, follow our tutorial [Creating a Project in QGIS](../../tutorials/creating-a-project-in-qgis/). Additional tips for project setup can be found in [QGIS project preparation](../../gis/features/). +::: + +Just as other project settings, the forms for data collection are configured in and follows these settings. + +Each layer has its own form. By default, the form is automatically generated, contains all the fields and these fields have a default type of data input. This means that even without a special configuration, you are able to fill in the form with valid input values. These default options can be changed to fit the needs of your field survey. You can define the type of data input for each field by choosing a . See our [widget gallery](../form-widgets/) for a quick overview of available widgets. + +Do you prefer a video? Check out this tutorial on how to configure QGIS widgets for survey forms. + + +## Setting up form widgets + +Attributes forms can be configured using in the **Attributes Form** tab in the **Layer Properties**. Note that the widget has to be compatible with the field data type. + +Each data type has a default widget: for instance, text fields use *Text edit* widget by default and are filled in by manually typing the value, while date fields use *Date/Time* widget and the value is selected using a calendar pop-up. + +![QGIS Layer Properties Attributes Form tab](./qgis-attributes-form.gif "QGIS Layer Properties Attributes Form tab") + +## Layout and configuration + +Extra configuration of attribute forms can be done to make data collection easier and more consistent, such as: +- using [default values](../default-values/) to automatically record attribute's values +- setting [constraints](../constraints/) to define valid inputs for the attributes +- designing the [attributes forms layout](../form-layout/) so that the forms are easy to work with + +In [Use Cases](../use-cases), you can find step-by-step guides to deal with specific scenarios, such as [opening files](../open-file/) from within the form, [using hyperlinks](../external-link/), [open a link to a navigation app](../link-to-navigation/) in the form and much more. + diff --git a/src/layer/form-widgets/qgis-attributes-form.gif b/src/layer/overview/qgis-attributes-form.gif similarity index 100% rename from src/layer/form-widgets/qgis-attributes-form.gif rename to src/layer/overview/qgis-attributes-form.gif diff --git a/src/layer/photos/index.md b/src/layer/photos/index.md index f74ea6d4..38df12e5 100644 --- a/src/layer/photos/index.md +++ b/src/layer/photos/index.md @@ -1,178 +1,180 @@ ---- -outline: deep ---- - -# Photos -[[toc]] - -Adding photos to a surveyed feature can be really helpful. With , you can quickly take photos during the survey, share them with your team and store them in the cloud. You can either capture a photo using your camera or select existing photos from the gallery. - - offers some useful functionalities for capturing photos: -- More than one photo can be attached to one feature. Follow our guide [How to attach multiple photos to features](#how-to-attach-multiple-photos-to-one-feature) to do so. -- Photos can be named automatically based on a [customised names format](#customising-photo-name-format-with-expressions). -- Synchronising photos during the field survey can use up a lot of mobile data, depending on the amount of pictures taken and their size. To reduce the data usage, you may use [selective synchronisation](../../manage/selective_sync/), [resizing pictures automatically](../../gis/features/#photo-quality) or following the [offline field survey workflow](../../field/offline-use/#offline-field-survey-workflow). - -|
Widget
|Preview in the | -|:---:|:---:| -[Attachment - Photos from device's camera or gallery](#photo-attachment-widget-in-qgis) | ![Mergin Maps mobile app attachment field form](../form-widgets/mobile-form-photo-preview.jpg "Mergin Maps mobile app attachment field form") ![Mergin Maps mobile app attachment field form](../form-widgets/mobile-form-photo-preview2.jpg "Mergin Maps mobile app attachment field form") | -|[Relation - Gallery ](#how-to-attach-multiple-photos-to-one-feature) | ![Mergin Maps mobile app multiple photos attributes form](../form-widgets/mobile-form-multiple-photo-preview.jpg "Mergin Maps mobile app multiple photos attributes form") | - - -:::tip Example projects available -To see the basic [attachment widget](#photo-attachment-widget-in-qgis) setup for photos, clone . - -If you want to [attach multiple photos to one feature](#how-to-attach-multiple-photos-to-one-feature) explore the public project . -::: - -## Photo attachment widget in QGIS - -:::tip Example project available -Clone to follow this example! -::: - -To add photos to features using the , the attributes form of a survey layer needs to have a field with data type `Text (string)` configured with the **Attachment** widget in QGIS as follows: - -To set up the attachment widget: -1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. -2. In the list of **Available Widgets** select the text field you want to work with. -3. In the **Widget Display** tab: - - From the drop-down menu, select **Attachment** - - **Default path** defines where images will be saved. If it is not defined, the project home folder will be used. - - Store the path as **Relative to project path** or **Relative to default path** depending on how you want to store the paths. - - ![QGIS photo attachment widget form](./qgis_form_photo.webp "QGIS photo attachment widget form") - - :::danger Avoid using absolute paths - Using *absolute paths* causes issues when working with your projects on different devices or working in a team: as each device or team member can use different paths, they may be unable to display the images. - ::: - -4. **Apply** the changes. Don't forget to save and sync your project! - -In the , this field will provide two options: -- **Take a picture** to use your camera app for taking a photos -- **From gallery** to attach an existing photo from your device - -![Mergin Maps mobile app photo widget](./mobile-form-attachment-photo.jpg "Mergin Maps mobile app photo widget") - -## Custom folder for storing photos {#how-to-set-up-a-custom-folder-for-storing-photos} -It can be useful to set up a custom folder for photos, e.g. if you want to use [selective synchronisation](../../manage/selective_sync/) or if you simply want to have your data organised. - -To set up a custom folder: -1. Create a subfolder in the project folder (here: `photos`) -2. Open your project in QGIS -3. Open the **Properties** of the survey layer and navigate to the **Attributes form** tab. - - Select the field, where photos are stored (here: `photo`) and make sure that the widget type is set to [**Attachment**](#photo-attachment-widget-in-qgis) - ![QGIS photo attachment widget form](./qgis_form_photo.webp "QGIS photo attachment widget form") - -5. Now we need to change the **Default path** to the folder we have created. Click on the *Data defined override* icon and choose **Edit...** - ![QGIS edit default path expression](./qgis_form_photo_edit_expr.jpg "QGIS edit default path expression") - -6. In **Expression String Builder** enter the expression `@project_folder + '/photos'` (replace `photos` by the name of your folder). Click **OK**. - ![QGIS enter default path expression](./qgis_forms_photo_expression.jpg "QGIS enter default path expression") - -7. The **Default path** now refers to the custom folder. - ![QGIS default path to custom folder](./qgis_custom_folder.jpg "QGIS default path to custom folder") - -8. **Apply the changes**. Don't forget to save and sync your project! - -### Overview of paths for attachment widget - -Here is an overview of paths that can be stored in various settings of the attachment widget. - -| Default path | Store path as | Value | -|:-------------------------: |:------------: |:----------------------------------: | -| - | Relative to project path | `image.jpg` | -| - | Relative to default path | `image.jpg` | -| `@project_folder` | Relative to project path | `image.jpg` | -| `@project_folder` | Relative to default path | `image.jpg` | -| `@project_home + '/photos'` | Relative to project path | `/photos/image.jpg` | -| `@project_home + '/photos'` | Relative to default path | `image.jpg` | - - -## Resizing pictures automatically -Photos that are captured during the field survey or uploaded using can be automatically resized, e.g. to save up storage space. The quality of the photos can be set up in the [ project properties](../../gis/features/#photo-quality) using . - -## Customising photo name format with expressions -Photos taken in the field using can be automatically renamed. This can be useful when browsing pictures in your project and keeping them organised. - -[**How to Set Photo Names Format**](../../gis/photo-names/) will guide you through the setup and provide examples of expressions that can be used to name your photos. - -## Displaying photos in QGIS -Photos taken using during the survey can be displayed in the feature's form in QGIS. - -1. In QGIS, double click on a survey layer to open **Layer Properties** -2. In the **Attributes Form** tab, select the field that contains the path to the photo. - - Scroll to the **Integrated Document Viewer** in the panel on the right. Set the **Type** to *Image*. - ![QGIS Integrated Document Viewer](./qgis-doc-viewer.jpg "QGIS Integrated Document Viewer") - -3. **Apply** the changes and click **OK**. - -Now when you click on a feature that contains a photo, it will be displayed in the form. - -![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. -::: - - -## How to attach multiple photos to one feature - -In some situations, it might be useful to take more than one picture of a feature during the field survey. Attaching multiple photos to one feature is a **one to many relation**. You can read more about this topic in general in [Relations](../relations). - -|
Widget
|Preview in the | -|:---:|:---:| -|Relation - Gallery | ![Mergin Maps mobile app multiple photos attributes form](../form-widgets/mobile-form-multiple-photo-preview.jpg "Mergin Maps mobile app multiple photos attributes form") | - -:::tip Example project available -To see this setup in practice, you can download this public project . -::: - - - -### Non-spatial layer for storing photos -To link multiple photos to a single feature, we need to have a non-spatial layer (table) to store the paths to the photos. - -1. Here we will create a new GeoPackage layer named `photos` with following attributes: - - `photo` with `Text (string)` data type to store the photo path - - `external-pk` with `Text (string)` data type to store the reference to the feature from the survey layer - - ![QGIS creating a non-spatial layer for storing photos](./qgis-create-photos-table.webp "QGIS creating a non-spatial layer for storing photos") - - ::: tip Using default values - You may add other attributes as needed, e.g. to record the username or dates automatically using [default values](../default-values/). - ::: - -2. Now we need to configure the attributes form: set the `photo` field to store photo paths as described in the [photo attachment widget](#photo-attachment-widget-in-qgis). - -### Relation setup -The `photos` layer will be linked to the survey layer using an UUID: the survey layer needs to have a **unique UUID** field generated by the `uuid()` function (see how to set it up [here](../relations/#generating-unique-ids-uuid)) and the [`photos` layer](#non-spatial-layer-for-storing-photos) has a field to store the foreign key (here: `external-pk`). - -:::danger Use UUIDs to link layers -**Do not use the FID field to link these tables**. FIDs can be changed during synchronisation, which can result in having photos linked to the incorrect feature. See [Behind Data Synchronisation](../../manage/synchronisation/) for more details. - -You should always use unique UUIDs generated by the `uuid()` function to link layers as they do not change during the sync. -::: - -Navigate to the [**Relations**](../relations/#setting-up-relation-in-qgis) tab in **Project Properties** and **Add Relation** as follows: -- **Name** is the name of the relation, can be left blank -- **Referenced (parent)** is the spatial layer `Survey` -- **Field 1** of the **Referenced (parent)** is the field `unique-id` that contains the UUID -- **Referencing (child)** is the non-spatial layer `photos` -- **Field 1** of the **Referencing (child)** layer is the `external-pk` that contains the foreign key to link photos with surveyed features. - -![Surveyed feature and photos relation setup](./qgis_relation_photos.jpg "Surveyed feature and photos relation setup") - -### Relations widget (gallery) in the form - -Check the **Attributes form** tab in the **Layer Properties** of your survey layer and make sure that the [relation widget](../relations/#attributes-forms-configuration-for-1-n-relations) is included in the form. - -If you use [Drag and Drop Designer](../form-layout/#qgis-drag-and-drop-designer), you may need to add it to the form manually. - -![Photo relation widget in QGIS attributes form](./qgis-form-photo-relation.webp "Photo relation widget in QGIS attributes form") - -The detects the relation widget and allows to add multiple images to one feature, displaying them in a gallery form. -![Many photos to a single feature in Mergin Maps mobile app](./mobile-multiple-photos.jpg "Many photos to a single feature in Mergin Maps mobile app") - +--- +description: Capture photos with Mergin Maps mobile app using photo attachment widget in QGIS. Photos can be stored in a custom folder, resized and renamed automatically. + +outline: deep +--- + +# Photos +[[toc]] + +Adding photos to a surveyed feature can be really helpful. With , you can quickly take photos during the survey, share them with your team and store them in the cloud. You can either capture a photo using your camera or select existing photos from the gallery. + + offers some useful functionalities for capturing photos: +- More than one photo can be attached to one feature. Follow our guide [How to attach multiple photos to features](#how-to-attach-multiple-photos-to-one-feature) to do so. +- Photos can be named automatically based on a [customised names format](#customising-photo-name-format-with-expressions). +- Synchronising photos during the field survey can use up a lot of mobile data, depending on the amount of pictures taken and their size. To reduce the data usage, you may use [selective synchronisation](../../manage/selective_sync/), [resizing pictures automatically](../../gis/features/#photo-quality) or following the [offline field survey workflow](../../field/offline-use/#offline-field-survey-workflow). + +|
Widget
|Preview in the | +|:---:|:---:| +[Single Photo](#photo-attachment-widget-in-qgis) | ![Mergin Maps mobile app attachment field form](../form-widgets/mobile-form-photo-preview2.jpg "Mergin Maps mobile app attachment field form") | +|[ Multiple Photos (Gallery) ](#how-to-attach-multiple-photos-to-one-feature) | ![Mergin Maps mobile app multiple photos attributes form](../form-widgets/mobile-form-multiple-photo-preview.jpg "Mergin Maps mobile app multiple photos attributes form") | + + +:::tip Example projects available +To see the basic [attachment widget](#photo-attachment-widget-in-qgis) setup for photos, clone . + +If you want to [attach multiple photos to one feature](#how-to-attach-multiple-photos-to-one-feature) explore the public project . +::: + +## Photo attachment widget in QGIS + +:::tip Example project available +Clone to follow this example! +::: + +To add photos to features using the , the attributes form of a survey layer needs to have a field with data type `Text (string)` configured with the **Attachment** widget in QGIS as follows: + +To set up the attachment widget: +1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. +2. In the list of **Available Widgets** select the text field you want to work with. +3. In the **Widget Display** tab: + - From the drop-down menu, select **Attachment** + - **Default path** defines where images will be saved. If it is not defined, the project home folder will be used. + - Store the path as **Relative to project path** or **Relative to default path** depending on how you want to store the paths. + + ![QGIS photo attachment widget form](./qgis_form_photo.webp "QGIS photo attachment widget form") + + :::danger Avoid using absolute paths + Using *absolute paths* causes issues when working with your projects on different devices or working in a team: as each device or team member can use different paths, they may be unable to display the images. + ::: + +4. **Apply** the changes. Don't forget to save and sync your project! + +In the , this field will provide two options: +- **Take a picture** to use your camera app for taking a photos +- **From gallery** to attach an existing photo from your device + +![Mergin Maps mobile app photo widget](./mobile-form-attachment-photo.jpg "Mergin Maps mobile app photo widget") + +## Custom folder for storing photos {#how-to-set-up-a-custom-folder-for-storing-photos} +It can be useful to set up a custom folder for photos, e.g. if you want to use [selective synchronisation](../../manage/selective_sync/) or if you simply want to have your data organised. + +To set up a custom folder: +1. Create a subfolder in the project folder (here: `photos`) +2. Open your project in QGIS +3. Open the **Properties** of the survey layer and navigate to the **Attributes form** tab. + + Select the field, where photos are stored (here: `photo`) and make sure that the widget type is set to [**Attachment**](#photo-attachment-widget-in-qgis) + ![QGIS photo attachment widget form](./qgis_form_photo.webp "QGIS photo attachment widget form") + +5. Now we need to change the **Default path** to the folder we have created. Click on the *Data defined override* icon and choose **Edit...** + ![QGIS edit default path expression](./qgis_form_photo_edit_expr.jpg "QGIS edit default path expression") + +6. In **Expression String Builder** enter the expression `@project_folder + '/photos'` (replace `photos` by the name of your folder). Click **OK**. + ![QGIS enter default path expression](./qgis_forms_photo_expression.jpg "QGIS enter default path expression") + +7. The **Default path** now refers to the custom folder. + ![QGIS default path to custom folder](./qgis_custom_folder.jpg "QGIS default path to custom folder") + +8. **Apply the changes**. Don't forget to save and sync your project! + +### Overview of paths for attachment widget + +Here is an overview of paths that can be stored in various settings of the attachment widget. + +| Default path | Store path as | Value | +|:-------------------------: |:------------: |:----------------------------------: | +| - | Relative to project path | `image.jpg` | +| - | Relative to default path | `image.jpg` | +| `@project_folder` | Relative to project path | `image.jpg` | +| `@project_folder` | Relative to default path | `image.jpg` | +| `@project_home + '/photos'` | Relative to project path | `/photos/image.jpg` | +| `@project_home + '/photos'` | Relative to default path | `image.jpg` | + + +## Resizing pictures automatically +Photos that are captured during the field survey or uploaded using can be automatically resized, e.g. to save up storage space. The quality of the photos can be set up in the [ project properties](../../gis/features/#photo-quality) using . + +## Customising photo name format with expressions +Photos taken in the field using can be automatically renamed. This can be useful when browsing pictures in your project and keeping them organised. + +[**How to Set Photo Names Format**](../../gis/photo-names/) will guide you through the setup and provide examples of expressions that can be used to name your photos. + +## Displaying photos in QGIS +Photos taken using during the survey can be displayed in the feature's form in QGIS. + +1. In QGIS, double click on a survey layer to open **Layer Properties** +2. In the **Attributes Form** tab, select the field that contains the path to the photo. + + Scroll to the **Integrated Document Viewer** in the panel on the right. Set the **Type** to *Image*. + ![QGIS Integrated Document Viewer](./qgis-doc-viewer.jpg "QGIS Integrated Document Viewer") + +3. **Apply** the changes and click **OK**. + +Now when you click on a feature that contains a photo, it will be displayed in the form. + +![Mergin Maps mobile app photo displayed in form](./qgis-form-view-photo.jpg "Mergin Maps mobile app photo displayed in form") + +::: details Image preview in QGIS +Some QGIS versions may not display the preview of the image correctly. This issue does not occur in . Therefore we recommend trying the setup by opening the form in the to make sure it works as intended. +::: + + +## Attaching multiple photos to one feature {#how-to-attach-multiple-photos-to-one-feature} + +In some situations, it might be useful to take more than one picture of a feature during the field survey. Attaching multiple photos to one feature is a **one to many relation**. You can read more about this topic in general in [Relations](../relations). + +|
Widget
|Preview in the | +|:---:|:---:| +|Relation - Gallery | ![Mergin Maps mobile app multiple photos attributes form](../form-widgets/mobile-form-multiple-photo-preview.jpg "Mergin Maps mobile app multiple photos attributes form") | + +:::tip Example project available +To see this setup in practice, you can download this public project . +::: + + + +### Non-spatial layer for storing photos +To link multiple photos to a single feature, we need to have a non-spatial layer (table) to store the paths to the photos. + +1. Here we will create a new GeoPackage layer named `photos` with following attributes: + - `photo` with `Text (string)` data type to store the photo path + - `external-pk` with `Text (string)` data type to store the reference to the feature from the survey layer + + ![QGIS creating a non-spatial layer for storing photos](./qgis-create-photos-table.webp "QGIS creating a non-spatial layer for storing photos") + + ::: tip Using default values + You may add other attributes as needed, e.g. to record the username or dates automatically using [default values](../default-values/). + ::: + +2. Now we need to configure the attributes form: set the `photo` field to store photo paths as described in the [photo attachment widget](#photo-attachment-widget-in-qgis). + +### Relation setup +The `photos` layer will be linked to the survey layer using an UUID: the survey layer needs to have a **unique UUID** field generated by the `uuid()` function (see how to set it up [here](../relations/#generating-unique-ids-uuid)) and the [`photos` layer](#non-spatial-layer-for-storing-photos) has a field to store the foreign key (here: `external-pk`). + +:::danger Use UUIDs to link layers +**Do not use the FID field to link these tables**. FIDs can be changed during synchronisation, which can result in having photos linked to the incorrect feature. See [Behind Data Synchronisation](../../manage/synchronisation/) for more details. + +You should always use unique UUIDs generated by the `uuid()` function to link layers as they do not change during the sync. +::: + +Navigate to the [**Relations**](../relations/#setting-up-relation-in-qgis) tab in **Project Properties** and **Add Relation** as follows: +- **Name** is the name of the relation, can be left blank +- **Referenced (parent)** is the spatial layer `Survey` +- **Field 1** of the **Referenced (parent)** is the field `unique-id` that contains the UUID +- **Referencing (child)** is the non-spatial layer `photos` +- **Field 1** of the **Referencing (child)** layer is the `external-pk` that contains the foreign key to link photos with surveyed features. + +![Surveyed feature and photos relation setup](./qgis_relation_photos.jpg "Surveyed feature and photos relation setup") + +### Relations widget (gallery) in the form + +Check the **Attributes form** tab in the **Layer Properties** of your survey layer and make sure that the [relation widget](../relations/#attributes-forms-configuration-for-1-n-relations) is included in the form. + +If you use [Drag and Drop Designer](../form-layout/#qgis-drag-and-drop-designer), you may need to add it to the form manually. + +![Photo relation widget in QGIS attributes form](./qgis-form-photo-relation.webp "Photo relation widget in QGIS attributes form") + +The detects the relation widget and allows to add multiple images to one feature, displaying them in a gallery form. +![Many photos to a single feature in Mergin Maps mobile app](./mobile-multiple-photos.jpg "Many photos to a single feature in Mergin Maps mobile app") + diff --git a/src/layer/photos/qgis_relation_form.jpg b/src/layer/photos/qgis_relation_form.jpg deleted file mode 100644 index 6779bb99..00000000 Binary files a/src/layer/photos/qgis_relation_form.jpg and /dev/null differ diff --git a/src/layer/photos/qgis_relation_form.xcf b/src/layer/photos/qgis_relation_form.xcf deleted file mode 100644 index db21b393..00000000 Binary files a/src/layer/photos/qgis_relation_form.xcf and /dev/null differ diff --git a/src/layer/photos/qgis_relation_tab.jpg b/src/layer/photos/qgis_relation_tab.jpg deleted file mode 100644 index eaacfcf4..00000000 Binary files a/src/layer/photos/qgis_relation_tab.jpg and /dev/null differ diff --git a/src/layer/photos/qgis_relation_tab.xcf b/src/layer/photos/qgis_relation_tab.xcf deleted file mode 100644 index ddfc97ac..00000000 Binary files a/src/layer/photos/qgis_relation_tab.xcf and /dev/null differ diff --git a/src/layer/photos/uuid-default.jpg b/src/layer/photos/uuid-default.jpg deleted file mode 100644 index f9b16777..00000000 Binary files a/src/layer/photos/uuid-default.jpg and /dev/null differ diff --git a/src/layer/photos/uuid-default.xcf b/src/layer/photos/uuid-default.xcf deleted file mode 100644 index 1ce56359..00000000 Binary files a/src/layer/photos/uuid-default.xcf and /dev/null differ diff --git a/src/layer/photos/uuid-field.jpg b/src/layer/photos/uuid-field.jpg deleted file mode 100644 index c1361923..00000000 Binary files a/src/layer/photos/uuid-field.jpg and /dev/null differ diff --git a/src/layer/photos/uuid-field.xcf b/src/layer/photos/uuid-field.xcf deleted file mode 100644 index a98c0275..00000000 Binary files a/src/layer/photos/uuid-field.xcf and /dev/null differ diff --git a/src/layer/qr-code/index.md b/src/layer/qr-code/index.md index 1638b7a2..3c0128f7 100644 --- a/src/layer/qr-code/index.md +++ b/src/layer/qr-code/index.md @@ -1,23 +1,27 @@ -# QR code - -You can scan QR codes with your mobile device to fill in a field in the form. - -|
Widget
|Preview in the | -|:---:|:---:| -[QR code or barcode scanner](#qr-code-setup) | ![Mergin Maps mobile app QR code field form](./mobile-form-qrcode-preview.jpg "Mergin Maps mobile app QR code field form") | - -:::tip Example project available -A QR code field is used in this public project: . Download or clone it to see this setup. -::: - -Prefer a video? Here is a short tutorial about scanning QR codes: - - - -## QR code setup - -To set up the field for QR code scanning, the field name or the field alias has to contain the word `qrcode`. The text is not case sensitive, it can be in combination of lower or upper case letters. - -In the , there will be a QR code icon next to the field. Tap on it to scan the QR code using your camera and the content (a number, text, link, etc.) will be filled in automatically to your field. - -![Mergin Maps mobile app QR code field form](./mobile-form-qrcode.jpg "Mergin Maps mobile app QR code field form") +--- +description: A field in the form can be set up for QR code scanning. Scan QR codes with your mobile device to fill in the values. +--- + +# QR code + +You can scan QR codes with your mobile device to fill in a field in the form. The field data type should match the desired input: if you want to scan, say, a link, you need a field with `Text (string)` data type. + +|
Widget
|Preview in the | +|:---:|:---:| +QR code or barcode scanner | ![Mergin Maps mobile app QR code field form](./mobile-form-qrcode-preview.jpg "Mergin Maps mobile app QR code field form") | + +:::tip Example project available +A QR code field is used in this public project: . Download or clone it to see this setup. +::: + +Prefer a video? Here is a short tutorial about scanning QR codes: + + + +## QR code setup + +To set up the field for QR code scanning, the field name or the field alias has to contain the word `qrcode`. The text is not case sensitive, it can be in combination of lower or upper case letters. + +In the , there will be a QR code icon next to the field. Tap on it to scan the QR code using your camera and the content (a number, text, link, etc.) will be filled in automatically to your field. + +![Mergin Maps mobile app QR code field form](./mobile-form-qrcode.jpg "Mergin Maps mobile app QR code field form") diff --git a/src/layer/relations/index.md b/src/layer/relations/index.md index d936d128..e466dc44 100644 --- a/src/layer/relations/index.md +++ b/src/layer/relations/index.md @@ -1,162 +1,161 @@ ---- -outline: 2,3 ---- - -# Relations -[[toc]] - -There are cases when multiple records from one layer (or table) relate to one feature from another layer, forming one to many (1-N) relation. For instance, there may be multiple photos of one feature, multiple inspections of the same feature or multiple parts, or one feature consisting of multiple polygons with different properties. As these use cases vary, there are different options for how to set up forms for relations. - - to learn more about connecting and editing data across layers. - -|
Widget
|Preview in the | -|:---:|:---:| -| [Relation](../one-to-n-relations/) | ![Mergin Maps mobile app relation form](../form-widgets/mobile-form-relations-preview.jpg "Mergin Maps mobile app relation form") | -|[Relation - Gallery ](../photos/#how-to-attach-multiple-photos-to-one-feature) | ![Mergin Maps mobile app multiple photos attributes form](../form-widgets/mobile-form-multiple-photo-preview.jpg "Mergin Maps mobile app multiple photos attributes form") | -| [Relation reference](#referencing-child-layer-attributes-form-relation-reference-widget) | ![Mergin Maps mobile app relation reference form](./mobile-form-relation-reference-preview.webp "Mergin Maps mobile app relation reference form") | - -:::tip Example projects and guides available -You can take a closer look at 1-N relations: -- Public project contains the setup described on this page as well as sample data -- [How to Link Multiple Records to One Feature](../one-to-n-relations/) explains how to add multiple **records** to a single feature. See also our public project: -- [How to Attach Multiple Photos to Features ](../photos/#how-to-attach-multiple-photos-to-one-feature) shows how to add multiple **photos** to a single feature. See also our public project: -::: - -As an example, we will use a project with two spatial layers: **parks** and **amenities**. One park can have multiple amenities, such as benches, picnic tables, fireplaces or water fountains. Every amenity feature can be located in one park only. Thus, the relation between these layers is one to many (1-*N*): 1 park to *N* amenities. - -This means that **parks** are the referenced (parent) layer and **amenities** are the referencing (child) layer. They will be related based on the *primary keys* of parks and corresponding *foreign keys* of the amenities layer, linking amenities to a specific park. - -*Primary keys* are unique IDs. While all layers have a default ID field when created (`fid`, `id`), these IDs can be changed during synchronisation in , e.g. when multiple surveyors capture new features at the same time (see [Behind data synchronisation](../../manage/synchronisation/#behind-data-synchronisation) for detailed explanation). As a result, child features could end up being linked to a wrong parent feature. - -Therefore, **we strongly recommend creating a new field for primary keys and using UUIDs generated by the `uuid()` function when a feature is created [as described below](#generating-unique-ids-uuid)**. UUID (Universally Unique Identifier) ensures that the primary keys are unique even after synchronisation and that the correct features are linked. - -## One to many relation setup -One to many (1-N) relation needs to be set up in your project in QGIS as follows: -1. [Create unique UUID field](#generating-unique-ids-uuid) for your referenced (parent) layer and a field for storing foreign keys in the referencing (child) layer -3. Define the relation in [Project Properties](#setting-up-relation-in-qgis) -4. [Configure Attributes forms](#attributes-forms-configuration-for-1-n-relations) of both layers as needed - -### Generating unique IDs (UUID) - -:::tip UUID as unique primary keys - (Universally Unique Identifier) is generated to be unique and will not be changed when synced. Therefore, **we strongly recommend using UUID to link layers**. -::: - -To create a field for storing unique UUIDs: - -1. Add a new field with `Text (string)` data type, here: `uuid` - ![Adding new text field](./uuid-field.webp "Adding new text field") - -2. Use the `uuid()` as the [**default value**](../default-values/) for this field in **Layer Properties**. - - This function assigns a unique identifier to every created feature, even when different surveyors create features simultaneously. - ![UUID as default value in Attributes Form](./uuid-default.webp "UUID as default value in Attributes Form") - - **Do not use** the *apply default value on update* option. The generated UUID should not be changed. - -::: tip Field for foreign keys -To create a 1-N relation between two layers, the referencing (child) layer needs to have a field for storing foreign keys. - -This field needs to have the same data type as the primary key: `Text (string)`. Here we will use `fk-uuid`. -::: - - -### Setting up relation in QGIS -Now let's look at the 1-N relation setup in QGIS: -1. From the main menu, select **Projects** > **Properties ...** - ![QGIS menu Project properties](./qgis-project-properties.webp "QGIS menu Project properties") - -2. In the **Relations** tab, click on the **Add Relation** button -![QGIS project properties, Relations tab, Add Relation button](./qgis_relation_tab.webp "QGIS project properties, Relations tab, Add Relation button") - -3. Specify the relation: - - **Id** is generated automatically - - **Name** is the name of the relation, here `park-amenities-relation` - - **Referenced (parent)** is the parks layer, here:`parent-park` - - **Field 1** of the **Referenced (parent)** is the field `uuid` that contains the **unique** UUID created as described [here](#generating-unique-ids-uuid) - - **Referencing (child)** is the amenities layer, here: `child-amenities` - - **Field 1** of the **Referencing (child)** layer is the `fk-uuid`, which acts as a foreign key to link amenities to parks - - ![One to many relation setup in QGIS](./qgis-add-relation.webp "One to many relation setup in QGIS") - -4. Confirm the setup by clicking **OK** - -The one to many relation between **parks** and **amenities** is now set in QGIS. Next we can configure the forms for both layers. - -### Attributes forms configuration for 1-N relations -Attributes form for both linked layers can be set up as needed, depending on the preferred data collection method for the referencing (child) layer: -- Child features can be added through the form of the [referenced (parent) layer](#referenced-parent-layer-attributes-form-relations-widget), meaning you can use the attributes form of the **parks** layer to add/edit/remove **amenities**. -- Child features can be added through the form of the [referencing (child) layer](#referencing-child-layer-attributes-form-relation-reference-widget). A new feature can be added to the **amenities** layer and the link to the corresponding **park** feature is set manually in the attributes form. - -Both options work both in QGIS and in the [](#relation-widgets-in-mergin-maps-mobile-app). - -#### Referenced (parent) layer attributes form - relations widget -Explore the attributes form of the referenced (parent) layer **parks**: -1. Navigate to the **Attributes** form tab in **Layer Properties** -2. Notice the `park-amenities-relation` was automatically added to the list of available widgets as **Relations**. - - If you use [Drag and Drop Designer](../form-layout/#qgis-drag-and-drop-designer), you can add or remove the relation widget from the form manually. - - ![One to many relation setup in QGIS](./qgis-forms-relations-setup.webp "One to many relation setup in QGIS") - -In QGIS, the attributes form looks like this: - -![QGIS attributes form relation](./qgis-form-parent.webp "QGIS attributes form relation") - -Note the editable `park-amenities-relation` with the option to add new (child) features to the **amenities** layer directly from the **parks** form. - - -#### Referencing (child) layer attributes form - relation reference widget -The referencing (child) layer **amenities** can also have the relation added to the attributes form. - -1. Navigate to the **Attributes** form tab in **Layer Properties** -2. Select the foreign key field (here: `fk-uuid`) in the list of fields. - - Choose **Relation Reference** as **Widget Type**: - - **Display expression** sets the display name of referenced layer (here: `name`) - - **Relation** offers all available relations defined in the project (here: `park-amenities-relation`) - - ![QGIS attributes form relation reference setup](./qgis-form-child-setup.webp "QGIS attributes form relation reference setup") - -In QGIS, the attributes form of the referencing (child) **amenities** layer looks like this. The foreign key field `fk-uuid` offers a drop-down menu with the list of features from the referenced (parent) layer **parks**. - -In this case, the link between the amenity feature and the park can be set (or edited) manually. - -![QGIS attributes form relation reference](./qgis-form-child.webp "QGIS attributes form relation reference") - - -## Relation widgets in Mergin Maps mobile app -Now let's look how these relation widgets look like in the . - -:::tip Example project available -[Clone the public project](../../manage/create-project/#clone-a-public-project) to see the setup and sample data on your mobile device. -::: - -There are two ways to add child features to a parent feature in the : using the [relation widget](#relation-widget) on the parent layer or using the [relation reference widget](#relation-reference-widget) on the child layer. - -![Mergin Maps mobile app relation widgets](./mobile-relation-widgets.gif "Mergin Maps mobile app relation widgets") - -### Relation widget - -The referenced (parent) features have the [relation widget](#referenced-parent-layer-attributes-form-relations-widget) in the attributes form. It displays all linked child features in a row. - -Here, **parks** feature `Park B` already contains a link to a `bench` from the **amenities** layer. Tapping on the child feature `bench` opens its attributes form with the option to edit the feature. - -A new child feature can be added by tapping the **+** button: - -![Mergin Maps mobile app relation widget](./mobile-form-relation-widget.webp "Mergin Maps mobile app relation widget") - -- If the referencing (child) layer is a spatial layer, you will be asked to record geometry. Here **amenities** are captured as points. Note that it is not possible to change the [active layer](../../field/mobile-features/#adding-features). -- In the form, you can fill in information about the child feature (here we add a `picnic table`). Note that the relation reference (foreign key `fk-uuid`) is filled in automatically based on the parent feature (here `Park B`). -- Save the changes. The form of the `Park B` feature now displays one more entry in the relation widget (`picnic table`). - -![Mergin Maps mobile app relation widget added child feature](./mobile-form-added-child-feature.webp "Mergin Maps mobile app relation widget added child feature") - -### Relation reference widget -You can also add a new feature to the referencing (child) layer directly: -- Tap the **Add** button and capture the geometry -- Fill in the Attributes form. Note that the [relation reference](#referencing-child-layer-attributes-form-relation-reference-widget) (foreign key, here `fk-uuid`) is empty and needs to be entered manually by choosing a feature from the referenced (parent) layer. -- Save the changes. - -![Mergin Maps mobile app relation widget added child feature](./mobile-add-child-feature.webp "Mergin Maps mobile app relation widget added child feature") - +--- + +description: Do you need to link multiple records to one feature in Mergin Maps? Set up 1-N relations between your layers in QGIS. + +outline: 2,3 +--- + +# Relations + +There are cases when multiple records from one layer (or table) relate to one feature from another layer, forming one to many (1-N) relation. For instance, there may be multiple photos of one feature, multiple inspections of the same feature or multiple parts, or one feature consisting of multiple polygons with different properties. As these use cases vary, there are different options for how to set up forms for relations. + + to learn more about connecting and editing data across layers. + +|
Widget
|Preview in the | +|:---:|:---:| +| View from parent (relation) | ![Mergin Maps mobile app relation form](./mobile-form-relation-preview.webp "Mergin Maps mobile app relation form") | +| View from child (relation reference) | ![Mergin Maps mobile app relation reference form](./mobile-form-relation-reference-preview.webp "Mergin Maps mobile app relation reference form") | + +:::tip Example projects and guides available +You can take a closer look at 1-N relations: +- Public project contains the setup described on this page as well as sample data +- [How to Link Multiple Records to One Feature](../one-to-n-relations/) explains how to add multiple **records** to a single feature. See also our public project: +- [How to Attach Multiple Photos to Features ](../photos/#how-to-attach-multiple-photos-to-one-feature) shows how to add multiple **photos** to a single feature. See also our public project: +::: + +There are two ways to add features with relations in the : using the [relation widget](#referenced-parent-layer-attributes-form-relations-widget) on the parent layer or using the [relation reference widget](#referencing-child-layer-attributes-form-relation-reference-widget) on the child layer: + +![Mergin Maps mobile app relation widgets](./mobile-relation-widgets.gif "Mergin Maps mobile app relation widgets") + +As an example, we will use a project with two spatial layers: **parks** and **amenities**. One park can have multiple amenities, such as benches, picnic tables, fireplaces or water fountains. Every amenity feature can be located in one park only. Thus, the relation between these layers is one to many (1-*N*): one park to many amenities. + +This means that **parks** are the **referenced (parent) layer** and **amenities** are the **referencing (child) layer**. They will be related based on the *primary keys* of parks and corresponding *foreign keys* of the amenities layer, linking amenities to a specific park. + +*Primary keys* are unique IDs. While all layers have a default ID field when created (`fid`, `id`), these IDs can be changed during synchronisation in , e.g. when multiple surveyors capture new features at the same time (see [Behind data synchronisation](../../manage/synchronisation/#behind-data-synchronisation) for detailed explanation). As a result, child features could end up being linked to a wrong parent feature. + +Therefore, **we strongly recommend creating a new field for primary keys and using UUIDs generated by the `uuid()` function when a feature is created [as described below](#generating-unique-ids-uuid)**. UUID (Universally Unique Identifier) ensures that the primary keys are unique even after synchronisation and that the correct features are linked. + +## One to many relation setup overview +One to many (1-N) relation needs to be set up in your project in QGIS as follows: +1. [Create unique UUID field](#generating-unique-ids-uuid) for your referenced (parent) layer and a field for storing foreign keys in the referencing (child) layer +3. Define the relation in [Project Properties](#setting-up-relation-in-qgis) +4. [Configure Attributes forms](#attributes-forms-configuration-for-1-n-relations) of both layers as needed + +## Generating unique IDs (UUID) + +:::tip UUID as unique primary keys + (Universally Unique Identifier) is generated to be unique and will not be changed when synced. Therefore, **we strongly recommend using UUID to link layers**. +::: + +To create a field for storing unique UUIDs: + +1. Add a new field with `Text (string)` data type, here: `uuid` + ![Adding new text field](./uuid-field.webp "Adding new text field") + +2. Use the `uuid()` as the [**default value**](../default-values/) for this field in **Layer Properties**. + + This function assigns a unique identifier to every created feature, even when different surveyors create features simultaneously. + ![UUID as default value in Attributes Form](./uuid-default.webp "UUID as default value in Attributes Form") + + **Do not use** the *apply default value on update* option. The generated UUID should not be changed. + +::: tip Field for foreign keys +To create a 1-N relation between two layers, the referencing (child) layer needs to have a field for storing foreign keys. + +This field needs to have the same data type as the primary key: `Text (string)`. Here we will use `fk-uuid`. +::: + + +## Setting up relation in QGIS +Now let's look at the 1-N relation setup in QGIS: +1. From the main menu, select **Projects** > **Properties ...** + ![QGIS menu Project properties](./qgis-project-properties.webp "QGIS menu Project properties") + +2. In the **Relations** tab, click on the **Add Relation** button +![QGIS project properties, Relations tab, Add Relation button](./qgis_relation_tab.webp "QGIS project properties, Relations tab, Add Relation button") + +3. Specify the relation: + - **Id** is generated automatically + - **Name** is the name of the relation, here `park-amenities-relation` + - **Referenced (parent)** is the parks layer, here:`parent-park` + - **Field 1** of the **Referenced (parent)** is the field `uuid` that contains the **unique** UUID created as described [here](#generating-unique-ids-uuid) + - **Referencing (child)** is the amenities layer, here: `child-amenities` + - **Field 1** of the **Referencing (child)** layer is the `fk-uuid`, which acts as a foreign key to link amenities to parks + + ![One to many relation setup in QGIS](./qgis-add-relation.webp "One to many relation setup in QGIS") + +4. Confirm the setup by clicking **OK** + +The one to many relation between **parks** and **amenities** is now set in QGIS. Next we can configure the forms for both layers. + +## Attributes forms configuration for 1-N relations +Attributes form for both linked layers can be set up as needed, depending on the preferred data collection method for the referencing (child) layer: +- Child features can be added through the form of the [referenced (parent) layer](#referenced-parent-layer-attributes-form-relations-widget), meaning you can use the attributes form of the **parks** layer to add/edit/remove **amenities**. +- Child features can be added through the form of the [referencing (child) layer](#referencing-child-layer-attributes-form-relation-reference-widget). A new feature can be added to the **amenities** layer and the link to the corresponding **park** feature is set manually in the attributes form. + +Both options work both in QGIS and in the . + +### Referenced (parent) layer attributes form - relations widget +Explore the attributes form of the referenced (parent) layer **parks**: +1. Navigate to the **Attributes** form tab in **Layer Properties** +2. Notice the `park-amenities-relation` was automatically added to the list of available widgets as **Relations**. + + If you use [Drag and Drop Designer](../form-layout/#qgis-drag-and-drop-designer), you can add or remove the relation widget from the form manually. + + ![One to many relation setup in QGIS](./qgis-forms-relations-setup.webp "One to many relation setup in QGIS") + +In QGIS, the attributes form looks like this: + +![QGIS attributes form relation](./qgis-form-parent.webp "QGIS attributes form relation") + +Note the editable `park-amenities-relation` with the option to add new (child) features to the **amenities** layer directly from the **parks** form. + +Now look at this form in . The referenced (parent) features have the [relation widget](#referenced-parent-layer-attributes-form-relations-widget) in the attributes form. It displays all linked child features in a row. + +Here, **parks** feature `Park B` already contains a link to a `bench` from the **amenities** layer. Tapping on the child feature `bench` opens its attributes form with the option to edit the feature. + +A new child feature can be added by tapping the **+** button: + +![Mergin Maps mobile app relation widget](./mobile-form-relation-widget.webp "Mergin Maps mobile app relation widget") + +- If the referencing (child) layer is a spatial layer, you will be asked to record geometry. Here **amenities** are captured as points. Note that it is not possible to change the [active layer](../../field/mobile-features/#adding-features). +- In the form, you can fill in information about the child feature (here we add a `picnic table`). Note that the relation reference (foreign key `fk-uuid`) is filled in automatically based on the parent feature (here `Park B`). +- Save the changes. The form of the `Park B` feature now displays one more entry in the relation widget (`picnic table`). + +![Mergin Maps mobile app relation widget added child feature](./mobile-form-added-child-feature.webp "Mergin Maps mobile app relation widget added child feature") + +### Referencing (child) layer attributes form - relation reference widget +The referencing (child) layer **amenities** can also have the relation added to the attributes form. + +1. Navigate to the **Attributes** form tab in **Layer Properties** +2. Select the foreign key field (here: `fk-uuid`) in the list of fields. + + Choose **Relation Reference** as **Widget Type**: + - **Display expression** sets the display name of referenced layer (here: `name`) + - **Relation** offers all available relations defined in the project (here: `park-amenities-relation`) + + ![QGIS attributes form relation reference setup](./qgis-form-child-setup.webp "QGIS attributes form relation reference setup") + +In QGIS, the attributes form of the referencing (child) **amenities** layer looks like this. The foreign key field `fk-uuid` offers a drop-down menu with the list of features from the referenced (parent) layer **parks**. + +In this case, the link between the amenity feature and the park can be set (or edited) manually. + +![QGIS attributes form relation reference](./qgis-form-child.webp "QGIS attributes form relation reference") + +It works the same in the . You can add a new feature to the referencing (child) layer: +- Tap the **Add** button and capture the geometry +- Fill in the Attributes form. Note that the [relation reference](#referencing-child-layer-attributes-form-relation-reference-widget) (foreign key, here `fk-uuid`) is empty and needs to be entered manually by choosing a feature from the referenced (parent) layer. +- Save the changes. + +![Mergin Maps mobile app relation widget added child feature](./mobile-add-child-feature.webp "Mergin Maps mobile app relation widget added child feature") + +## Gallery? +Did you follow these steps and do you see something like this? If the referencing (child) layer is set up with the [Attachment widget](../photos) for photos, the form in the will automatically display a gallery. + +![Many photos to a single feature in Mergin Maps mobile app](../photos/mobile-multiple-photos.jpg "Many photos to a single feature in Mergin Maps mobile app") + +::: tip +To display the [relations widget](#referenced-parent-layer-attributes-form-relations-widget) without the gallery, use `nogallery` in the relation name or label. +::: + +Recommended setup for gallery is explained in [Attaching multiple photos to one feature ](../photos/#how-to-attach-multiple-photos-to-one-feature). diff --git a/src/layer/relations/mobile-1-n-relation.jpg b/src/layer/relations/mobile-1-n-relation.jpg deleted file mode 100644 index 624cda6d..00000000 Binary files a/src/layer/relations/mobile-1-n-relation.jpg and /dev/null differ diff --git a/src/layer/relations/mobile-1-n-relation.xcf b/src/layer/relations/mobile-1-n-relation.xcf deleted file mode 100644 index 0f987e1a..00000000 Binary files a/src/layer/relations/mobile-1-n-relation.xcf and /dev/null differ diff --git a/src/layer/relations/mobile-form-1-n-relation.jpg b/src/layer/relations/mobile-form-1-n-relation.jpg deleted file mode 100644 index bf1af5b0..00000000 Binary files a/src/layer/relations/mobile-form-1-n-relation.jpg and /dev/null differ diff --git a/src/layer/relations/mobile-form-1-n-relation.xcf b/src/layer/relations/mobile-form-1-n-relation.xcf deleted file mode 100644 index 116b8686..00000000 Binary files a/src/layer/relations/mobile-form-1-n-relation.xcf and /dev/null differ diff --git a/src/layer/relations/mobile-form-relation-preview.webp b/src/layer/relations/mobile-form-relation-preview.webp new file mode 100644 index 00000000..74ff4157 Binary files /dev/null and b/src/layer/relations/mobile-form-relation-preview.webp differ diff --git a/src/layer/relations/mobile-form-relation-preview.xcf b/src/layer/relations/mobile-form-relation-preview.xcf new file mode 100644 index 00000000..1fcf403f Binary files /dev/null and b/src/layer/relations/mobile-form-relation-preview.xcf differ diff --git a/src/layer/relations/qgis-1-N-form.jpg b/src/layer/relations/qgis-1-N-form.jpg deleted file mode 100644 index 77b91108..00000000 Binary files a/src/layer/relations/qgis-1-N-form.jpg and /dev/null differ diff --git a/src/layer/relations/qgis-1-N-form.xcf b/src/layer/relations/qgis-1-N-form.xcf deleted file mode 100644 index 8e2ae1b0..00000000 Binary files a/src/layer/relations/qgis-1-N-form.xcf and /dev/null differ diff --git a/src/layer/relations/qgis-forms-relations-setup.jpg b/src/layer/relations/qgis-forms-relations-setup.jpg deleted file mode 100644 index 2952a80c..00000000 Binary files a/src/layer/relations/qgis-forms-relations-setup.jpg and /dev/null differ diff --git a/src/layer/relations/qgis_relation_form.jpg b/src/layer/relations/qgis_relation_form.jpg deleted file mode 100644 index 6779bb99..00000000 Binary files a/src/layer/relations/qgis_relation_form.jpg and /dev/null differ diff --git a/src/layer/relations/qgis_relation_form.xcf b/src/layer/relations/qgis_relation_form.xcf deleted file mode 100644 index db21b393..00000000 Binary files a/src/layer/relations/qgis_relation_form.xcf and /dev/null differ diff --git a/src/layer/relations/qgis_relation_photos.jpg b/src/layer/relations/qgis_relation_photos.jpg deleted file mode 100644 index 1962b940..00000000 Binary files a/src/layer/relations/qgis_relation_photos.jpg and /dev/null differ diff --git a/src/layer/relations/qgis_relation_photos.xcf b/src/layer/relations/qgis_relation_photos.xcf deleted file mode 100644 index 43db54bf..00000000 Binary files a/src/layer/relations/qgis_relation_photos.xcf and /dev/null differ diff --git a/src/layer/relations/qgis_relation_tab.jpg b/src/layer/relations/qgis_relation_tab.jpg deleted file mode 100644 index eaacfcf4..00000000 Binary files a/src/layer/relations/qgis_relation_tab.jpg and /dev/null differ diff --git a/src/layer/tabs-and-groups/index.md b/src/layer/tabs-and-groups/index.md index 02c143db..795fed3d 100644 --- a/src/layer/tabs-and-groups/index.md +++ b/src/layer/tabs-and-groups/index.md @@ -1,25 +1,29 @@ -# Tabs and groups -Using [QGIS Drag and Drop designer](../form-layout/#qgis-drag-and-drop-designer), fields can be arranged into groups and tabs. - -:::tip Example project available -To see an example of tabs and groups, you can clone . -::: - -1. Click on the **+** button to add new group or a tab to the form layout - ![QGIS Drag and drop designer add new group or tab](./qgis-form-layout-add-groups-tabs.jpg "Add new group or tab button") -2. Choose the container type, add a label, and if needed, the number of columns. - - A group can be placed within a tab or another group. - ![QGIS form Add tab](./qgis-add-group-tab.jpg "QGIS form Add tab") - ![QGIS form Add group](./qgis-form-add-group.jpg "QGIS form Add group") - -3. Drag and drop fields to tabs or groups as needed. - -Here we have two tabs, *Data* and *Changelog*. The *Data* tab contains two groups: *roads* and *paths*. -![QGIS form with tabs and groups](./qgis_forms_layout.jpg "QGIS form with tabs and groups") - -The form with tabs and groups will appear in QGIS like this: -![QGIS form layout with tabs and groups](./qgis-form-tabs-groups.jpg "QGIS form layout with tabs and groups") - -And this is how the same form looks like in the : -![Mergin Maps mobile form with tabs and groups](./mobile-forms-layout.jpg "Mergin Maps mobile form with tabs and groups") +--- +description: Using QGIS Drag and Drop designer, fields can be arranged into groups and tabs. +--- + +# Tabs and groups +Using [QGIS Drag and Drop designer](../form-layout/#qgis-drag-and-drop-designer), fields can be arranged into groups and tabs. + +:::tip Example project available +To see an example of tabs and groups, you can clone . +::: + +1. Click on the **+** button to add new group or a tab to the form layout + ![QGIS Drag and drop designer add new group or tab](./qgis-form-layout-add-groups-tabs.jpg "Add new group or tab button") +2. Choose the container type, add a label, and if needed, the number of columns. + + A group can be placed within a tab or another group. + ![QGIS form Add tab](./qgis-add-group-tab.jpg "QGIS form Add tab") + ![QGIS form Add group](./qgis-form-add-group.jpg "QGIS form Add group") + +3. Drag and drop fields to tabs or groups as needed. + +Here we have two tabs, *Data* and *Changelog*. The *Data* tab contains two groups: *roads* and *paths*. +![QGIS form with tabs and groups](./qgis_forms_layout.jpg "QGIS form with tabs and groups") + +The form with tabs and groups will appear in QGIS like this: +![QGIS form layout with tabs and groups](./qgis-form-tabs-groups.jpg "QGIS form layout with tabs and groups") + +And this is how the same form looks like in the : +![Mergin Maps mobile form with tabs and groups](./mobile-forms-layout.jpg "Mergin Maps mobile form with tabs and groups") diff --git a/src/layer/text/index.md b/src/layer/text/index.md index 2eed2e77..b649a5ac 100644 --- a/src/layer/text/index.md +++ b/src/layer/text/index.md @@ -1,46 +1,56 @@ -# Text - -Adding or editing text is the most common method for inserting information within the forms. The **Text Edit** widget can be used for single-line or [multiline](#multiline-text) text inputs for fields with `Text (string)` or `varchar` data types. - -|
Widget
|Preview in the | -|:---:|:---:| -|[Text](#text-widget) | ![Mergin Maps mobile app text field form](./mobile-form-text-preview.jpg "Mergin Maps mobile app text field form") | -|[Multiline Text](#multiline-text) | ![Mergin Maps mobile app text field form](./mobile-form-text-multiline-preview.jpg "Mergin Maps mobile app text field form") | - -:::tip Example project available -Both single-line and multiline text options are used in this public project: . Download or clone it to see this setup. -::: - -Prefer a video? Here is a short tutorial about text widgets: - - -## Text widget -The **Text Edit** widget is set by default for fields with text data type. For simple text input, you do not need to change it. - -![QGIS Text Edit Widget Type](./qgis-form-text.jpg "QGIS Text Edit Widget Type") - -In the , the basic text field looks like this: - -![Mergin Maps mobile app text field form](./mobile-form-text.webp "Mergin Maps mobile app text field form") - - -## Multiline text - -The **Text Edit** widget offers the option to store multiple lines within a single field. -1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. -2. In the list of **Available Widgets** select the field you want to work with (here: `text-multiline`) -3. In the **Widget Type** tab: - - Ensure that **Text Edit** is selected - - Check the **Multiline** option :heavy_check_mark: -4. **Apply** the changes. Don't forget to save and sync your project! - -![QGIS multiline text field setup](./qgis-form-text-multiline.jpg "QGIS multiline text field setup") - -In the , the **multiline text edit widget** looks like this: -![Mergin Maps mobile app multiline text field form](./mobile-form-text-multiline.jpg "Mergin Maps mobile app multiline text field form") - -## Voice input - -In the , the text can be entered manually or using voice-to-text (if your mobile device supports this feature). - -![Using voice to text in Mergin Maps mobile app](./mobile-form-text-voice-input.jpg "Using voice to text in Mergin Maps mobile app") +--- +description: The Text Edit widget can be used for single-line or multiline text inputs. +--- + +# Text + +Adding or editing text is the most common method for inserting information within the forms. The **Text Edit** widget can be used for single-line or [multiline](#multiline-text) text inputs for fields with `Text (string)` or `varchar` data types. + +|
Widget
|Preview in the | +|:---:|:---:| +|[Text](#text-widget) | ![Mergin Maps mobile app text field form](./mobile-form-text-preview.jpg "Mergin Maps mobile app text field form") | +|[Multiline Text](#multiline-text) | ![Mergin Maps mobile app text field form](./mobile-form-text-multiline-preview.jpg "Mergin Maps mobile app text field form") | + +:::tip Example project available +Both single-line and multiline text options are used in this public project: . Download or clone it to see this setup. +::: + +Prefer a video? Here is a short tutorial about text widgets: + + +## Text widget +The **Text Edit** widget is set by default for fields with text data type. For simple text input, you do not need to change it. + +![QGIS Text Edit Widget Type](./qgis-form-text.jpg "QGIS Text Edit Widget Type") + +In the , the basic text field looks like this: + +![Mergin Maps mobile app text field form](./mobile-form-text.webp "Mergin Maps mobile app text field form") + + +## Multiline text + +The **Text Edit** widget offers the option to store multiple lines within a single field. +1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. +2. In the list of **Available Widgets** select the field you want to work with (here: `text-multiline`) +3. In the **Widget Type** tab: + - Ensure that **Text Edit** is selected + - Check the **Multiline** option :heavy_check_mark: +4. **Apply** the changes. Don't forget to save and sync your project! + +![QGIS multiline text field setup](./qgis-form-text-multiline.jpg "QGIS multiline text field setup") + +In the , the **multiline text edit widget** looks like this: +![Mergin Maps mobile app multiline text field form](./mobile-form-text-multiline.jpg "Mergin Maps mobile app multiline text field form") + +::: tip +Both QGIS and support the use of HTML text fields. When setting up the [multiline](#multiline-text) text widget, check also the **HTML** option :heavy_check_mark:. + +HTML text fields can be used to include clickable links to, e.g., [open a link in a browser](../external-link/) or [open a navigation app](../link-to-navigation/) directly from the form in the . +::: + +## Voice input + +In the , the text can be entered manually or using voice-to-text (if your mobile device supports this feature). + +![Using voice to text in Mergin Maps mobile app](./mobile-form-text-voice-input.jpg "Using voice to text in Mergin Maps mobile app") diff --git a/src/layer/use-cases/index.md b/src/layer/use-cases/index.md index 56f9285d..09f2492c 100644 --- a/src/layer/use-cases/index.md +++ b/src/layer/use-cases/index.md @@ -1,5 +1,14 @@ -# Use Cases - -Here you can find some common use cases that can help you deal with specific scenarios. - -Our step-by-step guides provide detailed descriptions accompanied by public projects you can clone and explore in more detail. +--- +description: Our step-by-step guides provide detailed descriptions accompanied by public Mergin Maps projects you can clone and explore in more detail. +--- + +# Use Cases + +Here you can find some common use cases that can help you deal with specific scenarios. + +Our step-by-step guides provide detailed descriptions accompanied by public projects you can clone and explore in more detail: +- [How to Open a File](../open-file/) from within the form using the HTML widget or default values +- [How to Use Hyperlinks](../external-link/) in the form +- [How to Open a Link to a Navigation App](../link-to-navigation/) from within the form +- [How to Link Multiple Records to One Feature](../one-to-n-relations/) +- [How to Embed an Image](../embed-image/) in the form diff --git a/src/layer/use-cases/mobile-1-n-relation.jpg b/src/layer/use-cases/mobile-1-n-relation.jpg deleted file mode 100644 index 624cda6d..00000000 Binary files a/src/layer/use-cases/mobile-1-n-relation.jpg and /dev/null differ diff --git a/src/layer/use-cases/mobile-1-n-relation.xcf b/src/layer/use-cases/mobile-1-n-relation.xcf deleted file mode 100644 index 0f987e1a..00000000 Binary files a/src/layer/use-cases/mobile-1-n-relation.xcf and /dev/null differ diff --git a/src/layer/use-cases/mobile-form-1-n-relation.jpg b/src/layer/use-cases/mobile-form-1-n-relation.jpg deleted file mode 100644 index bf1af5b0..00000000 Binary files a/src/layer/use-cases/mobile-form-1-n-relation.jpg and /dev/null differ diff --git a/src/layer/use-cases/mobile-form-1-n-relation.xcf b/src/layer/use-cases/mobile-form-1-n-relation.xcf deleted file mode 100644 index 116b8686..00000000 Binary files a/src/layer/use-cases/mobile-form-1-n-relation.xcf and /dev/null differ diff --git a/src/layer/use-cases/qgis-1-N-form.jpg b/src/layer/use-cases/qgis-1-N-form.jpg deleted file mode 100644 index 77b91108..00000000 Binary files a/src/layer/use-cases/qgis-1-N-form.jpg and /dev/null differ diff --git a/src/layer/use-cases/qgis-1-N-form.xcf b/src/layer/use-cases/qgis-1-N-form.xcf deleted file mode 100644 index 8e2ae1b0..00000000 Binary files a/src/layer/use-cases/qgis-1-N-form.xcf and /dev/null differ diff --git a/src/layer/use-cases/qgis-add-relation.jpg b/src/layer/use-cases/qgis-add-relation.jpg deleted file mode 100644 index 85e84f76..00000000 Binary files a/src/layer/use-cases/qgis-add-relation.jpg and /dev/null differ diff --git a/src/layer/use-cases/qgis-add-relation.xcf b/src/layer/use-cases/qgis-add-relation.xcf deleted file mode 100644 index 8344ffc7..00000000 Binary files a/src/layer/use-cases/qgis-add-relation.xcf and /dev/null differ diff --git a/src/layer/use-cases/qgis-forms-relations-setup.jpg b/src/layer/use-cases/qgis-forms-relations-setup.jpg deleted file mode 100644 index 2952a80c..00000000 Binary files a/src/layer/use-cases/qgis-forms-relations-setup.jpg and /dev/null differ diff --git a/src/layer/use-cases/qgis-forms-relations-setup.xcf b/src/layer/use-cases/qgis-forms-relations-setup.xcf deleted file mode 100644 index 74258348..00000000 Binary files a/src/layer/use-cases/qgis-forms-relations-setup.xcf and /dev/null differ diff --git a/src/layer/value-select/index.md b/src/layer/value-select/index.md index 45bf15cb..b8ca01c3 100644 --- a/src/layer/value-select/index.md +++ b/src/layer/value-select/index.md @@ -1,137 +1,141 @@ -# Selecting a Single or Multiple Values -[[toc]] - -Selecting values from a drop-down menu is faster than typing them in manually and it also ensures that there are no typos or spelling variations. - -|
Widget
|Preview in the | -|:---:|:---:| -|[Drop-down menu with predefined values](#value-map) |![Mergin Maps mobile app value map field form](./mobile-form-valuemap-preview.jpg "Mergin Maps mobile app value map field form") | -|[Drop-down menu with values from another table, allowed multiple selection](#value-relation) |![Mergin Maps mobile app value relation field form](./mobile-form-value-relation-preview.jpg "Mergin Maps mobile app value relation field form") | - -To select values from a drop-down menu in the form, you can use the [Value Map](#value-map) or [Value Relation](#value-relation) widgets in QGIS. Additionally, it is possible to create [drill-down (cascade) forms](#drill-down-forms), where a value selected in one field can affect the options available in another field. - -The **Value Relation** widget is a bit more complex as it uses another layer (usually a non-spatial table) as a source of values. However, it provides some benefits when compared to the simpler **Value Map** setup, such as: -- Option to select multiple values from the list (in this case, the field needs to be of `text` data type). -- The table used for the drop-down menu can be edited in the . For example, if there is a value missing, you can [create it](../../field/mobile-features/#add-or-edit-non-spatial-features) during the field survey and use it immediately. The *Value Map* options can be managed only through QGIS. -- Searching the values: if you have a large list of values, it will become cumbersome to find the right value. With the *Value Relation* widget, you have the option to search for values in the list in the . - -:::tip Example projects available -The public project contains both *Value Map* and *Value relation* widgets. Download or clone it to see the setup. - -*Drill-down forms* are included in public project. -::: - - -## Value Map - -Value map widget is used to select a value from a drop-down menu. Values are defined in the widget in layer properties in QGIS. They cannot be changed or added from the . Only one value can be selected. - -If you want to use multiple selections in a field or need to add new values during the survey, check out the [Value Relation](#value-relation) widget. - -:::tip Example project available -This public project contains a Value Map field. Download or clone it to see the setup. -::: - -Prefer a video? Here is a short tutorial about using Value Map widget: - - -1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. -2. In the list of **Available Widgets** select the field you want to work with (here: `valuemap`) -3. In the **Widget Type** tab, select the **Value Map** option from the drop-down menu and fill in the table below. - **Value** is what will be stored in the field (these can be coded values or shortened names, here we use `1`, `2`, `3`). **Description** is what will be displayed in the form and in the attributes table (here: `value 1`, `value 2`, `value 3`). -4. **Apply** the changes. Don't forget to save and sync your project! - -![QGIS value map field form](./qgis-form-valuemap.jpg "QGIS value map field form") - -Now you can select the value from a drop-down menu in the : -![Mergin Maps mobile app value map field form](./mobile-form-valuemap.jpg "Mergin Maps mobile app value map field form") - - -## Value Relation - -The **Value Relation** widget is similar to the [Value Map](#value-map) widget, but the values for the drop-down menu come from another layer (usually a non-spatial table). - -:::tip Example project available -This public project contains a Value Relation setup. Download or clone it to explore it in more detail. -::: - -Prefer a video? Here is a short tutorial about using Value relations: - - -To have the option to safely add new values when working collaboratively, the value table should have a unique field with UUID values. This field should use the `uuid()` function as a [default value](../default-values/#examples-of-useful-default-values), so that every new entry has its UUID. - -To set up **Value Relation** in QGIS: - -1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. -2. In the list of **Available Widgets** select the field you want to work with (here: `value-relation-multi-select`) -3. In the **Widget Type** tab, select **Value Relation** from the drop-down menu and set it up as follows: - - Select the **Layer** that contains the values (here: `value-relation-table`) - - **Key column** is the field that contains the values (here: `uuid`) - - **Value column** is the field that contains the alias (description) of the value (here: `value`) - - Check the **Allow multiple selections** option :heavy_check_mark: if you want to have the option to select multiple values -4. **Apply** the changes. Don't forget to save and sync your project! - -![QGIS value relation field form](./qgis-form-value-relation-multiselect.jpg "QGIS value relation field form") - -:::danger Using UUID as key field -**Why UUID?** FID can be changed during [synchronisation](../../manage/synchronisation/). If multiple surveyors add new entries to the value table, features can end up with wrong values. - -On the other hand, (Universally Unique Identifier) is guaranteed to be unique and will not be changed when synced. Therefore, we recommend using UUID if you want to add new values during the survey. -::: - -When you open the field with **Value Relation** in the , you will be able to select a value or multiple values from the list. - -![Mergin Maps mobile app value relation multiple selection](./mobile-form-value-relation.jpg "Mergin Maps mobile app value relation multiple selection") - -## Drill-down forms -Drill-down or cascade forms enable to list values in a field depending on a value selected in another field. - -:::tip Example project available -Clone to explore drill-down forms. -::: - -Prefer a video? Here is a short tutorial about drill-down forms: - - -### How to set up drill-down forms -Here, we have a layer named `landuse` that has fields such as *Land use*, *Type*, *Plant type*. Values that can be filled in these fields depend on the previous choices: if we select `Farmland` as the *Land use*, the *Type* field drop-down menu offers options such as `Cereals`, `Oil plants` or `Vegetables`. Subsequently, the *Plant type* field has only options that are relevant for the selected type of land use. - -![QGIS drill-down form](./qgis-drill-down-form.gif "QGIS drill-down form") - -First, let us explore the structure of value tables that are used to set up drill-down forms. In the example project, *Land use* field uses `plant-habitat` value table that has following fields: - -![QGIS category value table](./qgis-table-habitat.jpg "QGIS category value table") - -The *Type* field refers to the `plant-type` value table. In this table, there is a field `habitat-code` that refers to a specific `code` value from the `plant-habitat` table. -For instance, the `FAR` habitat code (standing for *Farmland*) is used as the `habitat-code` for *Cereals, Vegetables, Oil plants* as these are applicable farmland types. - -![QGIS type value table](./qgis-table-type.jpg "QGIS type value table") - -Similarly, the *Plant type* field uses the `plant-sub-type` value table that contains a `Code` field that refers to specific types from the `plant-type` table. -For instance, the `CER` type code is applied for *Wheat, Rye, Barley, Maize*, meaning these types of plants belong to the *Cereals* category. - -![QGIS subtype value table](./qgis-table-subtype.jpg "QGIS subtype value table") - -To set up drill-down forms: -1. Right-click on a survey layer, select **Properties** and go to the **Attributes form** tab -2. The `habitat` field aliased as *Land use* is set up using the **Value relation** widget. Values are defined in the `plant-habitat` table: - - **Key column** is the field that contains the values (here: `code`) - - **Value column** is the field that contains the alias (description) of the value (here: `desc`) - - ![QGIS form value relation](./qgis-form-value-relation.jpg "QGIS form value relation") - -3. The `type` field (aliased as *Type*) uses the **Value relation** widget with values from the `plant-type` table: - - **Key column** is the field that contains the values (here: `Code`) - - **Value column** is the field that contains the alias (description) of the value (here: `Description`) - - **Filter expression**: `"habitat-code"= current_value('habitat')` is used to limit the options in the drop-down menu to values where the `habitat-code` of the value is the same as the current value of the `habitat` field. - ![QGIS form value relation filter expression](./qgis-form-value-relation-expression.jpg "QGIS form value relation filter expression") - -4. Likewise, the `subtype` field (aliased as *Plant type*) uses the **Value relation** widget with values defined in the `plant-sub-type` table: - - **Key column** is the field that contains the values (here: `id`) - - **Value column** is the field that contains the alias (description) of the value (here: `Species`) - - **Filter expression**: `"Code" = current_value('type')` - ![QGIS form value relation filter expression](./qgis-form-value-relation-expression-subtype.jpg "QGIS form value relation filter expression") - -And this is how the drill-down form looks in the . After selecting *Land use: Farmland*, the *Type* field only offers values `Cereals`, `Oil plants` or `Vegetables`. After selecting `Cereals`, the *Plant type* offers only relevant options such as `Wheat`, `Rye` or `Barley`. - -![Mergin Maps mobile app drill-down form](./mobile-drill-down-form.gif "Mergin Maps mobile app drill-down form") +--- +description: To select values from a drop-down menu in the form in Mergin Maps mobile app, you can use the Value Map or Value Relation widgets. +--- + +# Selecting Single or Multiple Values +[[toc]] + +Selecting values from a drop-down menu is faster than typing them in manually and it also ensures that there are no typos or spelling variations. Additionally, it is possible to create [drill-down (cascade) forms](#drill-down-forms), where a value selected in one field can affect the options available in another field. + +|
Widget
|Preview in the | +|:---:|:---:| +|[Drop-down menu with predefined values](#value-map) |![Mergin Maps mobile app value map field form](./mobile-form-valuemap-preview.jpg "Mergin Maps mobile app value map field form") | +|[Drop-down menu with values from another table, allowed multiple selection](#value-relation) |![Mergin Maps mobile app value relation field form](./mobile-form-value-relation-preview.jpg "Mergin Maps mobile app value relation field form") | + +To select values from a drop-down menu in the form, you can use the Value Map or Value Relation widgets in QGIS. The field data type depends on the values that should be stored in the field, usually `Text (string)` or `Integer`. To [allow multiple selection](#value-relation), the field needs to be of `Text (string)` data type). + +The **Value Relation** widget is a bit more complex as it uses another layer (usually a non-spatial table) as a source of values. However, it provides some benefits when compared to the simpler **Value Map** setup, such as: +- Option to select multiple values from the list +- The table used for the drop-down menu can be edited in the . For example, if there is a value missing, you can [create it](../../field/mobile-features/#add-or-edit-non-spatial-features) during the field survey and use it immediately. The *Value Map* options can be managed only through QGIS. +- Searching the values: if you have a large list of values, it will become cumbersome to find the right value. With the *Value Relation* widget, you have the option to search for values in the list in the . + +:::tip Example projects available +The public project contains both *Value Map* and *Value relation* widgets. Download or clone it to see the setup. + +*Drill-down forms* are included in public project. +::: + + +## Value Map + +Value map widget is used to select a value from a drop-down menu. Values are defined in the widget in layer properties in QGIS. They cannot be changed or added from the . Only one value can be selected. + +If you want to use multiple selections in a field or need to add new values during the survey, check out the [Value Relation](#value-relation) widget. + +:::tip Example project available +This public project contains a Value Map field. Download or clone it to see the setup. +::: + +Prefer a video? Here is a short tutorial about using Value Map widget: + + +1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. +2. In the list of **Available Widgets** select the field you want to work with (here: `valuemap`) +3. In the **Widget Type** tab, select the **Value Map** option from the drop-down menu and fill in the table below. + **Value** is what will be stored in the field (these can be coded values or shortened names, here we use `1`, `2`, `3`). **Description** is what will be displayed in the form and in the attributes table (here: `value 1`, `value 2`, `value 3`). +4. **Apply** the changes. Don't forget to save and sync your project! + +![QGIS value map field form](./qgis-form-valuemap.jpg "QGIS value map field form") + +Now you can select the value from a drop-down menu in the : +![Mergin Maps mobile app value map field form](./mobile-form-valuemap.jpg "Mergin Maps mobile app value map field form") + + +## Value Relation + +The **Value Relation** widget is similar to the [Value Map](#value-map) widget, but the values for the drop-down menu come from another layer (usually a non-spatial table). + +:::tip Example project available +This public project contains a Value Relation setup. Download or clone it to explore it in more detail. +::: + +Prefer a video? Here is a short tutorial about using Value relations: + + +To have the option to safely add new values when working collaboratively, the value table should have a unique field with UUID values. This field should use the `uuid()` function as a [default value](../default-values/#examples-of-useful-default-values), so that every new entry has its UUID. + +To set up **Value Relation** in QGIS: + +1. Right-click on a layer, select **Properties** and go to the **Attributes form** tab. +2. In the list of **Available Widgets** select the field you want to work with (here: `value-relation-multi-select`) +3. In the **Widget Type** tab, select **Value Relation** from the drop-down menu and set it up as follows: + - Select the **Layer** that contains the values (here: `value-relation-table`) + - **Key column** is the field that contains the values (here: `uuid`) + - **Value column** is the field that contains the alias (description) of the value (here: `value`) + - Check the **Allow multiple selections** option :heavy_check_mark: if you want to have the option to select multiple values +4. **Apply** the changes. Don't forget to save and sync your project! + +![QGIS value relation field form](./qgis-form-value-relation-multiselect.jpg "QGIS value relation field form") + +:::danger Using UUID as key field +**Why UUID?** FID can be changed during [synchronisation](../../manage/synchronisation/). If multiple surveyors add new entries to the value table, features can end up with wrong values. + +On the other hand, (Universally Unique Identifier) is guaranteed to be unique and will not be changed when synced. Therefore, we recommend using UUID if you want to add new values during the survey. +::: + +When you open the field with **Value Relation** in the , you will be able to select a value or multiple values from the list. + +![Mergin Maps mobile app value relation multiple selection](./mobile-form-value-relation.jpg "Mergin Maps mobile app value relation multiple selection") + +## Drill-down forms +Drill-down or cascade forms enable to list values in a field depending on a value selected in another field. + +:::tip Example project available +Clone to explore drill-down forms. +::: + +Prefer a video? Here is a short tutorial about drill-down forms: + + +### How to set up drill-down forms +Here, we have a layer named `landuse` that has fields such as *Land use*, *Type*, *Plant type*. Values that can be filled in these fields depend on the previous choices: if we select `Farmland` as the *Land use*, the *Type* field drop-down menu offers options such as `Cereals`, `Oil plants` or `Vegetables`. Subsequently, the *Plant type* field has only options that are relevant for the selected type of land use. + +![QGIS drill-down form](./qgis-drill-down-form.gif "QGIS drill-down form") + +First, let us explore the structure of value tables that are used to set up drill-down forms. In the example project, *Land use* field uses `plant-habitat` value table that has following fields: + +![QGIS category value table](./qgis-table-habitat.jpg "QGIS category value table") + +The *Type* field refers to the `plant-type` value table. In this table, there is a field `habitat-code` that refers to a specific `code` value from the `plant-habitat` table. +For instance, the `FAR` habitat code (standing for *Farmland*) is used as the `habitat-code` for *Cereals, Vegetables, Oil plants* as these are applicable farmland types. + +![QGIS type value table](./qgis-table-type.jpg "QGIS type value table") + +Similarly, the *Plant type* field uses the `plant-sub-type` value table that contains a `Code` field that refers to specific types from the `plant-type` table. +For instance, the `CER` type code is applied for *Wheat, Rye, Barley, Maize*, meaning these types of plants belong to the *Cereals* category. + +![QGIS subtype value table](./qgis-table-subtype.jpg "QGIS subtype value table") + +To set up drill-down forms: +1. Right-click on a survey layer, select **Properties** and go to the **Attributes form** tab +2. The `habitat` field aliased as *Land use* is set up using the **Value relation** widget. Values are defined in the `plant-habitat` table: + - **Key column** is the field that contains the values (here: `code`) + - **Value column** is the field that contains the alias (description) of the value (here: `desc`) + + ![QGIS form value relation](./qgis-form-value-relation.jpg "QGIS form value relation") + +3. The `type` field (aliased as *Type*) uses the **Value relation** widget with values from the `plant-type` table: + - **Key column** is the field that contains the values (here: `Code`) + - **Value column** is the field that contains the alias (description) of the value (here: `Description`) + - **Filter expression**: `"habitat-code"= current_value('habitat')` is used to limit the options in the drop-down menu to values where the `habitat-code` of the value is the same as the current value of the `habitat` field. + ![QGIS form value relation filter expression](./qgis-form-value-relation-expression.jpg "QGIS form value relation filter expression") + +4. Likewise, the `subtype` field (aliased as *Plant type*) uses the **Value relation** widget with values defined in the `plant-sub-type` table: + - **Key column** is the field that contains the values (here: `id`) + - **Value column** is the field that contains the alias (description) of the value (here: `Species`) + - **Filter expression**: `"Code" = current_value('type')` + ![QGIS form value relation filter expression](./qgis-form-value-relation-expression-subtype.jpg "QGIS form value relation filter expression") + +And this is how the drill-down form looks in the . After selecting *Land use: Farmland*, the *Type* field only offers values `Cereals`, `Oil plants` or `Vegetables`. After selecting `Cereals`, the *Plant type* offers only relevant options such as `Wheat`, `Rye` or `Barley`. + +![Mergin Maps mobile app drill-down form](./mobile-drill-down-form.gif "Mergin Maps mobile app drill-down form") diff --git a/src/layer/extra-variables/index.md b/src/layer/variables/index.md similarity index 56% rename from src/layer/extra-variables/index.md rename to src/layer/variables/index.md index 050586c3..1fca3d9d 100644 --- a/src/layer/extra-variables/index.md +++ b/src/layer/variables/index.md @@ -1,65 +1,76 @@ -# Extra Variables - -There are some useful variables that can be used as [default values](../default-values/). - -Here you can find the lists of: -- [extra QGIS variables](#extra-qgis-variables) introduced by that can be used to record information related to workspace, project or users -- [extra position variables](#extra-position-variables) that can be used to record GPS information - -## Extra QGIS variables - -The adds several variables that can be used in QGIS expressions: - -| 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_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 | -| `@mergin_project_full_name` | `martin/Tree survey` | project | Owner and project name joined with a forward slash | -| `@mergin_project_version` | `42` | project | Current version of the active project | - -A common use case is to use `@mergin_username` as the [default value](../default-values/) for one of the fields in a survey layer to automatically track who has added (and/or modified) a particular record. - -## Extra Position Variables - -With , it is possible to access GPS information using extra position variables. Note that location permission has to be allowed and location service enabled. - -Extra position variables can be used as [default values in feature forms](../default-values/). - -Following variables are supported: - - `@position_coordinate` - A point with the coordinates in WGS84. - - `@position_latitude` - Latitude - - `@position_longitude` - Longitude - - `@position_altitude` - Altitude - - `@position_direction` - The bearing measured in degrees clockwise from true north to the direction of travel. - - `@position_ground_speed` - The ground speed, in meters/sec. - - `@position_vertical_speed` - The vertical speed, in meters/sec. - - `@position_magnetic_variation` - The angle between the horizontal component of the magnetic field and true north, in degrees. Also known as magnetic declination. A positive value indicates a clockwise direction from true north and a negative value indicates a counter-clockwise direction. - - `@position_horizontal_accuracy` - The accuracy of the provided latitude-longitude value, in meters. - - `@position_vertical_accuracy` - The accuracy of the provided altitude value, in meters. - - `@position_from_gps` - True, if recorder/edited feature's geometry correspond with current user's position (Position marker has the same location as the crosshairs marker). - - `@position_satellites_visible` - Number of visible satellites. - - `@position_satellites_used` - Number of satellites used to calculate the position. - - `@position_gps_fix` - GPS fix, e.g. "RTK float" - - `@position_gps_antenna_height` - Antenna height as defined in [GPS settings](../../field/mobile-app-ui/#gps-settings) - - `@position_provider_type` - GPS device type. - - for internal GPS, returns "internal" - - for external GPS, returns "external" - - `@position_provider_name` - GPS device name. - - for internal GPS, returns "Internal" - - for external GPS, returns the name of the external device - - `@position_provider_address` - GPS device address. - - for internal GPS, returns "" - - for external GPS, returns the MAC address - - `@position_hdop` - Horizontal dilution of precision (HDOP) - - `@position_vdop` - Vertical dilution of precision (VDOP) - - `@position_pdop` - Position (3D) dilution of precision (PDOP) - -:::tip -**Dilution of precision** (DOP) is a useful value that reflects the confidence level of achieved position precision. In addition to the horizontal and vertical accuracy, the appropriate DOP value (horizontal, vertical, or 3D) can be used to assess the overall quality of your survey accuracy. - -You can read more about this topic e.g. on [Wikipedia](https://en.wikipedia.org/wiki/Dilution_of_precision_(navigation)). -::: - +--- +description: Mergin Maps variables (username, user email or project name) or GPS position variables can be used in QGIS expressions and as default values in forms. +--- + +# Variables + +There are some useful variables that can be used as [default values](../default-values/). + +Here you can find the lists of: +- [project and user variables](#project-and-user-variables) introduced by that can be used to record information related to workspace, project or users +- [position variables](#position-variables) that can be used to record GPS information + +## Project and user variables + + +The adds several variables that can be used in QGIS expressions: + +| Variable name | Sample value | Scope | Description | +|-----------------------------|-------------------------------|---------|------------- +| `@mm_full_name` | `martin second name` | global | Full name of the currently logged in user, blank if the full name is not set | +| `@mm_username` | `martin` | global | Username of the user currently logged in to | +| `@mm_user_email` | `martin@example.com` | global | Email of the user currently logged in to | +| `@mm_url` | `https://app.merginmaps.com` | global | URL of the service | +| `@mm_project_name` | `Tree survey` | project | Name of the active project | +| `@mm_project_full_name` | `martin/Tree survey` | project | Workspace and project name joined with a forward slash | +| `@mm_project_version` | `42` | project | Current version of the active project | + +A common use case is to use `@mm_username` or `@mm_user_email` as the [default value](../default-values/) for one of the fields in a survey layer to automatically track who has added (and/or modified) a particular record. + +::: tip `mergin_` variable names still work! +QGIS variables listed here previously used the prefix `mergin_`. Now we use the prefix `mm_` standing for . + +Both naming options are functional and will continue to work in the future: `@mergin_user_email` and `@mm_user_email` provide the same value when used in QGIS expressions. +::: + +## Position Variables + +With , it is possible to access GPS information using extra position variables. Note that location permission has to be allowed and location service enabled. + +Extra position variables can be used as [default values in feature forms](../default-values/). + +Following variables are supported: + - `@position_coordinate` - A point with the coordinates in WGS84. + - `@position_latitude` - Latitude + - `@position_longitude` - Longitude + - `@position_altitude` - Altitude + - `@position_direction` - The bearing measured in degrees clockwise from true north to the direction of travel. + - `@position_ground_speed` - The ground speed, in meters/sec. + - `@position_vertical_speed` - The vertical speed, in meters/sec. + - `@position_magnetic_variation` - The angle between the horizontal component of the magnetic field and true north, in degrees. Also known as magnetic declination. A positive value indicates a clockwise direction from true north and a negative value indicates a counter-clockwise direction. + - `@position_horizontal_accuracy` - The accuracy of the provided latitude-longitude value, in meters. + - `@position_vertical_accuracy` - The accuracy of the provided altitude value, in meters. + - `@position_from_gps` - True, if recorded/edited feature's geometry corresponds with current user's position (Position marker has the same location as the crosshairs marker). + - `@position_satellites_visible` - Number of visible satellites. + - `@position_satellites_used` - Number of satellites used to calculate the position. + - `@position_gps_fix` - GPS fix, e.g. "RTK float" + - `@position_gps_antenna_height` - Antenna height as defined in [GPS settings](../../field/mobile-app-ui/#gps-settings) + - `@position_provider_type` - GPS device type. + - for internal GPS, returns "internal" + - for external GPS, returns "external" + - `@position_provider_name` - GPS device name. + - for internal GPS, returns "Internal" + - for external GPS, returns the name of the external device + - `@position_provider_address` - GPS device address. + - for internal GPS, returns "" + - for external GPS, returns the MAC address + - `@position_hdop` - Horizontal dilution of precision (HDOP) + - `@position_vdop` - Vertical dilution of precision (VDOP) + - `@position_pdop` - Position (3D) dilution of precision (PDOP) + +:::tip +**Dilution of precision** (DOP) is a useful value that reflects the confidence level of achieved position precision. In addition to the horizontal and vertical accuracy, the appropriate DOP value (horizontal, vertical, or 3D) can be used to assess the overall quality of your survey accuracy. + +You can read more about this topic e.g. on [Wikipedia](https://en.wikipedia.org/wiki/Dilution_of_precision_(navigation)). +::: +