Documentation on selecting options from an external file for a choice list

Hi there,

I noticed some approximations or omissions in the Help centre’s documentation.

  1. The article found at:

speaks about appearance field and gives a link to:

That latter link explains how to use search(), in a way that does not work in Kobo (Enketo). I have spoken with one of the main developers of Enketo, and he told me that not supporting the search() function was a deliberate choice, because the search() function is actually a wonky hack that was created to workaround some gaps in the XForm standard specifications. Alas, those gaps have not been filled yet and one might regret that Enketo does not offer ways to workaround them (for example, to feed select fields with real-life CSV files in a flexible way).

Anyway, this link should be provided with some warning that Kobo does not implement/support all of what is written there, in particular the search() function.

  1. The page

delivers a couple of pieces of information that do not match the actual behaviour:

  • The name of the list in sheet “choices”, column “list_name”, indeed needs to be the same than the one in the “list_name” column of the CSV file, but the corresponding field name (or “question” name, or “variable”) and file name can be different (which makes sense if we consider that several fields might use the same list of choices); so in the phrase of “Step 2” that reads “In the choices sheet of the XLSForm, type the name of the variable (i.e. fruits) under list_name” the part “type the name of the variable (i.e. fruits)” should be replaced by “choose a name at your convenience”; and in the phrase in “Step 3” that reads “Under the list_name column, type the variable name for each row”, “variable” should be replaced by “the list name you chose in Step 2”.

  • Whatever is written in the “label” column of the “choices” sheet (even a random word or even just nothing) for the considered row, Enketo will display what is in the “label” column of the CSV file; if the CSV file does not have a “label” column (and again, whatever is set in the “label” column of the “choices” sheet), Enketo will display void labels (radio-buttons or checkboxes with no label). See the below attached example.

    • This entails a limitation: since only the “label” column from the CSV file is taken into account, no “label::en” or “label::whatever” will be displayed, and therefore no multi-language labels are supported. A possible workaround for a given select question Q1 using external options is to split it in several questions, each dedicated to a language, like Q1_en and Q1_fr, each using different rows of the CSV file by using filtering, with conditions in the “relevant” field making only the appropriate field (either Q1_en or Q1_fr) appear depending on the language. The “relevant” conditionality must rely on the jr:choice-name() of a prior select field, for example Q0 (I don’t think there is any other way to probe a form’s current language). Unfortunately, if the language is switched during the data collection, the question Q0 must be re-answered to refresh the detected language. Then, a Q1 calculate field can be created to consolidate responses from Q1_en and Q1_fr with the coalesce() function. See the attached example:
      Demo-fruits-multilanguage.xlsx (17.9 KB) fruits_multilang.csv (252 Bytes)
  • However, the “name” column of the “choices” sheet must not be void, or Enketo will throw an error. But it can be anything (as seen in the above attached example), even a random word that matches no column in the CSV file; anyway, Enketo will use the “name” column of the CSV file. If the file does not have a “name” column, Enketo will throw an error too.

Thank you so much for this; we will definitely look into this and amend what can be amended within the next couple of weeks. Thank you so much for your contribution.