This is a proposed addition to the ODK XForms spec to support functionality described at Display existing geometry when capturing new point/trace/shape on map Please see that thread for discussion around the user-facing functionality and the XLSForm spec!
XForms spec
Like selects, the geopoint, geotrace and geoshape control elements can have multiple item children or a single itemset child. Unlike selects, these are optional.
Like with selects, an itemset's label and value children define the XPath references to use to get an item's label and underlying value, respectively. Additionally, the geometry child defines the reference to use to get an item's geometry. If no ref is specified for geometry, it defaults to geometry.
When inline items are specified instead of an itemset, each item child must have a geometry child.
Each node in the resulting nodeset is a "reference feature" and is interpreted as follows:
- A reference feature MUST have a child element named
geometryor that matches thegeometryref specified in the case of anitemset. - The geometry value MUST be interpretable as a point, line or polygon that can be represented in ODK notation. For example, some clients may parse GeoJSON files into an internal format that can be represented in ODK notation.
If the geometry value is missing, empty, or invalid, the reference feature item MUST be ignored.
A reference feature MAY include child nodes that specify that feature's style. For each supported style property (same as select from map), if a child with that name exists and has a valid non-empty value, the client MUST use it for rendering that feature; otherwise the client MUST fall back to default styling.
Clients MUST ignore properties outside the defined style subset or invalid style values and fall back to default styling; style MUST NOT affect geometry parsing.
Possible future extensions
There are many possible additions to this functionality that users have requested. The ideas below are not fully developed and may never be built. We're including them to illustrate that they would be possible.
Displaying properties of reference items
The odk:reference-interaction attribute on the geopoint/geotrace/geoshape body control element specifies whether reference features can be tapped to view non-empty child nodes other than geometry and style nodes. Its value must be:
none(default): reference features MUST NOT be tappableidentify: tapping a reference feature MAY show the feature's properties (e.g. in a bottom sheet)
If the value is set to identify, tap precedence must be:
- If the tap targets an interactive part of the answer geometry (e.g. adding/moving a vertex), the geo capture behavior takes precedence
- Otherwise, if the tap hits a reference feature, display item details
Other ideas
Could also add a property to specify the geometry reference like odk:geometry-field="coordinates"
Could also add an allowlist/order mechanism like odk:reference-fields="name,type,status" -- this is something people want for select from map as well and would be applicable to a table view of items as well.