Help:Text Field Validation
HELP PAGE DISCUSSION CLOSE
Revision as of 23:21, 24 March 2013 by Matt (talk | contribs) (1 revision)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Text Field Validation allows you to specify a condition that will validate text a respondent has entered. It is used in question configuration and survey logic. There are many types of validation you can enforce, some of which can be very complex. The full range of configuration options are explained below. Learning how to use this field accurately will help you place restrictions on what text a respondent can enter, create more complex display conditions for questions and much more!


First, you must decide what type of text validation you wish to use. The following options are available from the select box that starts out blank when no validation method has yet been selected. Once you select one of the following validation methods, further fields will automatically appear below your selection.

All validation types listed above will also include a check box labeled "not" which allows you to negate the validation you have selected. For instance, if you selected Exact Match, entered 'hello' in the validation text field and then checked not, users would be able to put anything into that text field except for the text 'hello' and it would pass validation. In the case of Matches Numerical Expression and [[#[validate] Number|[validate] Number]] validation options, regardless of whether not is checked, the respondent will be required to enter a valid number or validation will fail.


The first four validation options listed above will also allow you to specify whether or not the validation is to occur sensitive to the case of the entered text. By default, capitalization is ignored and the matching is done case insensitively. If you wish to enforce the case of your validation string, you can select the case sensitive option.


If you have created a multi-language survey, the first five validation options listed above will allow you to enter a different validation for every language in your survey. The validation that you enter will only be applied to the language you enter it for. If you do not define a validation text for a language, then any text entered by a respondent who is taking the survey in that language will pass validation. There is a small exception for Matches Numerical Expression which will be explained below. However, in most cases, you will need to enter a validation string for each language. The following goes into detail on how you can configure each of your validation options.


Exact Match

When you have chosen to validate on an exact match, simply enter into the text field(s) the correct text. The user's text will only validate if it exactly matches (from start to finish) what you enter. They can enter no more or less than what you type into the text field. For instance, if you entered "hello" into the text field, while leaving the "case sensitive" option unchecked, the respondent would have to enter "Hello", "hELLo", "hello" or some other case insensitive combination of hello for the validation to succeed. If they entered Hello Sir!" or anything else, it would fail. You can enter as much text as you like into the validation field which must be matched exactly. You can also force them to enter anything except a specific answer by changing the first select field to does not.


If your survey has multiple languages enabled, you must define a restriction for every language unless you want no restriction placed on respondents in that language. If you leave a language validation field blank, it will always pass this restriction without any errors when the survey is taken in that language.


Contains Phrase

This validation type is very similar to Exact Match. The only difference is that the user can enter any amount of text before and after the validation text that they wish. For instance, if you configured your text field validation to contain are you and checked the case sensitive option, the respondent could enter "Hello, how are you doing?" and it would be valid. If you checked the not option, then the validation will only succeed if users do not use the phrase are you anywhere in their text.


If your survey has multiple languages enabled, you must define a restriction for every language unless you want no restriction placed on respondents in that language. If you leave a language validation field blank, it will always pass this restriction without any errors when the survey is taken in that language.


Contains Keyword(s)

When selecting the keywords option, the user's entered text will be compared to see if it contains the keywords you specify. Keywords can be specified either separated by spaces or in a complex condition. For instance, if you simply entered today tomorrow as the keywords, we will require that the text the respondent enters contains both of these keywords. "I will do that today or tomorrow" would validate in the above scenario. Any keywords separated by only a space will have an implicit AND inserted between them. However, if you wanted to allow them to enter only one of those keywords, you could separate them with OR, such as today OR tomorrow.


Now the respondent will only need to enter one of those words into their response for it to be considered valid. Your keywords can contain any complex condition utilizing AND, OR, NOT and parenthesis. NOT must always come before parenthesis which surround the condition you wish to negate. For instance, if you entered:

NOT(today OR tomorrow) AND yesterday

This requires that the user's text contain the keyword yesterday, but that it does not contain either keywords today or tomorrow. The user could enter "I went to practice yesterday" which would validate as true, but if they entered "I went to practice yesterday and have it again tomorrow" it would not pass validation.


If you wish to use a phrase in keyword matching, or match on a restricted word such as "and", you may enclose the keyword or keyphrase in double quotes. For instance:

"or" AND "to be"

The above would pass on a phrase such as "to be or not to be", but would fail on "to be and not to be". If you failed to enclose the word "or" in double quotes, you would have entered an invalid keyword validation, as it would consider the bare word "or" to be a conditional statement. Similarly, failing to enclose "to be" in quotes would be invalid, as it would appear to be two keywords without a conditional joiner (AND, OR).


If your survey has multiple languages enabled, you must define a restriction for every language unless you want no restriction placed on respondents in that language. If you leave a language validation field blank, it will always pass this restriction without any errors when the survey is taken in that language.


Matches Regular Expression (PostgreSQL)

This validation type allows for many of the most complex text validations you can think of. The text you enter here must work when evaluated as a advanced regular expression within PostgreSQL. These regular expressions have much in common with those found in PHP, Perl and other programming languages, but you may want to read up on the documentation at the link above to ensure you understand any differences or to learn how to use regular expressions.


Let's say you want to allow the user to enter any number, but nothing other than a number should be allowed to match. You could enter the following:

^\-?(\d*\.?\d+|\d+\.?\d*)$

When this is evaluated, it will match if the user entered any of the following: 1, -2.5, 0.5, .7, -54., etc. We will break this regular expression down as a sample. The carrot ^ character that starts it out requires that the regular expression start at the beginning of the user's text. Without this, they could enter "test54" and it would match. Similarly, the dollar sign $ character at the end requires that the user's text end at the end of the regular expression as well. The \-? portion of the regular expression says to match the minus sign (you can and should escape non-alphanumeric characters when you want to match them literally) 0 or 1 times. We then require it to match either \d*\.?\d+ or \d+\.?\d*. Simply, this means to match any number of digits, followed by an optional period and at least one number or match at least one number, followed by an optional period and any number of digits.


You do not need to include the forward slash / characters around your expression as is often found in some programming languages. You must select whether your regular expression requires the user's text to match case (upper and lower) exactly or not. You can also check the option not to have your regular expression negated.


If this all sounds like gibberish, here are some links that may be of help:


POSIX regular expressions within PostgreSQL (comprehensive)

Wikipedia: Regular expression (overview and different implementations)


If your survey has multiple languages enabled, you must define a restriction for every language unless you want no restriction placed on respondents in that language. If you leave a language validation field blank, it will always pass this restriction without any errors when the survey is taken in that language.


Matches Numerical Expression

While the other types of text validation are great for matching languages, they lack the ability to specify that a number be greater than 10 and less than or equal to 100. That is where our numerical expression validator comes in. When you choose this type, you can use the following operators to create any custom numerical validation routine. This validation will always fail unless the user has entered a number as their text. Only then will it even attempt to run their input through the numerical expression you have defined.

< #: user response is less than '#'
<= #: user response is less than or equal to '#'
> #: user response is greater than '#'
>= #: user response is greater than or equal to '#'
== #: user response is equal to '#'
!= #: user response is not equal to '#'
% #: user response is not evenly divisible by '#'
isZero: user response is zero
isNegative: user response is negative
isDecimal: user response is decimal

Furthermore, just like the Contain Keyword(s) validation type discussed above, you may use NOT, AND, OR and parenthesis within your expression to control how it is evaluated. NOT should always be followed by parenthesis that enclose the portion of the expression you wish to negate. Although case sensitivity has no bearing on this type of text validation (it is all numbers) you still must select one of the options. The following are some examples of numerical expressions:

Must be less than 10 or greater than 100:
  < 10 OR > 100
Must be greater than or equal to 400:
  >= 400
Must be a leap year:
  NOT(% 4) AND (% 100 OR NOT(% 400))
Must be zero or a positive integer:
  NOT(isDecimal) AND NOT(isNegative)

The user entered number will be placed in front of each numerical comparison operator so you must have an operator followed by a number. Further comparisons must be separated by AND or OR, with NOT and parenthesis thrown in the mix where appropriate. Our software will notify you if it thinks you have entered an invalid numerical expression.


If your survey has multiple languages enabled, you must define a restriction for every language unless you want to only validate the response as numeric in that language. If you leave a language validation field blank, it will force the respondent to enter a number, but pass this restriction without any other errors.


[validate] Number

When you select this option, it forces the user to enter a valid number in order for the validation to be satisfied. Even if not is checked, the user will still have to enter a valid number — the not will simply act on the conditions you have specified for that number. You can check three options for the [validate] Number option:

Disallow Zero
Allow Negative
Allow Decimal

By default, if you check none of the above options, the respondent will be forced to enter an integer 0 or greater. If you wish to be more flexible in the type of numbers they can enter, you can select additional options. You can choose to allow negative or decimal numbers or even eliminate the ability to enter 0.


[validate] Email Address

Select this option if you wish to force the respondent to enter an email address that matches valid syntax. This will not completely rule out bad email addresses, as there is no simple check to see if an email address actually works. It will, however, require that the respondent enter something that could be a legitimate email address. You can also force the respondent to enter anything except a valid email address if you select this option and then check the not checkbox next to it.


[validate] Web Site Link (URL)

Select this option if you wish to force the respondent to enter a web site link (URL) that matches valid URL syntax, such as:

http://www.example.com/somepage.html