View source for 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 <code class="mwt-code" >.bind()</code> method on the <code class="mwt-code" >AnswerSheet</code> object.

Example:

<code class="mwt-code" >AnswerSheet.bind('beforeCompleted', function(ev, answerSheet, questionnaire) { /* put code here */ });</code>

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|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 ===
<code class="mwt-code" >AnswerSheet.bind('beforeCompleted', function(ev, answerSheet, questionnaire) { /* put code here */ });</code>

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 <code class="mwt-code" >closeAnswerSheet</code> command to the server.
=== AfterCompleted ===
<code class="mwt-code" >AnswerSheet.bind('afterCompleted', function(ev, answerSheet, questionnaire) { /* put code here */ });</code>

This is called after <code class="mwt-code" >beforeCompleted</code>has completed.
=== BeforeMoveToNextPage ===
<code class="mwt-code" >AnswerSheet.bind('beforeMoveToNextPage', function(ev, answerSheet, questionnaire) { /* put code here */ });</code>

This is called before validation of the page before the <code class="mwt-code" >moveToNextPage</code> command is sent to the server.
=== BeforeMoveToPreviousPage ===
<code class="mwt-code" >AnswerSheet.bind('beforeMoveToPreviousPage', function(ev, answerSheet, questionnaire) { /* put code here */ });</code>

This is called before validation of the page before the <code class="mwt-code" >moveToPreviousPage</code> command is sent to the server.
=== BeforeMoveToFirstPage ===
<code class="mwt-code" >AnswerSheet.bind('beforeMoveToFirstPage', function(ev, answerSheet, questionnaire) { /* put code here */ });</code>

This is only used in the pre-viewer.
=== BeforeMoveToLastPage ===
<code class="mwt-code" >AnswerSheet.bind('beforeMoveToLastPage', function(ev, answerSheet, questionnaire) { /* put code here */ });</code>

This is only used in the pre-viewer.
=== BeforeShowPage ===
<code class="mwt-code" >AnswerSheet.bind('beforeShowPage', function(ev, answerSheet, questionnaire) { /* put code here */ });</code>

