relations

Author: alex-cit

src/layer/relations/index.md

@@ -6,17 +6,15 @@ 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.
 
 <QGISHelp ver="latest" link="/user_manual/working_with_vector/joins_relations.html" text="See QGIS Documentation" /> to learn more about connecting and editing data across layers.
 
 |<div style="width:150px"> Widget </div> |Preview in the <MobileAppNameShort />|
 |:---:|:---:|
-| [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")  |
+| 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:
@@ -25,21 +23,25 @@ You can take a closer look at 1-N relations:
 - [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: <MerginMapsProject id="documentation/forms_multiple_photos" />
 :::
 
-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. 
+There are two ways to add features with relations in the <MobileAppNameShort />: using the [relation widget](#relation-widget) on the parent layer or using the [relation reference widget](#relation-reference-widget) on the child layer:
 
-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.
+![Mergin Maps mobile app relation widgets](./mobile-relation-widgets.gif "Mergin Maps mobile app relation widgets")
+
+As an example, we will use a project <MerginMapsProject id="documentation/forms-relations" /> 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 <MainPlatformName />, 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 relation setup overview
 One to many (1-N) relation needs to be set up in your <MainPlatformName /> 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)
+## Generating unique IDs (UUID)
 
 :::tip UUID as unique primary keys
 <QGISHelp ver="latest" link="user_manual/expressions/functions_list.html#uuid" text="UUID" /> (Universally Unique Identifier) is generated to be unique and will not be changed when synced. Therefore, **we strongly recommend using UUID to link layers**.
@@ -64,7 +66,7 @@ This field needs to have the same data type as the primary key: `Text (string)`.
 :::
 
 
-### Setting up relation in QGIS
+## 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")
@@ -86,14 +88,14 @@ Now let's look at the 1-N relation setup in QGIS:
 
 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 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 [<MobileAppNameShort />](#relation-widgets-in-mergin-maps-mobile-app).
 
-#### Referenced (parent) layer attributes form - relations widget
+### 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**.
@@ -108,8 +110,21 @@ In QGIS, the attributes form looks like this:
 
 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 <MobileAppName/>. 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
+### 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**
@@ -127,39 +142,20 @@ In this case, the link between the amenity feature and the park can be set (or e
 
 ![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 <MobileAppNameShort />. 
-
-:::tip Example project available
-[Clone the public project](../../manage/create-project/#clone-a-public-project) <MerginMapsProject id="documentation/forms-relations" /> 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 <MobileAppNameShort />: 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:
+It works the same in the <MobileAppName/>. 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 <MobileAppNameShort/> 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 ](#attaching-multiple-photos-to-one-feature).