Validation

Custom validations can be inserted into survey utilizing the Responsive rendering style through the Client Validations option under the Survey menu:

On this page CSS and/or JavaScript code can be inserted for Illume Next to use on the rendering of every survey page.

To edit this page text:

1. Choose Survey, Custom CSS, Javascript from the Survey Designer menu.

2. Edit the page.

3. Click OK.

Custom CSS styles must be defined between style tags. DatStat advises naming custom CSS styles with a custom prefix (e.g. “.”) in order to avoid collision with the built-in DatStat survey styles.

Example of a custom CSS style:

<!--Custom CSS -->

<style>

.__myheader   {background:#999900;}

Custom JavaScript in Classic Rendering Style

For surveys rendering in the Classic rendering style (as opposed to Responsive) custom JavaScript may be inserted between script tags. This JavaScript code can either be inline or reference code in the Survey Resources. The JavaScript placed on this page cannot directly reference form elements because the content of this page is placed between the head HTML tags, however, form element objects can be passed as function arguments to JavaScript functions declared on this page.

Example of inline JavaScript:

<script language="JavaScript">

alert('Hello World');

</script>

Example of referencing JavaScript source from a resource:

<script language="JavaScript" src="SurveyResource/HelloWorld.js">

</script>

The subsequent pages provides information regarding how to insert a ranking validation, used to enforce that no single ranking is used more than once, and a sum check validation, which ensures that entered values sum to a defined total.  NOTE: Implementing the code provided in this article is supported in Classic/Default template surveys, as it relies on the prototype JavaScript library.  The specific code listed here cannot be implemented in a survey utilizing the Responsive template.  

Here is an example of a ranking question:

Here is an example of a sum check question:

Ranking and sum check validation is normally performed using a group of questions that are part of a question table. Ranking and sum check validation requires that the datatype of the questions be “Whole Numbers” or “Whole Numbers >= 0” and the display type of the questions be “Text Field” or “Select One – Poplist”.

In order to use Ranking/Sum Check validation, a survey must have originated from a version 4.7 survey template or higher, and the following conditions must be true:

• ClientValidation.js must be included as a survey resource.
• The survey must use a classic/default template, not a responsive template
• The following javascript code must be included on the Cascading Style Sheet(CSS)/JavaScript page:

<!-- Custom CSS -->

<style>
</style>

<!-- Custom JavaScript -->

<script type="text/javascript">
</script>

<script type="text/javascript">

// Include ClientValidation.js only if the DatStat object is defined
//

if (typeof(DatStat) != "undefined")

{
document.write('<script type="text/javascript" src="SurveyResource/ClientValidation.js"><\/script>');
}

</script>

The following example demonstrates how to add ranking validation:

• Make sure the survey you are editing adheres to the Survey requirements for using Ranking/Sum Check validation.
• Add 5 questions to a question table and set the variable names to ‘Q1’ through ‘Q5’.
• Make sure the data type of these questions is Whole Numbers and the display type is set to Text Field.
• Add a Text/HTML object IMMEDIATELY FOLLOWING all the ranking questions and/or the question table.
• Click the Source tab of the Text/HTML object created in the previous step and insert the following content:

[/mk_custom_list]

<script language="JavaScript">

DatStat.addClientValidationCheck(new DatStat.RankingValidation(

['{FormElement:P1}','{FormElement:P2}','{FormElement:P3}','{FormElement:P4}','{FormElement:P5}','{FormElement:P6}','{FormElement:P7}','{FormElement:P8}','{FormElement:P9}'],

'You must uniquely rank between 3 and 5 items.',

3,
5,
true
));

</script>

RankingValidation Parameters

The RankingValidation parameters are separated by commas and must appear in the order as listed below.

Question List Array

This value should be a comma-delimited list of single-quoted text values that are the form element names of the questions to be ranked all enclosed between beginning and end brackets (‘[‘ and ‘]’). The {FormElement:} tag is used to specify the form element names for each of the questions.

Example:

['{FormElement:Q1}', '{FormElement:Q2}', '{FormElement:Q3}' ]

Error Message

This is a text message enclosed in single-quotes. It is displayed if the user fails to uniquely rank the minimum and maximum number of items.

Required Minimum Rank Items

This is the minimum number of items that are required to be ranked. This number is adjusted to the number of question items displayed on the page if that number is less than the minimum. An error message will be displayed it the survey participant fails to uniquely rank this minimum number of items.

Maximum Rank Items

This is the maximum number of items that can be ranked. An error message will be displayed if the survey participant ranks more than this specified maximum.

Sequential Ranking

This is a true/false option. Set this option to true if you require ranking values to be sequential numbers starting with 1. This option is especially important if the ranking questions are of display type text field.

Warning Only (Optional)

This is a true/false option.  Set this option to true if you want the validation to be a warning only, with the ability to continue or to stay on the page and make changes.  This is also known as “soft” validation.  If this value is not specified, it will default to false.

The following example demonstrates how to add sum check validation.  In this example, let’s assume we want the sum of these questions to add up to 100.

<script language="JavaScript">

function setTotal(total, ok)

{
var display = document.getElementById("TOTAL");

if(!display || typeof display == 'undefined')
return;
display.innerHTML = total + "%";

if(ok)
display.style.color = 'green';
else
display.style.color = 'red';

}

DatStat.addClientValidationCheck(new DatStat.SumCheckValidation(

['{FormElement:Q7}', '{FormElement:Q8}', '{FormElement:Q9}'], /* Question array list */
100,   /* Minimum sum */
100,   /* Maximum sum */
true,
setTotal,  /* Callback function */

'Total must equal 100.  Current total is {0}.' /* Error Message */
));

</script>

SumCheckValidation Parameters

The SumCheckValidation parameters are separated by commas and must appear in the order as listed below.

Question List Array

This value should be a comma-delimited list of single-quoted text values that are the form element names of the questions to be ranked all enclosed between beginning and end brackets (‘[‘ and ‘]’). The {FormElement:} tag is normally used to specify the form element names for each of the questions.

Example:

['{FormElement:Q1}', '{FormElement:Q2}', '{FormElement:Q3}' ]

Minimum Allowed Sum

This is a numeric value that is the minimum allowed by the sum check validation code.  This value should be less than or equal to the maximum allowed sum (i.e. the next parameter).

Maximum Allowed Sum

This is a numeric value that is the maximum allowed by the sum check validation code.  This value should be greater than or equal to the minimum allowed sum (i.e. the previous parameter).

Callback Function

This is an optional argument. If not set to null, this argument should be a JavaScript function object that accepts 2 arguments:  1) the current running ‘total’; and 2) whether or not this value is ‘ok’ and fulfills the sum check minimum/maximum requirements.  This function is called whenever the sum of the questions changes.

Error Message

This is a text message enclosed in single-quotes.  It is displayed if the sum of the responses isn’t between the required minimum/maximum values.  This error message can contain the following tag: {0} which will be replaced with the current total.

Warning Only (Optional)

This is a true/false option.  Set this option to true if you want the validation to be a warning only, with the ability to continue or to stay on the page and make changes.  This is also known as “soft” validation.  If this value is not specified, it will default to false.