See [[#Sequence of events at new questions]]
=== AfterShowPage ===
<code class="mwt-code" >AnswerSheet.bind('afterShowPage', function(ev, answerSheet, questionnaire, element) { /* put code here */ });</code>

See [[#Sequence of events at new questions]].

The <code class="mwt-code" >element</code> 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 ===
<code class="mwt-code" >AnswerSheet.bind('afterValidateQuestion', function(ev, question, state) { state.valid = /* put code here */; });</code>

See [[#Sequence of events at goto another question]].

<code class="mwt-code" >State</code> is an object with 1 property <code class="mwt-code" >.valid</code>, which contains the result of the <code class="mwt-code" >.validate()</code> on each question. This may be updated during the call to <code class="mwt-code" >afterValidateQuestion</code>to overwrite the state.
=== AfterCreateDataState ===
<code class="mwt-code" >AnswerSheet.bind('afterCreateDataState', function(ev, data) { /* put code here */ });</code>

See [[#Sequence of events at goto another question]].

The <code class="mwt-code" >data</code> 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:<code class="mwt-code" >Question.bind('beforeShowQuestion', function(ev, question) { /* put code here*/ });</code>

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 ===
<code class="mwt-code" >Question.bind('beforeShowQuestion', function(ev, question) { /* put code here */ });</code>

See [[#Sequence of events at new questions]]
=== AfterShowQuestion ===
<code class="mwt-code" >Question.bind('afterShowQuestion', function(ev, question, element) { /* put code here */ });</code>

See [[#Sequence of events at new questions]].

The <code class="mwt-code" >element</code> contains the top-most html element of the page that holds the question.
=== AfterValidateQuestion ===
<code class="mwt-code" >Question.bind('afterValidateQuestion', function(ev, question, state) { state.valid = /* put code here */; });</code>

See [[#Sequence of events at goto another question]].

<code class="mwt-code" >State</code> is an object with 1 property <code class="mwt-code" >.valid</code>, which contains the result of the <code class="mwt-code" >.validate()</code>. This may be updated during the call to <code class="mwt-code" >afterValidateQuestion</code>to overwrite the state.
=== AnswerChanged ===
<code class="mwt-code" >Question.bind('answerChanged', function(ev, question) { /* put code here */ });</code>

<code class="mwt-code" >Question.bind('answerChanged', function(ev, question, subquestion) { /* put code here */ });</code>

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

All grid-type questions will add the <code class="mwt-code" >subquestion</code> 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: <code class="mwt-code" >Q1.attr('answerOptionColumns')</code>

== 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 <code class="mwt-code" >beforeShowQuestion</code>event handlers

5. Execute <code class="mwt-code" >beforeShowPage</code> event handlers

6. Render html

7. Execute each question <code class="mwt-code" >afterShowQuestion</code> event handlers

8. Execute <code class="mwt-code" >afterShowPage</code>event 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 <code class="mwt-code" >beforeMoveToNextPage</code> event handlers

4. For each question:

5. Execute .validate() on question

6. Execute <code class="mwt-code" >afterValidateQuestion</code> answer sheet event handlers 

7. Execute <code class="mwt-code" >afterValidateQuestion</code> question event handlers

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

9. Execute <code class="mwt-code" >createDataState()</code> on each question

10. Execute <code class="mwt-code" >afterCreateDataState</code> event handlers

11. Send the <code class="mwt-code" >moveToNextQuestion</code> 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 <code class="mwt-code">var value = question.attr('property');</code>.

To set an value stored on a question object use <code class="mwt-code">question.attr('property', newvalue);</code>.

== Question ==

=== <span style="color: rgb(230, 126, 35);">Properties</span> ===

'''<span style="color: rgb(35, 111, 161);">• string </span>label {get; }''' - Get the question's label.

'''<span style="color: #236fa1;">• Questionnaire.Models.AnswerOption.models </span>'''<span class="cm-string" style="box-sizing: inherit; color: #aa1111;"></span>'''answerOptions {get; } '''- Return all answer options of the question.

'''<span style="color: rgb(35, 111, 161);">•</span> <span style="color: rgb(35, 111, 161);">string</span> template {get; set;}''' - Get or set the question's template.

'''<span style="color: rgb(35, 111, 161);">•</span> <span style="color: rgb(35, 111, 161);">string</span> text {get; }''' - Get the question's text.

'''<span style="color: rgb(35, 111, 161);">•</span> <span style="color: rgb(35, 111, 161);">bool</span> answerRequired {get; }''' - Get the status of the answer's required mode.

'''<span style="color: rgb(35, 111, 161);">•</span>&nbsp;<span style="color: #236fa1;" >number </span>countdown {get; }''' - Get the number of seconds that user has to answer the question.

'''<span style="color: rgb(35, 111, 161);">• </span><span style="color: rgb(35, 111, 161);">number</span> points {get; }''' - Get the number of reward point that user receive after complete the question.

'''<span style="color: rgb(35, 111, 161);">• </span><span style="color: rgb(35, 111, 161);">string</span> errorMessage {get; set}''' - Get or set the error message of question.

'''<span style="color: #236fa1;">• </span><span style="color: #236fa1;">string</span> layout {get; }''' - Get the name of question layout.

'''<span style="color: #236fa1;">• </span><span style="color: #236fa1;" >number</span> type {get; }''' - Get the number of question type.
==== style ====
TODO

=== <span style="color: rgb(230, 126, 35);">Functions</span> ===

<span style="color: #236fa1;">
<span style="color: #000000;">'''<span style="color: rgb(35, 111, 161);">• </span>resetAnswer()''' - Clear all old answer of the question.</span></span>

<span style="color: #236fa1;">
<span style="color: #000000;">'''<span style="color: rgb(35, 111, 161);">• bool</span> 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.</span></span>

<span style="color: #236fa1;">
<span style="color: #000000;">'''<span style="color: rgb(35, 111, 161);">• object</span> createDataState()''' - Create data state for a question.</span></span>

== Multi Grid ==

=== <span style="color: rgb(230, 126, 35);">Properties</span> ===

'''<span style="color: rgb(35, 111, 161);">• Questionnaire.Models.SubQuestionClosed.models</span> subQuestions {get; } '''- Return all sub questions of the question.<p>'''<span style="color: rgb(35, 111, 161);">• number</span> minimumAnswers {get; set} '''- Get or set the minimum amount of answer options that the user must choose.</p>
<p>'''<span style="color: rgb(35, 111, 161);">• number</span> maximumAnswers {get; set} '''- Get or set the maximum amount of answer options that the user must choose.<br></p>
<p>'''<span style="color: #236fa1;">• array </span>defaultAnswer {set; } '''- Set default values for each sub questions. These values are separated by a semi-colon.<br></p>
<p>'''<span style="color: rgb(35, 111, 161);">• string</span> resources.error.inGridAnswerRequired''' '''{get; set} '''- Get or set the error message when user miss one of the options in a grid question.</p>
<p>'''<span style="color: #236fa1;">• string</span> resources.error.minimumAnswersRequired''' '''{get; set} '''- Get or set the error message when user choose less than the minimum amount of answer options.</p>
<p>'''<span style="color: rgb(35, 111, 161);">• string</span> resources.error.maximumAnswersRequired''' '''{get; set} '''- Get or set the error message when user choose more than the maximum amount of answer options.</p>

=== <span style="color: rgb(230, 126, 35);">Functions</span> ===

TODO

== Multi ==

=== <span style="color: rgb(230, 126, 35);">Properties</span> ===

'''<span style="color: #236fa1;">• </span><span style="color: rgb(35, 111, 161);">number</span> answerOptionRows {set; } '''- Set the number of rows of answer that display to user.

'''<span style="color: #236fa1;">•&nbsp;</span><span style="color: #236fa1;" >number</span> answerOptionColumns {set; } '''- Set the number of columns of answer that display to user.

'''<span style="color: #236fa1;">• </span><span style="color: rgb(35, 111, 161);">bool </span>autoArrangeAnswerOptions''' '''{set; } '''- Set the status of the auto arrange options.

'''<span style="color: #236fa1;">• bool </span>openAnswerRequired {set; }''' - Set the status of the open answer's required mode (user have to write some text in the open answer).

'''<span style="color: rgb(35, 111, 161);">•&nbsp;</span><span style="color: #236fa1;" >number</span> minimumAnswers {get; set}''' - Get or set the minimum amount of answer options that the user must choose.

'''<span style="color: rgb(35, 111, 161);">•&nbsp;</span><span style="color: #236fa1;" >number</span> maximumAnswers {get; set}''' - Get or set the maximum amount of answer options that the user must choose.

'''<span style="color: rgb(35, 111, 161);">• string</span> resources.error.answerRequired''' '''{get; set} '''- Get or set the error message when user does not answer the question if it is required.

'''<span style="color: #236fa1;">• </span><span style="color: #236fa1;">string</span> resources.error.minimumAnswersRequired {get; set}''' - Get or set the error message when user choose less than the minimum amount of answer options.

'''<span style="color: rgb(35, 111, 161);">• </span><span style="color: rgb(35, 111, 161);">string</span> resources.error.maximumAnswersRequired {get; set}''' - Get or set the error message when user choose more than the maximum amount of answer options.

=== <span style="color: rgb(230, 126, 35);">Functions</span> ===

'''<span style="color: #236fa1;">•</span> getAnswer()''' - Get answer value .

'''<span style="color: #236fa1;">•</span> setAnswer(<span style="color: #236fa1;">object </span>element '''"answer option to set"''') '''- Set answers.

'''<span style="color: #236fa1;">•</span> toggleAnswer(<span style="color: #236fa1;" >object </span>element '''"answer option to set"''')''' - Set toggle property for answer options.

== Number ==

=== <span style="color: rgb(230, 126, 35);">Properties</span><span style="color: rgb(230, 126, 35);"></span> ===

'''<span style="color: rgb(35, 111, 161);">• bool <span style="color: rgb(0, 0, 0);">allowDecimals {set; } </span></span>'''<span style="color: rgb(0, 0, 0);">- Set the status of allowing decimals input.</span>

'''<span style="color: rgb(35, 111, 161);">•</span> <span style="color: rgb(35, 111, 161);">number </span>minimum {get; set}''' - Get or set the minimum value can be entered.

'''<span style="color: rgb(35, 111, 161);">•</span> <span style="color: rgb(35, 111, 161);">number </span>maximum {get; set} '''- Get or set the maximum value can be entered.

'''<span style="color: #236fa1;">• </span><font color="#236fa1">string </font>unit {set; } '''- Set the text after the input box the user sees, usually used to nominate a unit.<p>'''• <span style="color: rgb(35, 111, 161);">string </span>resources.error.answerRequired {get; set} '''- Get or set the error message when user does not answer the question if it is required.</p>
<p>'''• <span style="color: rgb(35, 111, 161);">string</span> resources.error.minimumValueRequired {get; set}''' - Get or set the error message when user enter less than the minimum value required.</p>
<p>'''• <span style="color: rgb(35, 111, 161);">string</span> resources.error.maximumValueRequired {get; set} '''- Get or set the error message when user enter more than the maximum value required.</p>
<p>'''• <span style="color: #236fa1;">string </span>resources.error.numericValueRequired {get; set}''' - Get or set the error message when user enters text in a number question.</p>
<p>'''• <span style="color: #236fa1;">string </span>resources.error.numberOverflow {get; set} '''- Get or set the error message when user enters a number with too many digits.</p>
<p>'''<span style="color: rgb(0, 0, 0);"><span style="color: rgb(35, 111, 161);">• </span><span><span style="color: rgb(35, 111, 161);">string</span> resources.error.noDecimalValue </span>{get; set} </span>'''- Get or set the error message when user enters a decimal when a whole number is required.&nbsp;<br></p>

=== <span style="color: rgb(230, 126, 35);">Functions</span> ===

TODO

== Open ==

=== <span style="color: #e67e23;">Properties</span> ===

<p>'''<span style="color: rgb(35, 111, 161);">• number </span>answerOptionRows {set; } '''- Set the number of rows of answer that display to user.</p>
<p>'''<span style="color: rgb(35, 111, 161);">• number </span>answerOptionColumns {set; } '''- Set the number of columns of answer that display to user.</p>
<p>'''<span style="color: rgb(35, 111, 161);">• bool</span> autoArrangeAnswerOptions {set; } '''- Set the status of the auto arrange options.</p>
<p>'''<span style="color: rgb(35, 111, 161);">• number </span>minimumAnswers {set; }''' - Set the minimum amount of answer options that the user must choose.</p>
<p>'''<span style="color: rgb(35, 111, 161);">• number </span>maximumAnswers {set; }''' - Set the maximum amount of answer options that the user must choose.</p>
<p>'''<span style="color: rgb(35, 111, 161);">• string</span> resources.error.answerRequired {get; set}''' - Get or set the error message when user does not answer the question if it is required.</p>
<p>'''<span style="color: #236fa1;">• string </span>resources.error.minimumAnswersRequired {get; set}''' -Get or set the error message when user choose less than the minimum amount of answer options.</p>
<p>'''<span style="color: rgb(35, 111, 161);">• string </span>resources.error.maximumAnswersRequired {get; set}''' - Get or set the error message when user choose more than the maximum amount of answer options.</p>

=== <span style="color: rgb(230, 126, 35);">Functions</span> ===

'''<span style="color: rgb(0, 0, 0);" >• setAnswer</span>(<span style="color: rgb(35, 111, 161);" >object</span> element '''"answer option to set"''') '''- Set answers.

== Page ==

=== <span style="color: rgb(230, 126, 35);" >Properties</span> ===

TODO

=== <span style="color: rgb(230, 126, 35);" >Functions</span> ===

TODO

== Scale Grid ==

=== <span style="color: #e67e23;">Properties</span> ===

<span style="color: #e67e23;">'''<span style="color: #236fa1;">• Questionnaire.Models.SubQuestionScale.models <span style="color: rgb(0, 0, 0);">subQuestions {get; } </span></span>'''<span style="color: #236fa1;"><span style="color: rgb(0, 0, 0);">- Return all sub questions of the question.</span></span></span>
<span style="color: #e67e23;"><span style="color: rgb(0, 0, 0);"></span></span><span style="color: #236fa1;">
<span style="color: #e67e23;"><span style="color: #000000;"></span></span></span>
<p><span style="color: #236fa1;">
<span style="color: #e67e23;"><span style="color: #000000;">'''<span style="color: rgb(35, 111, 161);">• bool</span> discrete {set; }''' - User interger value for the scale bar.</span></span></span></p>
<p>'''<span style="color: #236fa1;">• number </span>minimum {get; }''' - Get the minimum value on scale bar.</p>
<p>'''<span style="color: #236fa1;">• number </span>maximum {get; } '''- Get the maximum value on scale bar.</p>
<p>'''<span style="color: #236fa1;">• string <span style="color: rgb(0, 0, 0);">minimumText</span></span> {get; }''' - Get the maximum text on scale bar.</p>
<p>'''<span style="color: #236fa1;">• string <span style="color: rgb(0, 0, 0);">maximumText</span></span> {get; }''' - Get the maximum text on scale bar.</p>
<p>'''<span style="color: #236fa1;">• number </span>step {set; } '''- Set the step between numbers.</p>
<p>'''<span style="color: rgb(35, 111, 161);">• string</span> resources.error.inGridAnswerRequired {get; set}''' - Get or set the error message when user miss one of the options in a grid question.&nbsp;</p>

=== <span style="color: #e67e23;">Functions</span> ===

TODO

== Scale ==

=== <span style="color: rgb(230, 126, 35);">Properties</span> ===

<p>'''<span style="color: rgb(35, 111, 161);">• bool <span style="color: rgb(0, 0, 0);">discrete {set; }</span></span>'''<span style="color: rgb(35, 111, 161);"><span style="color: rgb(0, 0, 0);"> - User interger value for the scale bar.</span></span></p>
<p>'''<span style="color: rgb(35, 111, 161);">• number </span>minimum {get; } '''- Get the minimum value on scale bar.</p>
<p>'''<span style="color: rgb(35, 111, 161);">• number </span>maximum {get; }''' - Get the maximum value on scale bar.</p>
<p>'''<span style="color: #236fa1;">• string <span style="color: rgb(0, 0, 0);">minimumText </span></span>{get; }''' - Get the maximum text on scale bar.</p>
<p>'''<span style="color: #236fa1;">• string </span>maximumText {get; }''' - Get the maximum text on scale bar.</p>
<p>'''<span style="color: rgb(35, 111, 161);">• number</span> step {set; } '''- Set the step between numbers.</p>
<p>'''<span style="color: rgb(35, 111, 161);">• string</span> resources.error.answerRequired {get; set}''' - Get or set the error message when user does not answer the question if it is required.&nbsp;</p>

=== <span style="color: rgb(230, 126, 35);">Functions</span> ===

TODO

== Single Grid ==

=== <span style="color: rgb(230, 126, 35);">Properties</span> ===

'''<span style="color: rgb(35, 111, 161);" >• </span><span style="color: rgb(35, 111, 161);">Questionnaire.Models.SubQuestionClosed.models</span> subQuestions {get; } -''' Return all sub questions of the question.

'''<span style="color: rgb(35, 111, 161);">• string </span>resources.error.inGridAnswerRequired {get; set}''' - Get or set the error message when user miss one of the options in a grid question.

=== <span style="color: rgb(230, 126, 35);">Functions</span> ===

TODO

== Single ==

=== <span style="color: rgb(230, 126, 35);">Properties</span> ===

'''<span style="color: rgb(35, 111, 161);">• </span><span style="color: rgb(35, 111, 161);">number</span> answerOptionRows {set; } '''- Set the number of rows of answer that display to user.

'''<span style="color: rgb(35, 111, 161);">• </span><span style="color: rgb(35, 111, 161);">number</span> answerOptionColumns {set; } '''- Set the number of columns of answer that display to user.

'''<span style="color: rgb(35, 111, 161);"><span>• </span>bool</span> autoArrangeAnswerOptions''' '''{set; } - '''Set the status of the auto arrange options.

'''<span style="color: rgb(35, 111, 161);">• </span><span style="color: rgb(35, 111, 161);">bool</span> openAnswerRequired {set; }''' - Set the status of the open answer's required mode (user have to write some text in the open answer).

'''<span style="color: rgb(35, 111, 161);">• string</span> resources.error.answerRequired {get; set} '''- Get or set the error message when user does not answer the question if it is required.

=== <span style="color: rgb(230, 126, 35);">Functions</span> ===

'''<span style="color: rgb(35, 111, 161);">•</span> getAnswer()''' - Get answer value .

'''<span style="color: rgb(35, 111, 161);">•</span> setAnswer(<span style="color: rgb(35, 111, 161);">object </span>element '''"answer option to set"''') '''- Set answers.

'''<span style="color: rgb(35, 111, 161);">•</span> toggleAnswer()''' - Set toggle property for answer options.<span style="color: #236fa1;"></span>

== Text Grid ==

=== <span style="color: #e67e23;">Properties</span>'''<span style="color: rgb(35, 111, 161);"></span>''' ===

<p>'''<span style="color: rgb(35, 111, 161);">• Questionnaire.Models.SubQuestionOpen.models</span> subQuestions {get; } -''' Return all sub questions of the question.</p>
<p>'''<span style="color: #236fa1;">• string</span> unit {set; } '''- Set the text after the input box the user sees, usually used to nominate a unit</p>
'''<span style="color: rgb(35, 111, 161);">• string </span>resources.error.inGridAnswerRequired {get; set}''' - Get or set the error message when user miss one of the options in a grid question.

'''<span style="color: #236fa1;">• string </span>resources.error.illegalType {get; set}''' - Get or set the error message when user enters invalid type.<br><p>'''<span style="color: rgb(35, 111, 161);">• </span><span><span style="color: rgb(35, 111, 161);">string </span>resources.error.noDecimalValue </span>{get; set} '''- Get or set the error message when user enters a decimal when a whole number is required.<br></p>

=== <span style="color: #e67e23;">Functions</span> ===
<span style="color: rgb(0, 0, 0);">TODO</span>

== Text ==
=== <span style="color: #e67e23;">Properties</span> ===

<p>'''<span style="color: #236fa1;">• string</span> unit {set; } '''- Set the text after the input box the user sees, usually used to nominate a unit.</p>
'''<span style="color: rgb(35, 111, 161);">• string</span> resources.error.answerRequired {get; set} '''- Get or set the error message when user does not answer the question if it is required.

=== <span style="color: #e67e23;">Functions</span> ===
<span style="color: rgb(0, 0, 0);" >TODO</span>