[[TOC]]
= Survey Module =
The survey module is used to generate and analyse surveys.
== The data model ==
[[Image(wiki:BluePrint/SurveyTool/ADAT:survey_implementation.png)]]
=== survey_template ===
The template is the root table and acts as a container for the questions that will be used in a survey.

=== survey_sections ===
The questions can be grouped into sections this provides the description of the section and the position of the section within the template

=== survey_question ===
This holds the actual question and a unique string code is used to identify the question. The type of question is also set here. More details of the questions can be found on the section of [#types (Question Types)]

It is possible for the same question to be used in different templates. If this is done then analysis across templates becomes possible, although this has not yet been implemented.

=== survey_question_metadata ===
This is used to hold additional details of the question. The valid metadata that can be stored will be defined by the [#types (question type)].

For example: if the question type is option, then valid metadata might be:
||= Key =||= Descriptions =||= Value =||
||count || the number of options that will be presented || 3 ||
|| 1 || the first option || Female ||
|| 2 || the second option || Male ||
|| 3 || the third option || Not Specified ||

So in the above case a question record will be associated with four question_metadata records. 

=== survey_question_list ===
The survey_question_list table is a resolver between the survey_question and the survey_section tables.

Along with ids mapping back to these tables it will have a code that can be used to reference the question it will have the position that the question will appear in the template.

=== survey_series ===
The survey_series table is used to hold all uses of a template

When a series is first created the template status will change from
Pending to Active and at the stage no further changes to the
template can be made.

Typically a series will be created for an event, which may be a
response to a natural disaster, an exercise,
or regular data collection activity.

The series is a container for all the responses for the event

=== survey_complete ===
The survey_complete table holds all of the answers for a completed
response. It has a link back to the series this response belongs to.

Whilst this table holds all of the answers in a text field during
the onaccept each answer is extracted and then stored in the
survey_answer table. This process of moving the answers to a 
separate table makes it easier to analyse the answers
for a given question across all responses.

=== survey_answer ===
The survey_answer table holds the answer for a single response of a given question.

== The Question Types [=#types]==
== The Question Widgets ==
== Code Overview ==
=== modules/s3/s3survey.py ===
=== models/survey.py ===
=== controllers/survey.py ===
== Terminology Used ==
 * assessment the response to a single questionnaire used in the survey
 * questionnaire the list of questions (I think of it as the physical piece of paper that needs to be filled in, whilst the assessment includes both the questionnaire and the answers)
 * series is a survey that has been set up for a particular event and holds all of the responses to the assessments
 * template is a list or each question that will be held in the questionnaire and a template can be shared across series, thus we can have many series using the same template and in the future it may be possible to do some analysis across series that share the same template.
 * widget all question types are managed by widgets, one to validate and display the data in a form the other to analyse and produce charts