Cascading and external selects

Cascading selects

Cascading selects are used to restrict a list of available answers based on the answer to a previous question. This will make your surveys easier to use, keeping choice lists small, by only presenting relevant options to users.

Follow these steps to use cascading selects in your survey:

  1. Enter the values for the choice lists on the choices tab.
  2. Add one or more columns for the cascading select criteria (for example, country, state, city, suburb).
  3. Enter the relevant value for each choice in the extra columns.
  4. Repeat for each choice list in the hierarchy.

Once the choice lists have been completed, you'll need to create a choice_filter column on the survey tab. This column will hold 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 Cascading Selects sample in Survey123 Connect.

Cascading selects can be used with select_one or select_multiple questions. The values used in the name field of the choices sheet must be text, not numeric.

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 will be 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. The name of your question must be defined inside quotation marks.

The jr:choice-name function can be used in any string question. When using a hidden question, be sure to also define its bind::esri:fieldType and bind::esri:fieldAlias.

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 your survey named external_choices. This new tab should contain the same column headings as the choices tab. When the survey is published, values from the external_choices tab will be 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 or select_multiple_external to prefix the list name.

External selects are not to be confused with an external choice list, which does not require an external_choices worksheet.

Note:

External selects are designed to work with choice lists associated with a cascading select only. Only choices with an applied choice filter will be added to the itemsets.csv file.