Adding Ranking Validation

Home / DatStat Illume Product Documentation / Validation / Adding Ranking Validation

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:


<script language="JavaScript">

DatStat.addClientValidationCheck(new DatStat.RankingValidation(


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



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.


['{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.