Script language overview

In dotData you can use server side scripting. These are scripts you can use for making calculations, retrieving and storing values or manipulation question content and question display.

Note

For basic questionnaires, you don’t need to type code. Typing code is considered advanced use and is typically needed when the requirements of a questionnaire become more complex.

Client side scripting

Basics

For all basic question types, a simplefied event model is built into the page. No need for jQuery or other libraries is required in this form. All events in the respondents page trigger the FireUserEvent function which takes the following form:

<script>
function FireUserEvent(event, objectName) {
        if (event == 'init') {
                alert('the page has loaded, you can now answer the question');
        }
        if (event == 'validate') {
                alert('here you can validate your response before it is submitted');
                pageOK = false; // this line triggers blocking of the post
                pageMsg += 'the validation failed, please check your answer\n';
        }
}
</script>

Defined events

The following events are defined:

• init: indicates that the page finished loading (comparable with jQuery.ready)

• click: indicates an element was clicked

• changed: indicates the value of an element has changed

• validate: indicates that the page needs to be validated Using this, you can build validation in addition to the built-in validations supplied. Should a page not validate, you should set two values:

  • pageOK = false: this will indicate to the engine that the data is not ready to be posted to the server

  • pageMsg += ‘This is an error messagen’: this is the message that is displayed to the respondent

jQuery

The methods described above provide a simple basic way to do most of what you will need. Explicit inclusions of JavasScript libraries, or knowledge of JavaScript libraries, is not required. However if you are familiar with libraries such as jQuery, of course you are free to use those.

Server side scripting

This section focuses on server side-scripting. This is different from client-side scripting:

• client-side scripts provide functionality that run in browsers, typically made in JavaScript. These scripts are transferred to the browser and visible for any tech savvy user. This contains code that drives user interaction in the browser and validation of answers before they get posted to the server.

• server-side scripts provide functionality that run on the server. These scripts are not visible to the respondent. Typical use cases for these scripts are:

  • calculation of segmentations

  • provide quota balancing logic beyond what is available through the standard methods

  • manipulation of the content of what is visible to the respondent beyond what is available through standard methods

Pre-requisite

Pre-requisite of using scripting is that you know how to make a basic questionnaire and have some understanding of the notion of variable names. Knowledge about any existing scripting language (eg JavaScript, C#, Python) greatly helps.

Note

The built-in scripting language is built so it can be easily adapted by people who have experience with VBA, the application language built in to the Microsoft Office products. It is case-insensitive, meaning that the names of functions and objects can be typed with upper case, lower case or a mixture of those.

Getting started

You create a script by inserting an item into the questionnaire of type ‘script. After that you type the content of the script. A questionnaire can have zero or more script items. A script is executed when the script-item is next-in-flow within the list of questionnaire items.

Storing values

Often you want to store the result of your calculation for later use or for delivery into your dataset. Typically for this purpose a so-called punch variable is created. A punch variable is a strawman question that is not actually visible to the respondent but still contains data. Just like any visible question, punch variables can be of any type (text, numeric or an answer category).

First example

Suppose you have a question called ‘AGE’ where you ask the respondent his age bracket:

• < 18

• 18-30

• 30-40

• 40-50

• 50-60

• > 60

and you want to build logic on stratified age group (young, middle, old):

• young are people who answered < 18

• middle are people who answered 18-30, 30-40 or 40-50

• old are people who answered 50-60 or > 60

The steps to set up this script are as follows:

• STEP 1: create the punch variable holding the result

  You would create an item with these properties

  • name: ‘AgeGroup’

  • type: ‘Single Response’

  • categories: Young, Middle, Old

• STEP 2: place a script item after the Age question with the following content:

     Do Case
             Case Age = 1
                     StoreAnswer('AgeGroup', 1)
             Case InList(Age, 2, 4)
                     StoreAnswer('AgeGroup', 2)
             Case Age = 5 or Age = 6
                     StoreAnswer('AgeGroup', 3)
     EndCase

Note

Often there is more than one way to code your script. For instance in line 3 in the example above we use the InList function where in line 5 we just use an OR to make the expression.

You can find a full description of the language in the Language glossary.