Preparing project
Project preparation is done in QGIS. For more information about loading layers, styling the data and creating map themes, visit QGIS documentation page. In addition, Input uses some of the features within the project to help with visualisation, data capturing and interrogation of the data. Below are the key parts used by Input:
Background layers
If you have internet connectivity, you can use a WM(T)S or XYZ layer as your background map. QGIS can also reads local XYZ tiles.
Note: that for XYZ tiles, ensure to change the tile resolution to Standard in your connection settings in QGIS. This will ensure the fonts are readable on the high resolution screens (applicable to the majority of the recent phones which come with high DPI screens).
Note: you also need to change resampling method for WM(T)S layer to ensure the texts are readable on HiDPi screens.
If you are using a vector layer for background layer:
-
Ensure to use a simplified geometry version of your data. This will help with smooth map navigation.
-
All vector layers not intended to be used as survey layers, have to be set as read-only. To make a vector layer read-only in QGIS, from the main menu select Project > Properties. Within the window, select Data Source tab and select the Read-only option for the layers you do not want to be used as survey layer in Input.
Project extent
In Input app, there is an option to zoom to the project extent. If not set, Input zooms to all visible layers. This is not particularly convenient when you have a layer with a large/global extent (e.g. Open Street Map).
To set the project extent: from Project > Properties, select QGIS Server (not the most obvious location!). Under WMS capabilities select the option for Advertised extent and either enter the coordinate extent of your project bounding box or use the canvas extent.
Survey layer
Vector layers can be used as survey layer in Input. You can apply style and set up the forms according to the QGIS documentation.
Layer properties
The following properties of a layer in QGIS project will be additionally used in Input:
Settings for Input preview panel
Similar to Google map, when a feature is identified on the map a preview panel will appear. To enable a layer being identified, the option should be enabled in QGIS desktop, under Project properties. For setting the preview panel, you need to open Layer Properties and select Display tab.
-
title - this will use Display Name (in layer properties > Display tab) which can be a field name or an expression.
-
content - there are three options for what to show in content area: 1. field values, 2. image, 3. HTML. This will use “HTML Map Tip” (in layer properties > Display tab). QGIS always interprets the content of map tip as being HTML, however Input extends the syntax to allow two more modes. If the map tip is not specified, Input will try to use the first three fields and show their attribute values.
Field values
Sample map tip content that will show “description” and “time” field values:
# fields
description
time
If the map tip content has # fields
marker on the first line, the following lines will be understood as field names that should be listed in the preview.
At most three fields will be shown. Expressions are not allowed.
Image
Sample map tip content that will cause an image to be show specified by file path in field “image_1” (containing path relative to the project directory):
# image
file:///[%@project_folder%]/[% "image_1" %]
If the map tip has # image
marker on the first line, the following line is understood as the URL for the image. It can be a regular file on the file system, but it could be even a remote image from network. Expressions embedded in the image URL will be evaluated (enclosed in [% 1+1 %]
).
HTML
Sample map tip content that will show render as HTML page:
<p><strong>Notes:</strong>[% "notes" %]</p>
If the map tip does not contain any special marker, it is assumed that the map tip is HTML content. Only a limited subset of HTML is supported - see https://doc.qt.io/qt-5/richtext-html-subset.html
Example of the preview panel in Input and QGIS tooltip set up can be seen below:
Forms
This section briefly describes behaviour of some types of widgets with several configurations.
Make use of Value Map widget in your forms to simplify filling the forms during survey.
Attachement (External resource) widget
To be able to attach photos to a survey feature, you will need to have an attribute column in your survey layer. Within the form setting, ensure to set Widget type to Attachment. The widget is compatible with field of type QString. It suppose to store absolute/relative path to an image.
Field configuration:
- Widget type - Attachment as the only option to work with images
- Default path - Defines where an image will be saved. Evaluation of
default path
configuration is in following order:- evaluate default path expression if defined,
- use default path value if not empty,
- use project home folder.
- Relative path
- unchecked - the final value of a attachment field has absolute path,
- relative to project path - relative to project home folder path (where project file is located),
- relative to default path - relative to defined default path. See section above if it is not defined.
Examples
Lets define project home folder as ‘path/to/project’, where a project file is located.
default path | relative to | value |
---|---|---|
- | - | <path/to/project>/image.jpg |
- | project home | image.jpg |
- | default path | image.jpg |
@project_folder |
- | <path/to/project>/image.jpg |
@project_folder |
project home | image.jpg |
@project_folder |
default path | image.jpg |
@project_home + '/photos' |
- | <path/to/project>/photos/image.jpg |
@project_home + '/photos' |
project home | /photos/image.jpg |
@project_home + '/photos' |
default path | image.jpg |
Date/Time widget
Field configuration:
- Widget type - Date/Time as the only option to use a date time widget
- Field format - currently supported Date, DateTime, Time, Custom
- Widget display - supported both Default or Custom
- Calendar popup - currently ignored, Input datetime widget always acts like it is checked
- Default value - has to return a type matching QgsField type
Note that while working with QString fields with a date/time value and format function (used in a default value), it is important to match field format with a given format there.
###QgsField type How the result value is saved depends on how a QgsField is defined. Following types are supported:
Default values are marked as “-”
Type: QString
field format | widget display | default value | value |
---|---|---|---|
Date | - | format_date(now(), 'yyyy-MM-dd') |
''2020-09-09' |
Custom (dd/MM/yyyy) | dd/MM/yyyy | format_date(now(), 'dd/MM/yyyy') |
'09/09/2020' |
Time | - | format_date(now(), 'HH:mm:ss') |
'12:34:56' |
Custom (HH-mm-ss) | HH-mm-ss | format_date(now(), 'HH-mm-ss') |
'12-34-56' |
Date Time | - | format_date(now(), 'yyyy-MM-dd HH:mm:ss') |
'2020-09-09 12:34:56' |
Custom (dd/MM/yyyy HH-mm-ss) | dd/MM/yyyy HH-mm-ss | format_date(now(), 'dd/MM/yyyy HH-mm-ss') |
'09/09/2020 12-34-56' |
Type: QDate
field format | widget display | default value | value |
---|---|---|---|
Date | - | - | 0000-00-00 |
Date | - | now() |
2020-09-09 |
Date | dd/MM/yyyy | now() |
09/09/2020 |
Type: QDateTime
field format | widget display | default value | value |
---|---|---|---|
Time | - | - | 00:00:00 |
Time | - | now() |
12:34:56 |
Time | HH/mm/ss | now() |
12/34/56 |
Date Time | - | - | 0000-00-00 00:00:00 |
Date Time | - | now() |
2020-09-09 12:34:56 |
Date Time | dd/MM/yyyy hh-mm-ss | now() |
09/09/2020 12-34-56 |
Project settings
Having Map Themes, will help switching between different background layers in Input (e.g. one map theme set up with aerial photo and another with cartography rasters.)
Ensure the paths are set to Relative under Project Properties. All paths to the project data in Input is relative to the project location.
Input does not include all the SVGs within QGIS. Therefore, if you are using SVGs for your layer styling, ensure those are copied across to the project folder.
An example of Project Properties in QGIS for survey layers and identifiable layers can be seen below:
QGIS variables
Input recognizes several variables that can be used in QGIS expressions (they are also supported by Mergin plugin for QGIS):
Variable name | Sample value | Scope | Description |
---|---|---|---|
@mergin_username |
martin |
global | Name of the user currently logged in to Mergin |
@mergin_url |
https://public.cloudmergin.com |
global | URL of the Mergin service |
@mergin_project_name |
Tree survey |
project | Name of the active Mergin project |
@mergin_project_owner |
martin |
project | Name of the owner of the active Mergin 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 Mergin project |
A common use case is to use @mergin_username
as the default value for one of the fields in a survey layer to automatically track who has added (and/or modified) a particular record.