The system allows you to use templates for your error messages in custom validation. For each error type, various elements are filled in that can improve the information content of the messages you report to the respondents. Instead of simply using fixed strings for error messages, the ErrorTemplate function can be used to “plug in” information about the current question, like question texts, current answers etc.
ErrorTemplate
ErrorTemplate(spec)spec is a string with the template specification. Inside the spec string you may use different elements that are singled out with caret (^) as pre- and suffix, e.g.
^MISSING^Example:
SetQuestionErrorMessage(LangIDs.en, ErrorTemplate("^MISSING^ has not been answered."));This will set the text of the error message to "label(s) has not been answered"
Templates are available for all the standard validation. There are usually several versions of the templates, which differ in how they separate words when they are listed. Some only use commas, some use commas, but "and" or "or" between the last two items. "and"/"or" is also available in several languages, so e.g. in German they will be replaced with "und"/"oder" and so on.
Answer Required Checks
MissingRequiredError()
returns true when one or more required answers to a question are missing. The following template elements can be used when MissingRequiredError returns true:
Template | Description |
| MISSING | Labels of all questions that lack answers, comma separated. |
| MISSING_AND | Same as above, but with the word “and” separating the two last items. |
| MISSING_OR | Same as above, but with the word “or” separating the two last items. |
Example:
if(MissingRequiredError())
{
SetQuestionErrorMessage(LangIDs.en,
ErrorTemplate("Please select an answer for ^MISSING_AND^."));
}
Exclusivity Tests
ExclusivityError()
returns true if an exclusive answer ("single punch") in a multi has been selected together with any other alternative. The following template elements can be used when ExclusivityError returns true:
Template | Description |
| SEL_EXCL | The labels of all exclusive (single punch) answers that were selected. |
| SEL_EXCL_AND | Same as above, but with the word “and” separating the two last items. |
| SEL_EXCL_OR | Same as above, but with the word “or” separating the two last items. |
| SEL_NEXCL | The labels of all non-exclusive (multi punch) answers that were selected. |
| SEL_NEXCL_AND | Same as above, but with the word “and” separating the two last items. |
| SEL_NEXCL_OR | Same as above, but with the word “or” separating the two last items. |
| DEF_EXCL | The labels of all exclusive (single punch) answers, regardless of which of them that were selected. |
| DEF_EXCL_AND | Same as above, but with the word “and” separating the two last items. |
| DEF_EXCL_OR | Same as above, but with the word “or” separating the two last items. |
| DEF_NEXCL | The labels of all non-exclusive (multi punch) answers, regardless of which of them that were selected. |
| DEF_NEXCL_AND | Same as above, but with the word “and” separating the two last items. |
| DEF_NEXCL_OR | Same as above, but with the word “or” separating the two last items. |
Examples:
if(ExclusivityError())
{
SetQuestionErrorMessage(LangIDs.en,
ErrorTemplate("Please do not check ^SEL_EXCL_OR^ if you check other answers to the question."));
}
if(ExclusivityError())
{
SetQuestionErrorMessage(LangIDs.en,
ErrorTemplate("^DEF_EXCL_AND^ can not be combined with any of the other answers."));
}
Other Specify Checking
Note: These two functions will ONLY work when the option “Other-Specify checking: Check that BOTH checkbox and textbox have been completed for an Other-specify answer” has been selected in survey settings.
NotSpecifiedError()
returns true if an alternative in an Other-Specify construct has been selected/answered without filling in the associated "Specify" text box.
NotSelectedError()
returns true if a "Specify" value has been entered in the text box of an Other-Specify construct without selecting/answering the associated answer alternative.
The following template elements are defined when one of these functions returns true:
Template | Description |
| OTHER | Label of the alternative/input that requires specification in an Other-Specify construct. |
| SPEC | The specification |
Examples:
if(NotSpecifiedError())
{
SetQuestionErrorMessage(LangIDs.en,ErrorTemplate("Please specify if ^OTHER^ is chosen."));
}
if(NotSelectedError())
{
SetQuestionErrorMessage(LangIDs.en,
ErrorTemplate("If you specify ^OTHER^ then please select the ^OTHER^ option."));
}
Rank Order Tests
RankError()
returns true if the "Ordered" property has been selected for the form and the answers to the questions are non-numeric, do not start at 1 or are non-consecutive. The following template elements are defined when RankError returns true:
Template | Description |
| RANK_MIN | The label of the first member of the ranking scale, or 1 if the question is open ended. |
| RANK_MAX | The label of the nth member of the ranking scale, or n if the question is open ended, where n is the number of items to rank. |
Example:
if(RankError())
{
SetQuestionErrorMessage(LangIDs.en,
ErrorTemplate("Please enter consecutive answers in the range ^RANK_MIN^ to ^RANK_MAX^."));
}
Answer Size For Fixed Width Fields
SizeError()
returns true if one or more open-ended answers exceeds the maximum length specified in the field width. The following template elements are defined when SizeError returns true:
Template | Description |
| TOO_LONG | The labels of the inputs that were too long. |
| TOO_LONG_AND | Same as above, but with the word “and” separating the two last items. |
| MAX_SIZE | The maximum allowed size. |
Example:
if(SizeError())
{
SetQuestionErrorMessage(LangIDs.en,
ErrorTemplate("The answers to ^TOO_LONG_AND^ were longer than ^MAX_SIZE^ characters and have been truncated. Please review."));
}
Numeric Validation
NumericError()
returns true if the "Numeric" property has been selected and the answer is not numeric. The following template elements are defined when NumericError returns true:
Template | Description |
| NUMERIC_ERRORS | The labels of all elements with a numeric error. |
| NUMERIC_ERRORS_AND | Same as above, but with the word “and” separating the two last items. |
Example:
if(NumericError())
{
SetQuestionErrorMessage(LangIDs.en,
ErrorTemplate("Please make sure that the answers to ^NUMERIC_ERRORS^ are numbers only."));
}
Precision Error Tests
PrecisionError()
returns true if the "Numeric" property has been selected and the answer cannot be stored within the defined total digits. The following template elements are defined when PrecisionError returns true:
Template | Description |
| PRECISION | The defined total digits |
| PRECISION_ERRORS | The labels of all elements with a total digits error. |
| PRECISION_ERRORS_AND | Same as above, but with the word “and” separating the two last items. |
Example:
if(PrecisionError())
{
SetQuestionErrorMessage(LangIDs.en,
ErrorTemplate("Please enter a number with no more than ^PRECISION^ digits for ^PRECISION_ERRORS^."));
}
Scale Error Tests
ScaleError()
returns true if the "Numeric" property has been selected and the answer contains more decimals than in the defined decimal places. The following template elements are defined when ScaleError returns true:
Template | Description |
| SCALE | The defined decimal places |
| SCALE_ERRORS | The labels of all elements with to many decimals. |
| SCALE_ERRORS_AND | Same as above, but with the word “and” separating the two last items. |
Example:
if(ScaleError())
{
SetQuestionErrorMessage(LangIDs.en,
ErrorTemplate("Please enter answers with no more than ^SCALE^ decimals for ^SCALE_ERRORS_AND^."));
}
Range Error Tests
RangeError()
returns true if the "Numeric" property has been selected and the answer is outside the defined range. The following template elements are defined when RangeError returns true:
Template | Description |
| RANGE_MIN | The label of the defined minimum value. |
| RANGE_MAX | The label of the defined maximum value. |
| RANGE_ERRORS | The labels of all elements with too many decimals. |
| RANGE_ERRORS_AND | Same as above, but with the word “and” separating the two last items. |
Example:
if(RangeError())
{
SetQuestionErrorMessage(LangIDs.en,
ErrorTemplate("Please enter answers in the range ^RANGE_MIN^ to ^RANGE_MAX^."));
}
Note: If the survey is using a responsive layout, the client-side validation (which does not have details of numeric range boundaries) is executed before any custom validation. These template elements will therefore not function and the default error messages will be presented.
Columns in 3D grid
In 3D grids the CTITLE primitive is available to give the possibility of including the column header (question text) of the question in the error message.
Template | Description |
| CTITLE | The column header (question text) for the question in the 3D grid. |
Example:
if(f("q1").size() < 5)
{
SetQuestionErrorMessage(LangIDs.en,
ErrorTemplate("Please select at least 5 items for ^CTITLE^."));
}