The original version of this document is located at https://docs.qfield.org/how-to/attributes-form
QField creates forms similar to, but not equal to QGIS.
The field widgets from QGIS are supported on a best effort basis and optimized for the mobile use.
Widget type | Support | Notes |
---|---|---|
Text Edit | ✅ | - HTML is not supported - Numerical input is enforced based on the type. |
Check Box | ✅ | |
Value Map | ✅ | |
Hidden | ✅ | |
Attachment | ✅ | This field is combined with camera integration. It is also able to open other files like pdf and doc (if you have an appropriate viewer) Attachment (photo settings) |
Date Time | ✅ | |
Range | ✅ | |
Relation Reference | ✅ | |
Relation Widget | ✅ | |
Value Relation | ✅ | |
UUID Generator | ✅ | |
QML / HTML Widget | ✅ | |
Others | ❌ | Funding |
The editable flag of fields is respected.
QField offers a much more fine-grained control over the last used values
and ignores the QGIS setting.
The setting suppress attribute form is directly applied to the
QField form.
Groups and Tabs from Drag and Drop designer forms are supported.
In the “Attributes Form,” you can structure your forms using various containers, such as tabs and groups, and enhance interactivity by incorporating expression-based conditional visibility. By enabling the Drag and Drop Designer, you gain the flexibility to re-order attribute fields, as well as gaining access to widgets that are not directly tied to specific fields (e.g., HTML/QML widgets).
🖥️ Desktop preparation
For more information refer to the relations chapter of the official
QGIS Documentation.
The relation widget shows all the referencing child features in a list.
It is possible to add, delete and open them.
The visual identification of the list entries are done via the Display Expression of the child layer.
Since the parents primary keys are used as foreign keys on the
referencing child features, these primary keys must be save to use even
after the synchronization back to the original data. Therefore we
recommend to use stable values such as UUIDs for primary keys.
It is possible to already add children from a parent that is about to be
added. This possibility will be blocked if there is no valid primary key
on the parent or the constraints are violated. In case the adding of the
parent feature is canceled after some children have been added already,
the children are deleted as well.
On many-to-many relationships, according to the cardinality setting in
the QGIS Vector Layer Properties, on adding, deleting or opening an
entry in the list effects directly the child layer (on direct
cardinality) or the linking table (on many-to-one cardinality).
The second case is usually used when there are additional relation
information (e.g. percentage) in the linking table.
In case of the many-to-one cardinality on many-to-many relations the
Display Expression needs to be set on the linking table.
The Ordered Relation Editor widget allows you to reorder linked child features in a relation editor widget based on a specific ordering field.
Make sure you have installed the Ordered Relation Editor plugin from the official repository or through the “Plugin Manager” in QGIS.
Navigate to the Attributes Form section of your layer settings and set the layout editor to Drag and Drop Designer.
In the Relation widget type dropdown, select Ordered Relation Editor. Then, configure the widget using the following settings:
Ordering Field: Specify the field in the child layer that will be used to determine the order of the features.
Description: Define an expression to display descriptive text for each child feature in the list.
Image Path (Optional): Provide a path to an image or icon to visually enhance the list. This is an expression that resolves dynamically.
To enhance the user experience within QField, it is possible to control the item threshold at which point the value map editor widgets switch to a toggle buttons interface.
This feature allows users to quickly access items in QField when there are few and providing a more intuitive interface when dealing with a large number of items.
Open Layer Properties by right-clicking on the desired layer and selecting ‘Properties’ from the context menu.
Navigate to the QField tab located within the Layer Properties dialog.
Here, you will find an option to specify the quantity of items that will trigger the transition to a toggle button interface.
Enter the preferred threshold value according to your needs.
🖥️ Desktop preparation
The widget type Attachment is used with fields that store the path
to files.
It can be used to:
The path should be set to relative. The pictures, audios, videos, pdf and docs are
stored then in a sub-directory of the project, where the link stored in
the textfield is pointing to.
Note
QGIS 3.30 or newer is required for the audio and video functionality
In QField the attachments are displayed. By clicking the icons symbol the camera or audio record is started to update the pictures, videos or audios with a new media.
On synchronization the sub-directory with the pictures, videos audios, pdf and docs has to be copied as well.
The option hyperlink on the attachment widget will disable the
camera functionality and enable a hyperlink to open a document (pdf,
doc, ...).
🖥️ Desktop preparation
QFieldSync provides the possibility to configure the path of attachments.
Use expressions to specify the path of the attachments. By default, pictures are saved into the “DCIM” folder, audio recordings are saved into the “audio” folder and videos are saved into “video” with a timestamp as name.
🖥️ Desktop preparation
The widget Value Relation offers values from a related table in a
combobox. You can select layer, key column and value column. Several
options are available to change the standard behaviors: allow null value, order by value and allow multiple selections. The widget will
display a drop-down or multiple-select list of the referenced features.
🖥️ Desktop preparation
Groups can be hidden based on an expression. This is useful when certain
attributes are only required under certain conditions. As an example
imagine mapping trees. Some of them might have a disease and you have a
list of possible deseases. To not clutter the form with many fields,
make a group and configure a visibility expression for a group
“diseases”. Add a field “desease” with a checkbox. Only when the
checkbox is checked, the list of diseases will be available to you.
Let’s see what we got on the field:
🖥️ Desktop preparation
Attribute fields can have constraints attached. Constraints are
expressions that needs to evaluate to True
(or 1
) in order to be
able to save the form. Constraints are configured on a per-field basis
and a description can be added that will be shown if a
constraint is not satisfied.
You cannot enter an elevation value higher than the highest mountain in
this country.
sql
"elevation" < 5000
It is required to fill in an identifier.
sql
"identifier" IS NOT NULL
🖥️ Desktop preparation
Fields can have default values configured. Default values are inserted
into the attribute form when digitizing a new feature. They are visible and can be modified as long as the field is editable. They
can be based on the geometry or expression variables.
When creating expressions for projects intended to be used with QField, it is recommended to use layer names rather than layer IDs. This recommendation stems from the fact that during the project conversion process via QFieldSync, the resulting layers may receive different IDs, which can lead to incorrect expression evaluations. By using layer names, you ensure that expressions are evaluated consistently and accurately across different project states.
For more information regarding storing information related to your
position in object attributes, refer to the deticated
GNSS documentation.
For QFieldCloud users, two variables can be used in expressions including attribute form’s default values:
- @cloud_username
which returns the name of the currently logged in QFieldCloud user.
- @cloud_useremail
which returns the email address of the currently logged in QFieldCloud user.
Insert positioning information as variable:
sql
@position_horizontal_accuracy
Insert the current date and time:
sql
now()
Insert the length of the digitized line:
sql
length($geometry)
Configure global variables on the device and insert them.
sql
@operator_name
If you want to assign a region code based on the location where a new
feature is inserted, you can do so by using an aggregate expression:
sql
aggregate( layer:='regions', aggregate:='max', expression:="code", filter:=intersects( $geometry, geometry( @parent ) ) )
To transform the coordinates received from \@position_coordinate to the
coordinate system of your project:
sql
x(transform(@position_coordinate, 'EPSG:4326', @project_crs ))
y(transform(@position_coordinate, 'EPSG:4326', @project_crs ))
::: {#snapping_results}
If you want to use the snapping results after drawing a line, you can
use the [\@snapping_results]{.title-ref} variable. The following code
extracts the value of the attribute [id]{.title-ref} of the snapping
match of the first point of a line.
:::
sql
with_variable(
'first_snapped_point',
array_first( @snapping_results ),
attribute(
get_feature_by_id(
@first_snapped_point['layer'],
@first_snapped_point['feature_id']
),
'id'
)
)
It is possible to search value in a value relation or relation reference widget using the magnifying
glass next to the field.
Note
Define the display expression for the concerned layers, this will
be used for searching for features. This is configured under
Vector Layer Properties > Display
🖥️ Desktop preparation
The “Use completer” checkbox must be checked to be able to use the
auto-complete in the value relation.
Here a video showing how it works on QField
Custom QML widgets can be useful to integrate advanced actions into forms.
In this example we define add a button that open a third-party map and navigation app.
This is useful to open e.g. turn-by-turn navigations on the device-native app for the user.
```qml
import QtQuick 2.0
import QtQuick.Controls 2.0
Button {
width: 200
height: width/5
text: “Open in Maps”
onClicked: {
Qt.openUrlExternally(expression.evaluate(“‘geo:0,0?q=’ || $y || ‘,’ || $x”));
}
}
```
The geo
URI above is adapted to work with Android. For Apple Maps the URI can be changed to 'geo:' || $y || ',' || $x
.