Overview of Ranking and Sum Check validation

Ranking validation requires survey participants to enter sequential numeric responses for a minimum and/or maximum number of question items. Here is an example of a ranking question:

Sum check validation requires survey participants to enter numeric values for a group of questions whose sum equals some value or is between some specified minimum and maximum values. JavaScript code can also be supplied to update a running total that is displayed in the survey. Here is an example of a sum check question:

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

In order to use Ranking/Sum Check validation, Multi-Control component validation, or other custom client validation,
a survey must have originated from a version 4.7 survey template or the following conditions must be true:

• ClientValidation.js must be included as a survey resource.
• The following javascript code must be included on the Cascading Style Sheet(CSS)/JavaScript page:
  
  

  <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 aheres 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 type="text/javascript">
     DatStat.addClientValidationCheck(new DatStat.RankingValidation(
         ['{FormElement:Q1}', '{FormElement:Q2}', '{FormElement:Q3}', '{FormElement:Q4}',
          '{FormElement:Q5}'], /* Question List Array */
         'You must uniquely rank between 3 and 5 items.',    /* Error Message */
         3,      /* Required minimum rank items */
         5,      /* Maximum rank items */
         true   /* Sequential ranking (true or false) */
         ));
  </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 normally 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.

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.

• Make sure the survey you are editing aheres 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.
• Click the Source tab of the question table Instructions field and append the following HTML content that allows for a running total to be displayed:
  
  <P>Current Total: <SPAN id=TOTAL style="FONT-WEIGHT: bold;COLOR: red"></SPAN>
  
  
• Add a Text/HTML object IMMEDIATELY FOLLOWING the question table created above.

• Click the Source tab of the Text/HTML object created in the previous step and insert the following content:
  
  <script type="text/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:Q1}', '{FormElement:Q2}', '{FormElement:Q3}','{FormElement:Q4}',
     '{FormElement:Q5}'], /* Question array list */
    100,   /* Minimum sum */
    100,   /* Maximum sum */
    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.