Merge pull request getodk#1461 from lognaturel/select-map

Select map

src/collect-offline-maps.rst

@@ -14,8 +14,7 @@
 Using Offline Maps
 ====================
 
-Collect's :ref:`geopoint <geopoint-maps>`, :ref:`geotrace <geotrace-widget>`, and :ref:`geoshape <geoshape-widget>` questions can be configured to display different map data. The :ref:`mapping-settings` let you select a basemap to show, as well as a reference
-layer to show on top of the basemap.
+Collect's :ref:`location question types <location-widgets>`, :ref:`select from map question <select-from-map>`, and :doc:`filled form map <collect-form-map>` can be configured to display different map data. The :ref:`mapping-settings` let you select a basemap to show, as well as a reference layer to show on top of the basemap. Those settings are shared between all mapping components in a single :doc:`project <collect-projects>`.
 
 The data for all the available basemaps comes from services on the Internet, so the basemap will only be visible to users who are online. To choose a basemap, select a :guilabel:`Source` and then a :guilabel:`Style` if multiple styles are available.
 

src/form-datasets.rst

@@ -13,6 +13,8 @@
   ezeke
   Eziama
   eziama
+  geojson
+  Giger
   lga
   lgas
   Poperi
@@ -45,7 +47,7 @@ External datasets are useful when:
 Building selects from CSV files
 ---------------------------------
 
-CSV files can be used as datasets for select questions using ``select_one_from_file`` or ``select_multiple_from_file``. CSV files used this way must have :th:`name` and :th:`label` columns. For each row in the dataset, the text in the :th:`name` column will be used as the value saved when that option is selected and the text in the :th:`label` column will be used to display the option. For select multiples, :th:`name` must not contain spaces.
+CSV files can be used as datasets for select questions using ``select_one_from_file`` or ``select_multiple_from_file``. CSV files used this way must have :th:`name` and :th:`label` columns unless you use the :th:`parameters` column to :ref:`customize the columns used <customizing-label-and-value>`. For each row in the dataset, the text in the value column (defaults to :th:`name`) will be used as the value saved when that choice is selected and the text in the label column (defaults to :th:`label`) will be used to display the choice. For select multiples, :th:`name` must not contain spaces.
 
 These files may also have any number of additional columns used in :ref:`choice filters <cascading-selects>` or other expressions. The example below uses one select from internal choices followed by selects from two different external CSV files.
 
@@ -77,6 +79,61 @@ These files may also have any number of additional columns used in :ref:`choice
   ezeke_amasiri, Ezeke amasiri, afikpo_n
   poperi_amasiri, Poperi amasiri, afikpo_n
 
+.. _selects-from-geojson:
+
+Building selects from GeoJSON files
+------------------------------------
+
+*New in* `ODK Collect v2022.2.0 <https://github.com/getodk/collect/releases/tag/v2022.2.0>`_, `ODK Central v1.4.0 <https://forum.getodk.org/t/odk-central-v1-4/36886>`_
+
+.. warning::
+  GeoJSON attachments are not yet available in web forms (Enketo).
+
+
+GeoJSON files that follow `the GeoJSON spec <https://datatracker.ietf.org/doc/html/rfc7946>`_ can be used as datasets that populate select questions using ``select_one_from_file``. Selects from GeoJSON may be styled as maps using the :ref:`map appearance <select-from-map>` but can also use any other :ref:`select appearance <select-appearances>`. In order to be used by a form, a GeoJSON file:
+
+- must have a ``.geojson`` extension (NOT ``.json``)
+- must define a single top-level `FeatureCollection <https://datatracker.ietf.org/doc/html/rfc7946#section-3.3>`_
+- must include a unique identifier for each feature (by default, a top-level :th:`id`, falling back to an :th:`id` property, or can be :ref:`configured <customizing-label-and-value>`)
+- must only include features with `Point geometry <https://datatracker.ietf.org/doc/html/rfc7946#appendix-A.1>`_
+
+.. csv-table:: survey
+  :header: type, name, label
+
+  select_one_from_file museums.geojson,museum,Select the museum closest to you
+
+GeoJSON files referenced in forms can have any number of ``features`` and any number of custom ``properties``.
+
+.. code-block:: json
+
+    {
+      "type": "FeatureCollection",
+      "features": [
+          {
+              "type": "Feature",
+              "geometry": {
+                  "type": "Point",
+                  "coordinates": [
+                      7.0801379,
+                      46.5841618
+                  ]
+              },
+              "properties": {
+                  "id": "fs87b",
+                  "title": "HR Giger Museum",
+                  "annual_visits": 40000
+              }
+          }
+      ]
+    }
+
+All properties are displayed by :ref:`select from map <select-from-map>` questions and can be :ref:`referenced by any part of the form <referencing-values-in-datasets>`.
+
+A feature's :th:`geometry` can be accessed as ``geometry`` and is provided in :ref:`the ODK format <location-widgets>`. Given the GeoJSON file and the form definition above, if the user selected "HR Giger Museum", the value of ``${museum}`` would be ``"fs87b"``. 
+
+The expression ``instance('museums')/root/item[id=${museum}]/geometry`` would evaluate to ``46.5841618 7.0801379 0 0`` which is a point in the ODK format.
+
+
 .. _selects-from-xml:
 
 Building selects from XML files
@@ -110,6 +167,6 @@ For internal datasets, the instance name is the ``list_name`` specified on the *
 
 .. note::
 
-  Due to a pyxform bug, it is necessary for there to be some value in the `choice_filter` column (for at least one question) when referencing internal datasets. If none of the questions in your form need filtering, simply put `true()` as the `choice_filter` value.
+  Due to a pyxform limitation, it is necessary for there to be some value in the `choice_filter` column (for at least one question) when referencing internal datasets. If none of the questions in your form need filtering, put `true()` as the `choice_filter` value.
 
 For external datasets, the instance name is the filename specified in the ``select_one_from_file`` or ``select_multiple_from_file`` declaration without the file extension. For example, to look up a ward's label given the form :ref:`above <selects-from-csv>`, the instance name to use is ``wards`` because the filename referenced is ``wards.csv``. The expression would be ``instance("wards")/root/item[name = ${ward}]/label``.