The Ask application deals with creating and displaying questionnaires.
Questionnaires can be spread across multiple pages, and consist of questions. Questions can also be grouped into Instruments, which can be placed in a block into a page. Questions will often refer to ChoiceSets (groups of discreet options), e.g. for likert type responses.
To enable rapid editing of questionnaires, a text-based format is available in which titles, questions and choice-sets can be specified, and which are converted into Asker, Question and ChoiceSet objects in the database. This text format is based on [markdown](http://johnmacfarlane.net/pandoc/demo/example9/pandocs-markdown.html).
The text to edit questionnaires comes in two blocks: the header, which specifies details of the questionnaire as a whole, and the body which contains individual questions and choicesets.
The header is formatted as follows:
---
name: "Name of the questionnaire here"
slug: "examplequestionnaire"
redirect_url: "http://www.example.com"
show_progress: false
step_navigation: true
steps_are_sequential: true
success_message: "Thanks for completing this questionnaire."
---
The name and slug attributes identify the questionnaire — the slug being a short identifier which can be used in url links. The other fields are as follows:
Questions themselves are defined in what are called ‘fenced code blocks’ in Markdown. For example:
~~~
This the simplest type of 'question' - an instruction. No responses will be collected here.
~~~
When this is saved, you’ll notice that the system adds some attributes to the block to enable it to be identified in the database later for editing. So, the example above would get transformed into:
~~~{#ecVhsaj7889ij type="instruction"}
This the simplest type of 'question' - an instruction. No responses will be collected here.
~~~
Here, a variable name has been added (ecVhsaj7889ij) and the `type`specified for clarity. To add other types of questions you will need to manually specify the type, and optionally also the variable name for example:
~~~{#howoldareyou type="integer"}
How old are you, in years?
~~~
This would create an html question which requires an integer answer to be entered in a small text box. Some questions (including integer questions) have optional attributes. For example:
~~~{#howoldareyou type="integer" min="12" max="120"}
How old are you, in years?
~~~
In the example above we add a min and max attribute to validate against some typos. The text of questions can itself include markdown formatting to create headings, emphaisis or links within a questionnaire. For example:
~~~{#howoldareyou type="integer" min="12" max="120"}
# Demographic information
How old are you, ***in years***?
~~~
In the example above, a level-1 heading (Demographic information) is inserted, and the text ‘in years’ is formatted in bold and italic. For more information on [markdown formatting see the guide here](XXX).
Some questions require users to select from a restrcited range of choices, for example a likert-type scale. To specify the choices, specify a choiceset attribute on the question, and define the choiceset in a second, separate block:
~~~{#howhappyareyou type="likert" choiceset="range1to4"}
How happy are you?
~~~
~~~{#range1to4 .choiceset}
1=Happy
2=2
3=3
4=Unhappy
~~~
Here the name of the choiceset is marked with a # symbol (as for variable names for questions) and possible options are listed on separate lines, in the form score=label. Scores must be integers, and are the values saved when the user provides an answer (although note that answers are saved as strings in the database, and value labels are exported as part of the data-download functions too).
To mark one option to be selected by default, insert a star in front of the value:
~~~{#range1to4 .choiceset}
*1=Happy is selected by default
2=2
3=3
4=Unhappy
~~~
A slider element which allows users to pick a value between a min and a max which are specified as additional attributes. E.g.:
~~~{#variablename type="slider" min=0 max=100 value=50}
Slide the slider to a value between 0 and 100 (this slider defaults to 50).
~~~
Or if you want a slider with two movable points to specify a range of values:
~~~{#variablename type="slider" min=0 max=100 values=[10,90]}
Slide the slider to encompass a range of values between 0 and 100 (this slider defaults to the range 10-90).
~~~
Questions are created by using django form field elements, and extending them with additional information required by signalbox. The types of questions which can be created are documented here: Types of questions (Field classes)
The fields and widgets are as described in the floppyforms documentation: http://django-floppyforms.readthedocs.org/en/latest/widgets-reference.html
In addition, for IVR telephone calls, there are:
Each question must have unique variable name which will be used to identify data collected. If a question is to be repeated within a questionnaire, it should either be duplicated and given a second, different, name, or placed within an Instrument, and that Instrument given a prefix.
These are calculated by a method on the Asker (Questionnaire) model:
Read about ScoreSheets first.
Summary scores or previous questionnaire responses can be included on later pages, using the curly brace markers {{}}:
~~~
This will include an instruction displaying the users user response to a variable named howoldareyou:
{{answers.howoldareyou}}
~~~
Or to show a summary score:
~~~
{{scores.summary_score_name}}
~~~
Be sure to enable a particular summary score for your Questionnaire on the main editing page - it won’t be available unless you do.
Instruments are packages fo questions which can be placed as a unit within a questionnaire, e.g. for a psychometric scales which will be used in multiple studies.
A useful property of instruments embedded within questionnaires is the ability to make all questions required or not-required with a single checkbox. This can be turned on once testing is over to ensure participants complete all questions.