Version Notice: This article covers features in our r9/IS Pro platform. If you're looking for information on this topic related to r8, see validate.
Survey questions sometimes need specific restrictions on how a respondent may answer them. Use the validate
(alias validation
) widget or tag to create custom restrictions, known as validations.
The validate
tag evaluates a logical condition and prevents the respondent from continuing to the next page if the condition is false. Every validation must include a message that communicates to the respondent why they cannot proceed.
To ensure a good respondent experience, it is important to carefully test validations. The conditions should be tested to ensure respondents can't get stuck, unable to meet the requirements. It is also important to write clear validation messages so that respondents can easily determine how to pass the validation.
Syntax
Validations may be written as a tag on a question or table, or as a standalone widget. Validations consist of a condition followed by a message
decorator.
validate: [condition] { message: Text to display if condition not met }
Be sure to write the condition in terms of what is needed for the respondent to continue. The validation is triggered when the condition evaluates as false.
Multiple validation
tags may be added to a single question. See below for examples.
Tip! Make sure the validation is on the same page as the criteria it validates. When a respondent sees a validation message, they should not need to navigate to a different survey page to resolve the issue. This will help prevent situations where respondents can get stuck, or feel like they are stuck if they encounter a validation.
'warn: y' decorator
Add the warn: y
decorator to a validation to allow respondents to continue past a validation after it has been triggered once. Be sure to clearly indicate they may continue in the message.
validate: [condition] { message: Text to display if condition not met } { warn: y }
'flag' tag
When a validation is triggered, a validation icon will appear next to the question(s) that are referenced in the condition. Include the flag
tag, along with one or more question IDs, to add this icon to other questions on the page and help direct the respondent's attention.
validate: [condition] { message: Text to display if condition not met } flag: QX
# Add flag to multiple questions with a comma-separated list:
flag: QX, QY, QZ
'value' placeholder
In validation conditions, the [value]
placeholder can be used instead of $QX
, where 'X' is the question ID where the validation has been added. Note that the [value]
placeholder is only available when the validate
tag is included on a question and not used as a standalone widget.
validate: anyChecked([value],1) { message: Message here }
Validations in tables
If a validation condition for a table needs to be repeated for every row or column of the table, a row validation
or column validation
may be more appropriate. See Table row validation and column validation (r9) for more information and examples.
The [value]
placeholder may also be used in a table with the validate
tag, instead of a row validation. See the example below.
Examples
Validate response against a previous question
The following example uses validation in Q2 to ensure that one's responses in the table match the responses from the previous question (Q1). If the respondent answers that they have children in either (or both) age ranges, they must enter a quantity for the age range(s) they selected. If they leave a text field blank or enter '0' for one of the age ranges in which they indicated they have children, the validation message will be displayed, indicating there is a discrepancy, and their response in Q2 should be amended.
1. Do you have children living in your home? type: checkbox exclusive: 99 1. 0-7 years old 2. 8-17 years old 99. No kids in those age ranges 2. How many kids do you have in the following age ranges? type: integer table showif: anyChecked($Q1,1,2) maxlen: 2 datatype: whole rowsfrom: Q1 validate: (anyChecked($Q1,1) and $Q2R1 > 0) or noneChecked($Q1,1) { message: In the previous question, you indicated you had a child between the ages of 0-7. } validate: (anyChecked($Q1,2) and $Q2R2 > 0) or noneChecked($Q1,2) { message: In the previous question, you indicated you had a child between the ages of 8-17. }
Multiple validations with 'value' placeholder
In this example, QFAVORITE2 has two separate validations. The conditions use the [value]
placeholder instead of writing out $QFAVORITE2
.
set list: COLORS3 1. red 2. orange 3. yellow 4. green 5. blue 6. indigo 7. violet FAVORITE2. Pick two colors. type: checkbox optsfrom: COLORS3 validation: countChecked([value]) == 2 {message: Please select exactly 2 answers.} validation: anyChecked([value],6,7) {message: You must pick a purplish color.}
Using 'value' placeholder for table row validation
The [value]
placeholder functions as a row or column validation when used on a table.
3. Select red or blue in each row. type: checkbox table rowsfrom: series[1..3] 1. Red 2. Blue 3. Yellow validate: anyChecked([value],1,2) { message: Select red or blue. }
With row validation, the example above would be written as follows:
row validate: anyChecked($Q3R[id],1,2) { message: Select red or blue. }
Note: The [value]
placeholder is not compatible with row or column validations.
Open-end text validation
The validate
tag can also evaluate text responses. Q4 in the example below requires an answer of 'yellow' to continue.
4. What color is a banana? type: text maxlen: 6 validate: [value] eq 'yellow' { message: Sorry, that is not the correct color. Try again. }
Tip! Validation logic for text is very precise. In the above example, 'Yellow' would not be accepted because of the capital 'Y'.
The condition [value] eq 'yellow' or [value] eq 'Yellow'
would allow for this variation. For more complex ways of validating text responses, see Using other tags alongside validations below.
Allowing respondents to continue with 'warn: y'
The following example uses a validation with the warn
decorator. If '1' is selected, the respondent may click the continue button a second time to move past the validation without changing their response. It's a good idea to make this clear in the validation message so that the respondent doesn't think they're stuck.
S5. Make a selection. type: radio 1. 1 2. 2 validate: $QS5 == 1 { message: Are you sure? Click continue again to confirm. } { warn: y }
Using listUnique for table validation
Use the listUnique
function in a validation to require respondents to enter a unique response for every row or column in a table.
This basic example references the series
function as the list name, and uses [id]
as the iterator, which pulls in each option ID established in the series. Each field reference constructed becomes '$Q6R1', '$Q6R2', and so on. The function then returns the result of the evaluated statement, examining whether any of the rows' text entries match the others.
6. Try writing the exact same text in more than one row. type: text table rowsfrom: series[1..5] validation: listUnique(series[1..5]; $Q6R[id]) {message: Every row must be unique.}
Using other tags alongside validations
There are many tags in SPL that provide built-in validations, especially for numeric and open-end text questions. Tags such as datatype
, maxlength
and minlength
, or maxchecked
, minchecked
, and numchecked
are designed to handle many common use cases. It is often a good idea to review the available tags and see if they can provide the desired validation.
If needed, validate
tags can be used alongside other tags to produce the desired restrictions. In the following example, we want to ensure the respondent enters a six-digit number. The datatype: whole
tag restricts the allowed input to numeric characters. The maxlen: 6
tag sets the size of the text field on the page and limits the length of the response to six characters. Lastly, the validate
condition length($Q7)
== 6
specifies that the response must be six characters long.
7. Please enter your six digit catalog number: instructions: Enter exactly six digits. prefix: Catalog Number: type: integer datatype: whole maxlen: 6 validate: length($Q7) == 6 {message: Try again. The number you enter must be a 6 digit number.}
Tip! The minlength
tag is intended for open-end text responses. Its built-in validation message ("Please be more specific") wouldn't be appropriate for this scenario. A validation is used instead of minlen: 6
so the message can be customized.
In this example, Q8 must be eight characters long and contain only letters or numbers. The datatype: word
tag restricts the allowed input to letters and numbers (no spaces or special characters). The maxlen: 8
tag sets the size of the text field on the page and limits the length of the response to eight characters. Lastly, the validate
condition length($Q8)
== 8
specifies that the response must be eight characters long.
8. Please create an eight character username. instructions: Use only letters and numbers. type: text datatype: word maxlen: 8 validate: length($Q8) == 8 { message: Please use only letters and numbers. You must enter eight characters. }
Validations with Perl and regular expressions
As with other tags and decorators such as cvalue
or condition decorators, validation conditions accept Perl syntax. For text entry questions, regular expressions (a.k.a. "regex") is useful for validating responses. In the example below, regex is used to ensure that only letters are entered for the first name and last name fields. For more information, see Perl code in surveys.
starttable: 9 intro: Please enter your contact information to receive your incentive. type: text cellalign: left validate: ($Q9RFIRST =~ /^[a-zA-Z]+$/) {message: Please ensure there are only letters in your first name.} validate: ($Q9RLAST =~ /^[a-zA-Z]+$/) {message: Please ensure there are only letters in your last name.} FIRST. First Name LAST. Last Name EMAIL. Email datatype: email endtable
Comments
0 comments
Please sign in to leave a comment.