Understanding Dynamic Labels in Survey123 for ArcGIS
Starting with version 3.1, you can dynamically change the label of a question, using answers from other questions in the form. Dynamic question labels are particularly handy when working with very long forms, making questions in your survey more meaningful to end-users.
The Water Violation survey sample on the side, for example, shows how you can insert the Type of Violation and Name of Offender in the photo and signature questions that follow.
This is quite a simple example to illustrate the idea. As your survey includes questions across multiple groups, repeats and even pages, dynamic labels become critical to aid with form navigation and to avoid user input errors.
The dynamic labels technique is often described in survey jargon as question piping, where user responses are inserted or piped into questions further into the survey.
You can add dynamic labels to your forms using Survey123 Connect for ArcGIS. Once published, dynamic labels will work in both the Survey123 web as well as the field apps.
The basics of dynamic labels in XLSForm
In order to insert text dynamically within a question label, you must add XLSForm variables in the label column of your survey. The syntax is quite simple. Insert ${QuestionName} exactly where you want the answer to a particular question in the survey to appear in your label. This is what the Water Violation example illustrated above looks like in XLSForm.
You can add multiple variables to the same label but it is important to highlight that the use of full XLSForm expressions within the label column is not supported. Survey123 will only replace XLSForm variables. For example, this is valid:
But this is not valid:
While you cannot use full XLSForm expressions within the label, you can use them in a calculate question, and then reference your calculate question in the label. Calculate questions will not show in your form, but will help you hold the output of full XLSForm expressions, so you can insert those values in a label. For example, lets pretend you want to use a dynamic label in a note to describe the total cost of repairs of a pipe, given its length:
The cost question is a calculate. It will not be shown in the form to the end-user. We use the cost calculate question to run a full expression that evaluates the total cost, and once we have that, we simply use it for our dynamic label.
Working with different data types
As you work with dynamic labels, you will notice that things are straight-forward when you want to insert values from questions of type text, decimal or integer. All you will need to do is to reference these questions directly exactly as shown above. When working with other types such as dates or select questions, things are a bit more complicated and you will need to pre-process user values through calculate questions before you insert them into the label.
- Dates: If you want to insert a date value within a label, you must first use a calculate question and apply the format-date() function. There are some details about formatting dates in https://community.esri.com/groups/survey123/blog/2016/04/17/dates-and-time-in-survey123-for-arcgis After doing this, you can bring the formatted date value string from the calculate question, into your label.
- Select_one questions: If you want to bring a user selection from a select_one question into a dynamic label, you have to keep in mind that by default, you are going to get the choice name value, not the label of the selected choice. If you want to display the label of the selected choice, then I suggest you use a calculate using the jr:choice-name() function.
Support for the XLSForm jr:choice-name() function was introduced in Survey123 in version 3.1 in both the field and web Survey123 apps. This function takes two inputs: a string representing a choice name, and a second string representing the name of the select question. Note that the second parameter requires you to enclose the question with quotes.
The output of this function is the label of the choice name passed-in. If this function is used in a multi-language survey, the label returned is that of the active language.
- Select_multiple questions: Select_multiple questions let you choose one or more values from a predefined list. The output of a select_multiple question is a comma-separated string representing all the values selected by the user. This output, as is, is not the easiest to handle with dynamic labels, but again you can use other calculate questions to properly massage the output before it is added to your question label. The https://community.esri.com/groups/survey123/blog/2017/08/30/understanding-multiple-choice-questions-... blog post describes in more detail how multiple choice questions behave and how you can work and control its outputs.
Other things to consider
There are some obvious and not so obvious things to consider when working with dynamic labels:
- If you reference in your label a question for which the user has not provided an answer, then your question is going to have some missing text. You can choose to be clever with the label. For example, in our Water Violation Example it is not evident when the violation type is missing. You will either read “Photo of the violation” (No violation type chosen) or “Photo of the Broken Pipe violation” (if Broken Pipe has been chosen). In practice, you will not always get so lucky when the variable is missing. In the pipe cost repair example above, it is evident that we are missing something in the total cost note when a dollar amount is not present. You can choose to use a relevant statement to hide questions with dynamic labels until the variable to be replaced (in our example the cost or repair) has a valid value. In these cases, you can use the string-length() function as shown in the following example.
- Your dynamic labels will certainly look great in the survey, but what about when you bring your survey layers into web maps? Or when you look at your survey data in the Survey123 website? On this one, it is important to understand what really happens when your survey is published, and how the Survey123 website as well as other ArcGIS apps work with your survey layers.
When you publish an XLSForm document with Survey123 Connect, we take the values in the name column of your survey spreadsheet and we use them to create new fields in the survey feature layer. By default, we use the contents of the label XLSForm column to define the field aliases of your attribute fields. Typically, ArcGIS apps will use the field alias for display purposes. This is the case in the popup of a web map as well as throughout the Survey123 website.
When you insert a dynamic label, your field aliases will include the variable placeholder and that will not look very nice. If you are worried about this, make sure you set the alias value for your attribute fields in the esri::bind:esriFieldAlias XLSForm column. Alternatively, you can also refine the field aliases, after the survey is published, from the Item Details page of the feature layer item.
If used wisely, dynamic labels can help you build better and more user friendly smart forms. We hope this new feature is useful to you!