Creating questionnaires¶

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.

Editing via markdown text format¶

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 questionnaire header¶

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:

redirect_url: The page the user is sent to when the questionnaire is complete
success_message: If the user is redirected to page within the signalbox site, an extra message which will appear in a banner at the head of the page after completion.
show_progress: Whether participants can see how far through the questionnaire they are
step_navigation: Whether links should be included allowing random access to each page within the questionnaire.
steps_are_sequential: If true, and step_navigation is enabled, then participants can only navigate ‘back’ within the questionnaire, and cannot skip forwards.

The questionnaire body¶

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 .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 of question 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 .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 .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 .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).

Defining a list of choices¶

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 .likert}
How happy are you?
>>>
1=Very happy
2=Miserable
~~~

Here the possible options are listed following “>>>” on separate lines, in the form score=label. Scores must be integers, and are the values saved when the user provides an answer.

Default options¶

To mark one option to be selected by default, insert a star in front of the value:

~~~{#range1to4 .likert}
Question text
>>>
*1=Happy is selected by default
2=2
3=3
4=Unhappy
~~~

Calculating and displaying summary scores from participant responses¶

For instruction questions, in place of a list of choices, it is possible to specify a score which will be computed from previous participant responses (a ScoreSheet). For example:

~~~{#summaryscoreexample .instruction}
Your total score is: {{totalscore}}
>>>
totalscore <- sum(variablename1 variablename2 variablename3 ...)
~~~

This question will compute the sum of variable1, 2 and 3, and display it where the {{totalscore}} marker is, within the question text. Again markdown formatting can be applied to scores.

Note: because answers must be saved in the database before being available for summary scores, be sure to specify this type of question on a page which comes after the variables to be used.

Remapping of scores¶

As notes, scoresheets allow you to specify summary scores from combinations of questions which the participant has already made. Sometimes, you might like to score responses in such a way that several of the options equate to the same value. You can achieve this by adding [int] after the score to be stored in the database:

~~~{#remappingexample .likert}
Question text
>>>
*1=Stores 1 in the database, and in scoresheets
2=Stores 2 in the database, and in scoresheets
3[2]=Stores 3 in the database, but scores 2 as part of scoresheets
~~~

Using the Django templating language¶

Signalbox uses the Django template language to render the text of a question as it is presented to the user. Several variables, including summary scores (see above) are available in the render context, and can be included with the {{varname}} syntax. Other more advanced features can also be used, for example to conditionally display text based on previous answers. For example:

~~~{#djangoteplateexample .instruction}
Your total score was: {{totalscore}}.
{% if totalscore > 10 %}Well done!{% endif %}
>>>
totalscore <- sum(variablename1 variablename2 variablename3)
~~~

This question computes {{totalscore}} and then uses it to conditionally display extra text in the question.

Other variables available as the text is rendered are:

Saved answers, accessed as: {{answers.variable_name}}.
The Reply object (e.g. You started this reply at: {{reply.started}}).
The User object (e.g. Your name is {{user.first_name}}).

A complete example¶

A complete example can be found in ask/fixtures/asker_text.md.

Creating questions¶

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:

Uninterruptible instruction (this speaks the text of the questions, but without allowing the user to ‘barge-in’and skip the text by pressing a key, as is the case with a normal instruction question.)
Listen (records audio of the user)
Hangup (speaks the text of the question and then ends the current call; it is required that the asker ends with a hangup question)

All questions can take an ‘audio’ attribute for use in IVR calls, for example:

~~~{#ivrexample .likert audio="http://www.example.com/audio.mp3"}
This text will be shown on the web, but http://www.example.com/audio.mp3 will be played over the telephone.
>>>
1=1
2=2
...
~~~

Repeating questions within a Questionnaire¶

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.

Approximate completion times for questionnaires¶

These are calculated by a method on the Asker (Questionnaire) model:

Displaying previous answers or summary scores in questions¶

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.