Cascading selects are used to restrict a list of available answers based on the answer to a previous question, and their content can be stored within the XLSForm itself, or in an external file.
Cascading selects
Cascading selects are used to restrict a list of available answers based on the answer to a previous question. This makes surveys easier to use, keeping choice lists small, by only presenting relevant options to users.
For each choice list in the hierarchy, complete the following:
- Enter the values for the choice lists on the choices tab.
- Add one or more columns for the cascading select criteria (for example, country, state, city, suburb).
- Enter the relevant value for each choice in the extra columns.
It is not recommended that you include duplicate choice names in a choice list. For more information, see Multiple choice questions.
Once the choice lists have been completed, you must create a choice_filter column on the survey tab. This column holds the expression used to restrict your choice lists. The choice_filter column can accept the contents of another field, for example, state=${state_1}, or an expression, for example, selected(${states_visited},state_code).
To see cascading selects in action, see the Choice Filters and Cascading Selects sample in Survey123 Connect.
You can use cascading selects with select_one, select_multiple, and rank questions. Cascading selects are not supported for rank questions in the Survey123 web app.
Tip:
When reviewing the results of a survey with a question that uses a cascading select, only the name of the choice that is submitted is displayed. This is different from the behavior of select_one or select_multiple questions without a choice filter, where the label of the choice is displayed instead.
Use the jr:choice-name() function in another question to return and store the label associated with the choice from a question. Conceptually, this can be represented by jr:choice-name(string value, 'question name').
In jr:choice-name(${city_choice}, '${city_choice}'), the first parameter represents the selected value, and the second is the name of the question. You must define the name of your question inside quotation marks.
For select_multiple questions, you must use the selected-at() function to extract the label for individual answers. For example:
jr:choice-name(selected-at(${city_choice}, 1), '${city_choice}')
You can use the jr:choice-name() function in any string question. When using a hidden question, also define its bind::esri:fieldType and bind::esri:fieldAlias.
Caution:
Starting with Survey123 version 3.12, choice lists are managed through an internal database. This means that you cannot use SQLite reserved keywords for column names in cascading and external selects.
External selects
The choice lists associated with cascading selects can become large and impact the performance of your forms. Survey123 has an option to save these lists in an external file and load them into the survey on demand.
To implement this option, create a tab on the spreadsheet for the survey named external_choices. This new tab must contain the same column headings as the choices tab. When the survey is published, values from the external_choices tab are saved in a file named itemsets.csv in the media folder of your survey project, rather than as part of the form item. To reference the choice lists on the external_choices tab, use select_one_external to prefix the list name.
External selects are different than an external choice list, which does not require an external_choices worksheet.
Note:
External selects are only possible for select_one questions. They are not supported for select_multiple questions.
External selects are designed to work with choice lists associated with a cascading select only. Only choices with an applied choice filter are added to the itemsets.csv file.