Understanding Multiple-Choice Questions in Survey123 for ArcGIS
Through a multiple-choice question, users are allowed to select one or more
options from a predefined list of values.
Some scenarios where multiple-choice questions are handy include:
- In an asset inspection form, a multiple choice-question can be used to represent a checklist.
- In a water-waste report, a multiple-choice could represent the potential violations of the city's code.
- In a household needs assessment survey, a multiple-choice question can be used to indicate if one or more of the following are needed: water, clothes, food, blankets.
This blog post covers multiple-choice questions in depth, starting with the basics but also covering some advanced techniques.
The Basics: How to create multiple choice questions
Multiple choice questions can be created both from Survey123's Web Designer as well as from Survey123 Connect for ArcGIS.
Survey123 Web Designer:
Survey123 Web Designer is available at https://survey123.arcgis.com Log with your ArcGIS Online credentials and choose New Survey. You will be prompted to launch Survey123 Web Designer at that time.
Configuring multiple choice questions from Web Designer is an absolute no-brainer: you can easily drag a Multiple Choice question into your draft view of the survey and start adding choices immediately. This video will show you how to get started:
Right from Web Designer, you can use the Validation section to control the minimum and maximum number of options that can be checked in the question by the end-user.
Survey123 Connect for ArcGIS:
With Survey123 Connect for ArcGIS you can define multiple-choice questions using the XLSForm specification. Using Survey123 Connect is more involved, but gives a good deal of flexibility defining the look and feel of your multiple-choice questions as well as user-input validation rules.
XLSForms is a standard that describes how to define smart forms using an XLS spreadsheet. I recommend using Microsoft Excel when creating XLSForms for Survey123 for ArcGIS. Survey123 Connect is a desktop tool that you can download to help you create and publish your XLSForms into ArcGIS. You can download Survey123 Connect from our Survey123 download page.
In XLSForms, multiple-choice questions are modeled as select_multiple type of questions. To properly create such a question you must define a list defining all choices to be shown, and you must create the list in the choices worksheet of your XLSForm. This 3 minute video-tutorial introduces choice questions in XLSForms. It touches on questions that let you select one choice (select_one) and those where you can select multiple choices (select_multiple).
Advanced Topics: Multiple-Choice Questions and XLSForms
Beyond adding basic multiple-choice questions to your surveys, there is much, much more you can do. In the next few sections I will explore in more detail some advanced techniques and concepts regarding multiple-choice questions and XLSForms.
Appearances
By default, elements in your multiple-choice questions will be arranged vertically in a single column. You can however arrange your choice lists differently using the appearance column in the survey worksheet of your XLSForm:
- Leaving the appearance column empty will arrange your choices vertically in a single column. This is typically the best option when you want to include a small number of choices. Say up to 10 or so. Using a single column also makes handling long labels easy.
- Setting the appearance value to horizontal may allow you to save vertical real estate when displaying all choices at once. In practice, the horizontal appearance is best when you have a very small number of choices and when the choice labels are short. The horizontal appearance will attempt to display all choices in a single row, but if the width of your device is not enough, it will start arranging elements in columns.
The best thing about the default and horizontal appearances is the fact that all choices are presented at once to the user, minimizing clicking and tapping. Having all choices visible at all times accelerates data entry, and is also handy when you want to review responses in a survey. Now: displaying all choices at once it not the best idea when you have many choices.
- The minimal appearance will collapse your choice list into a drop-down menu. This is advantageous when the list of choices is long because it reduces the vertical real estate needed to render the form. It can also help reducing the initial loading time of the survey. The caveat is that for user to check choices in the list a tap is needed before one can see the options.
No other appearances apply to multiple choice questions. If you use other appearances (numbers, autocomplete, etc) the arrangement of choices will be shown as horizontal.
Label Formatting
You can refine the look and feel of your choices using HTML formatting. This is not unique to select_multiple questions, as it also applies to select_one questions, but I thought I would add this as a reminder. In the Residential Septic Tank Inspection survey on the side, for example, I used HTML Label formatting to underline specific parts of the choices. HTML formatting can similarly be used to change the color of the text. You can find a complete reference of all the HTML tags you can use in this help topic.
Just for completeness, here is what the choice list in XLSForm would look like. Note that I inserted the <u></u> HTML tag in the label of some of the choices to underline certain words.
Building XLSForm expressions for constraints, calculations, relevant statements...
There are two critical functions in XLSForms that you need to understand before you can write effective expressions on top of select_multiple questions.
- selected: The selected function will help you determine if a particular choice in your list has been selected. For example, the expression selected(${violations},'overwatering') will return true if the overwatering choice has been selected in the violations question. It does not matter if overwatering is the only or one of many other violations selected... if the overwatering choice was checked, the function will return true.
It is important to keep in mind that internally, the selected choices by the user are kept as a comma separated list of values. It is for this reason that an expression like ${violations}='overwatering' does not return true if the user has selected overwatering plus other violations. It will only return true if the only choice selected is overwatering.
- count-selected: The count-selected function returns the number of selected choices in a select_mulitple question. For example count-selected(${violations}) returns 3 if the user has selected a total of 3 violations from your choice list.
The two functions above are specifically designed to work with select_multiple questions. You can use them in different scenarios. For example, you can use count-selected in the constraint field to ensure that no more than 4 choices are selected in a particular multiple-choice question. You can also use selected to control the visibility of a note through an expression in the relevant column that determines if a particular combination of choices has been selected.
Controlling how user selections are stored in ArcGIS
In the previous section I already hinted that user selections in select_multiple questions are internally handled as a comma separated list of values. Now, this does not necessarily mean that you have to store it that way in ArcGIS. There are good reasons why you may want to store them differently and this is perfectly possible.
In some cases for example, you may want to store the user selection using one field for each of the choices in your list, and a binary value indicating it the choice was checked or not. Why you would want to do this? Well, because once you normalize your data this way you can more easily run queries and analysis on the captured data.
In the next XLSForm spreadsheet you can look at the syntax a bit closer. Note that I added as many hidden questions in my survey as choices are present in the violations list. I keep the questions as type hidden because I do not want them to be presented to the end-user, but I want their values to be stored in my feature service. The values in these questions are automatically set through an expression in the calculation column. If the choice is selected, I store a value of 1, otherwise, I store a value of zero.
| type | name | label | calculation |
|---|---|---|---|
| select_multiple violations | violations | Violations observed | |
| hidden | overwatering_violation | Overwatering | if(selected(${violations},'10'),1,0) |
| hidden | brokenpipe_violation | Broken Pipe | if(selected(${violations},'20'),1,0) |
| hidden | time_violation | Time | if(selected(${violations},'30'),1,0) |
| hidden | day_violation | Day | if(selected(${violations},'40'),1,0) |
| hidden | waterfeature_violation | Water Feature | if(selected(${violations},'50'),1,0) |
When using this technique, keep in mind that hidden questions will by default be mirrored in your feature service with a field of type string. If you want to be more specific, you can force the field data type by using the bind::esri:fieldType column of your XLSForm. For example, in my example above, I will want to set the value of bind::esri:fieldType to esriFieldTypeInteger, because I only plan to store zeroes and ones.
When working with if statements, remember that there should be no spaces between if and the open parenthesis.
- if(selected{$question},'choice'),true,false) works
- if (selected{$question},'choice'),true,false) will not do anything
In the case of the select_multiple question, the default field data type will be string as well, and you really do not want to change that because comma separated lists of values can only be persisted in a string field. Now, as we will see later, there are some cases where you may need to change the length of the field.
Starting with version 2.4 of Survey123 (scheduled to be released before the end of September 2017), we will introduce a new option in the bind:esri:fieldType list. This new option is null and can be used to indicate that you do not desire to persist the selection values (the comma separated list) from the select_multiple question. Using the null field type makes sense when you have used the user selections to drive values in other questions of the survey.
Common mistakes, errors and other tips.
Multiple-choice questions are tricky because of the way the user selection is handled. This can cause some common errors, so I will try to summarize them here.
${question}='choice' vs selected(${question},'choice'). The most common mistake people make when working with select_multiple questions is the belief that you can tell if a particular choice has been selected simply by simply doing a string comparison against the data in the question. I described this above when taking about the use of the selected function, but I will be more explicit here.
Do not use ${question}='choice' to validate if a choice has been selected. It will not work unless the specified choice is the only choice selected in your question. You should use the selected (${question},'choice') function instead.
Error Code 1000: String or binary data would be truncated. This error message is triggered when the Survey123 app is attempting to insert data into a feature service field that exceeds the capacity of that field. There are some conditions when using select_multiple questions where this error could be generated.
By default, Survey123 will create a field of type string and with length of 255 characters for every select_multiple question you add into your survey. Now, given that the result of a selection is persisted as a comma separated list of values, it is technically possible to have Survey123 attempt to add longer strings into that field. This of course can only happen when you select many choices. If concatenating the values of all selected choices exceeds the length of the field you will get the error described above.
There are a couple of things that you could do in this extreme case. The first one is to make the field for your question bigger by using the bind::esri:fieldLength column in you the survey spreadsheet of your XLSForm. The second one, is to rethink the length of the names given to your choices in the choices spreadsheet. As indicated above, starting with 2.4 you can even decide not to store the comma separated list of values which certainly will get rid of your error...
Pointing your select_multiple question against an integer field. Imagine that your select_multiple question is using a choice list where the values (names) are all integers. Well, then you should be able to store the user selection in an integer field. Right? No! Remember that if the user selects more than one choice, the output of the select_multiple is a comma separated list of values... That will be a string.
Defaults. Just like with any other type of question in Survey123, you can define in your XLSForm what the default values should be. Given that select_multiple data is modeled as a comma separated list of values, you can make one or more choices be selected by default by simply figuring out what the comma separated string should look like. To get things straight, make sure that the order of choices in your string is the same as the order of values in your list.
Multiple-choices & Multiple-Languages. Also like any other question n Survey123, you can translate select_multiple questions into multiple languages. For details, have a look at this other blog post on Introducing Multiple Language Surveys.
All in one sample.
It has a lot of merit if you got so far down into this post. There are quite a bit of boring details up there! In case you like learning by example, we have a added a new XLSForm sample into Survey123 Connect that illustrates much of what is described here. You will learn quite a bit by simply looking at the XLSForm. To open the sample, go into Survey123 Connect, click on New Survey and select the Multiple-Choice survey from the Samples category.
If you can't choose wisely, choose many times.
(Old Kiwi proverb...Chinese, Italian... OK, I just made it up )