Survey application tutorial

Welcome to the survey app tutorial. This tutorial will guide guide you through the process of setting up and conducting an email survey using the Project Assignment Website. The survey process is split into three stages, namely

1. Initialization phase, where the survey parameters, the data capture form, and the participants are defined
2. Participation phase, where the participants are able to log in and enter their data
3. Closed phase, where the survey is closed and no more data can be added or edited by the participants.

To demonstrate the typical survey work flow, this tutorial will show how to conduct survey as to determine guests dietary preferences.

Before the tutorial begins, some of the major features of survey app are discussed. These features being

• a flexible data capture form, allowing multiple questions to be asked each of which has its own widget type (text box, choice box), and input validation.
• an emailing system with authentication links, which give each participant a unique link which allows them to upload/edit only their own data.
• an email communication system, with various options for selecting which participants the emails are sent to.

Initializing the survey

Log into the Django administrative interface at https://mecheng.up.ac.za/admin/survey/survey/ and add a new survey to begin the process. The main Survey object itself only has four fields

• Description : description of survey, which is used in heading text of the majority of the survey views. So for the dinner party survey, a value such as Dietary preferences survey although boring is appropriate.

• Stage : This value controls the stage of the survey, and should only be edited if survey stage needs to be manually rolled back.

• Preamble template : Django template for message shown before the data capture form. The template variables are the participant (fields available: firstName, initials, lastName ), survey (fields defined in this list). For this Dietary preferences survey, the following is used

  {{ participant.firstName }}  <br />  <br />
  
  We are hosting a dinner party to celebrate Foo day, please take a moment to complete this survey in order to assist us with our preparations.
  
  <br><br>
  Hope to cu there

  For information on how Django templates work, visit https://docs.djangoproject.com/en/1.3/topics/templates/

• Postamble template : Django template for message shown below the data capture form.

Click the save and continue editing button to save your progress. That's it, the main Survey object has now been created, what follows next is the creation of the data capture form

Creating a data capture form

In the Django admin interface, in the Dietary preferences survey edit form, you will see a table with the heading survey fields. This table is used to define the data capture form. For the dinner party survey, the table values used for this tutorial are as follows

Description	Input Type	Input type args	Widget Attrs	Long Description
attending	ChoiceField	yes, no		Would you be able to attend the dinner party?
guests	IntegerField	0,3,0	size=6	How many additional friends are you bringing with you to the party?
special dietary needs	textArea	5000	cols=50, rows=5

The meaning of the comma separated input type args, which dependent the Input type, are listed below:

• Each of the ChoiceField args represent a choice option
• IntegerField args are default, max, min. If only zero args are given no default or bounds are set, if only one arg is passed only the default is set ...
• CharField, textArea args are default value and the maximum length. In the case of special dietary needs row above the first arg (ie the default value arg) is length 0, and therefore a blank entry value is allowed by the form validator

The best way to understand the effects for the different options is to preview their effects using the preview view. This can be accessed from the main survey administration pages https://mecheng.up.ac.za/surveys/. From this view follow the link to the survey which you just created. Under this administration page, follow the Preview link which allows the data capture form to be previewed as well as the input validation to be checked.

Tip: whats rather useful when defining the capture form, is to have two browsers open side by side. One browser open in the Django admin interface editing the survey definition, the other browser previewing the result form. Then definition can then be edited (hit save and continue editing) and then refresh the preview browser to quickly and test out the result.

Defining and editing participants

The survey application is design to administered the participants through a CSV file. All the instructions needed are available under the upload participants under the participants heading on the admin survey page. Once the participants are defined, its time to start the participation stage. For testing purposes why not enter you own details?

Participation Stage

To initiate the participation, follow the Initiate survey by emailing participants link under the actions headings.

Note that the emails which are sent using the survey app, are sent with the from field value from your Django user accounts email value. There are various email options available which may prove useful. Also to cc multiple addresses use comma separatation i.e. bob@smith, may@holiday, using a cc value such as Bobby <bob@smith> will most likely crash the system.

In order to add additional participants to the survey, update the participants CSV file and upload the data using the upload participants under the participants heading. Then use the email action link, to email participants who have not been emailed before.

As the participants fill in their data, it will appear in the results table at the end of the survey administration page.

Closing the Survey

After a reasonable period of time, close the survey using the close survey link under the actions heading. This helps to avoid situations where data is entered after analysis of the results is completed. If its desired to re-open the survey, this can be done by editing the module definition and setting the stage from 2 back to 1.

In terms of analyzing the result data, two options are available. The first is use the filters on the results table shown on the administer survey page, to extract the desired data. The alternative option is to download the results table as a CSV, and analyse the results from there.