Questionnaire scripting

Event handlers

It is possible to define JavaScript either in the questionnaire script section, or in each questions individual script section.

Answer sheet event handlers

Answer sheet event handlers are defined by calling the .bind() method on the AnswerSheet object.

Example:

AnswerSheet.bind('beforeCompleted', function(ev, answerSheet, questionnaire) { /* put code here */ });

The lifetime of the event handler if defined in the questionnaire script section is the until the viewer is closed.

Notice that the questionnaire script section is not used if the questionnaire is reached by using GotoQuestionnaire.

If the event handler is called in a question script section, the lifetime is from visiting the page with the given question until the viewer is closed. It it therefore NOT recommended to attach answer sheet event handlers in a question script section.

The following sections describe the actual events available.

BeforeCompleted

AnswerSheet.bind('beforeCompleted', function(ev, answerSheet, questionnaire) { /* put code here */ });

This is called when the respondent clicks the "close" button, or when an countdown completes on the last page, but before the validation and sending the closeAnswerSheet command to the server.

AfterCompleted

AnswerSheet.bind('afterCompleted', function(ev, answerSheet, questionnaire) { /* put code here */ });

This is called after beforeCompletedhas completed.

BeforeMoveToNextPage

AnswerSheet.bind('beforeMoveToNextPage', function(ev, answerSheet, questionnaire) { /* put code here */ });

This is called before validation of the page before the moveToNextPage command is sent to the server.

BeforeMoveToPreviousPage

AnswerSheet.bind('beforeMoveToPreviousPage', function(ev, answerSheet, questionnaire) { /* put code here */ });

This is called before validation of the page before the moveToPreviousPage command is sent to the server.

BeforeMoveToFirstPage

AnswerSheet.bind('beforeMoveToFirstPage', function(ev, answerSheet, questionnaire) { /* put code here */ });

This is only used in the pre-viewer.

BeforeMoveToLastPage

AnswerSheet.bind('beforeMoveToLastPage', function(ev, answerSheet, questionnaire) { /* put code here */ });

This is only used in the pre-viewer.

BeforeShowPage

AnswerSheet.bind('beforeShowPage', function(ev, answerSheet, questionnaire) { /* put code here */ });

See #Sequence of events at new questions

AfterShowPage

AnswerSheet.bind('afterShowPage', function(ev, answerSheet, questionnaire, element) { /* put code here */ });

See #Sequence of events at new questions.

The element contains the top-most html element of the page that holds all of the questions. This element contains each questions top html element as a child.

AfterValidateQuestion

AnswerSheet.bind('afterValidateQuestion', function(ev, question, state) { state.valid = /* put code here */; });

See #Sequence of events at goto another question.

State is an object with 1 property .valid, which contains the result of the .validate() on each question. This may be updated during the call to afterValidateQuestionto overwrite the state.

AfterCreateDataState

AnswerSheet.bind('afterCreateDataState', function(ev, data) { /* put code here */ });

See #Sequence of events at goto another question.

The data contains the actual data that is sent to the server.

Question event handlers

Similar to the answersheet event handlers, it is also possible to specify events for each question.

Example:Question.bind('beforeShowQuestion', function(ev, question) { /* put code here*/ });

It is not possible to define these events in the questionnaire script section, only in each questions individual script section.

The lifetime of the event handler viewer proceeds to the next page.

The following sections describe the actual events available.

BeforeShowQuestion

Question.bind('beforeShowQuestion', function(ev, question) { /* put code here */ });

See #Sequence of events at new questions

AfterShowQuestion

Question.bind('afterShowQuestion', function(ev, question, element) { /* put code here */ });

See #Sequence of events at new questions.

The element contains the top-most html element of the page that holds the question.

AfterValidateQuestion

Question.bind('afterValidateQuestion', function(ev, question, state) { state.valid = /* put code here */; });

See #Sequence of events at goto another question.

State is an object with 1 property .valid, which contains the result of the .validate(). This may be updated during the call to afterValidateQuestionto overwrite the state.

AnswerChanged

Question.bind('answerChanged', function(ev, question) { /* put code here */ });

Question.bind('answerChanged', function(ev, question, subquestion) { /* put code here */ });

Whenever the respondent (or script) change the answers to a question, this event is called.

All grid-type questions will add the subquestion parameter on the call.

Reference other questions

It is possible to reference other questions on the same page, by using the Question Label of this other questions, example: Q1.attr('answerOptionColumns')

Sequence of events at new questions

The primary loop of updates occur when the viewer has visited the server (or is starting up) and got a new batch of questions to display

1. Got new questions to display

2. Update answer sheet state

3. Run individual question scripts

4. Execute each question beforeShowQuestionevent handlers

5. Execute beforeShowPage event handlers

6. Render html

7. Execute each question afterShowQuestion event handlers

8. Execute afterShowPageevent handlers

Sequence of events at goto another question

Once the viewer is asked to change page, a sequence of events occur before calling the server and getting the next questions to display.

Here shown for goto next page, but similar events happen for before,first and last.

1. Check if we can goto next page

2. Set state to Normal

3. Execute beforeMoveToNextPage event handlers

4. For each question:

5. Execute .validate() on question

6. Execute afterValidateQuestion answer sheet event handlers

7. Execute afterValidateQuestion question event handlers

8. After all questions are processed, and if determined valid

9. Execute createDataState() on each question

10. Execute afterCreateDataState event handlers

11. Send the moveToNextQuestion command to server with the data state

12. Trigger #Sequence of events at goto another question

Question API

Each question type has its own API.

To get an value stored on a question object use var value = question.attr('property');.

To set an value stored on a question object use question.attr('property', newvalue);.

Question

Properties

• string label {get; } - Get the question's label.

• array answerOptions {get; } - Return all answer options of the question.

• string template {get; set;} - Get or set the question's template.

• string text {get; } - Get the question's text.

• bool answerRequired {get; } - Get the status of the answer's required mode.

• int countdown {get; } - Get the number of seconds that user has to answer the question.

• int points {get; } - Get the number of reward point that user receive after complete the question.

• string errorMessage {get; set} - Get or set the error message of question.

type

TODO

style

TODO

layout

TODO

Functions

• object resetAnswer() - Clear all old answer of the question.

• bool validate() - All questions have a validate function, that can be overwritten. It should return true, if the state of the question is valid and can be transmitted to the server. Or false if not. • object createDataState() -

Multi Grid

Properties

• array subQuestions {get; } - Return all sub questions of the question.

• int minimumAnswers {get; set} - Get or set the minimum amount of answer options that the user must choose.

• int maximumAnswers {get; set} - Get or set the maximum amount of answer options that the user must choose.

• string resources.error.answerRequired {get; set} - Get or set the error message when user does not answer the question if it is required.

• string resources.error.inGridAnswerRequired {get; set} - Get or set the error message when user miss one of the options in a grid question.

• string resources.error.maximumAnswersRequired {get; set} - Get or set the error message when user choose more than the maximum amount of answer options.

• string resources.error.minimumAnswersRequired {get; set} -Get or set the error message when user choose less than the minimum amount of answer options.

Functions

TODO

Multi

Properties

• int answerOptionRows {get; set} - Get or set the number of rows of answer that display to user.

• int answerOptionColumns {get; set} - Get or set the number of columns of answer that display to user.

• int minimumAnswers {get; set} - Get or set the minimum amount of answer options that the user must choose.

• int maximumAnswers {get; set} - Get or set the maximum amount of answer options that the user must choose.

• bool openAnswerRequired {get; set} - Get or set the status of the open answer's required mode (user have to write some text in the open answer).

• string resources.error.answerRequired {get; set} - Get or set the error message when user does not answer the question if it is required.

• string resources.error.minimumAnswersRequired {get; set} - Get or set the error message when user choose less than the minimum amount of answer options.

• string resources.error.maximumAnswersRequired {get; set} - Get or set the error message when user choose more than the maximum amount of answer options.

Functions

TODO

Number

Properties

• bool allowDecimals {get; set} - Get or set the status of allowing decimals input.

• int minimum {get; set} - Get or set the minimum value can be entered.

• int maximum {get; set} - Get or set the maximum value can be entered.

• string resources.error.answerRequired {get; set} - Get or set the error message when user does not answer the question if it is required.

• string resources.error.minimumValueRequired {get; set} - Get or set the error message when user enter less than the minimum value required.

• string resources.error.maximumValueRequired {get; set} - Get or set the error message when user enter more than the maximum value required.

• string resources.error.numericValueRequired {get; set} - Get or set the error message when user enters text in a number question.

• string resources.error.numberOverflow {get; set} - Get or set the error message when user enters a number with too many digits.

• string resources.error.noDecimalValue {get; set} - Get or set the error message when user enters a number with too many digits.

Functions

TODO

Open

Properties

TODO

Functions

TODO

Page

Properties

TODO

Functions

TODO

Scale Grid

Properties

TODO

Functions

TODO

Scale

Properties

TODO

Functions

TODO

Single Grid

Properties

• array subQuestions {get; } - Return all sub questions of the question.

Functions

TODO

Single

Properties

• int answerOptionRows {get; set} - Get or set the number of rows of answer that display to user.

• int answerOptionColumns {get; set} - Get or set the number of columns of answer that display to user.

• bool openAnswerRequired {get; set} - Get or set the status of the open answer's required mode (user have to write some text in the open answer).

Functions

• getAnswer() - Get answer value .

• resetAnswer() - Clear all old answer of the question.

• setAnswer(object element "answer option to set") - Set answers.

• toggleAnswer() - Set toggle property for answer options.

Text Grid

Properties

TODO

Functions

TODO