Creating a survey

When you start creating a survey you are first asked to enter a name and a description for your survey, and wether this survey should be public or not. Public surveys can be taken by anybody, even unregistered users, if the survey module itself is readible for everyone (check this in the site-map).

After confirming you are prompted to add a first question to the survey. You can do this now or click on the "Admin this Survey"-Link to skip this step for now.

Administrating a survey

Wether you add a question now or not afterwards you get to the administration menu for your new survey. Here you can adjust some more parameters, view and add questions and manage the results of a survey.

The first option is to enable or disable the survey. A disabled survey is not shown to users and cannot be answered to. This is the standard for newly created surveys. When you are done editing the survey and want it to become accessible to users, you need simply toggle this setting and all users that are allowed to take this survey will see it in their list of unifnished surveys.

Underneath this setting you can find the name and description of the survey. You can change these with the "Edit"-Button. "Preview" will give you a preview of the survey. Please note that for multi-sectioned and branched surveys this will display all sections on a single page.

The next block allows viewing the results of survey. This feature is described further below.

When you create a survey it is by default a single-section survey. That is, all questions will be presented to the user on one page. If you want to split very long survey to multiple pages or if you need to branch depending on the answers, you need to make the survey multi-sectioned.

In a multi-sectioned survey each section has a name and a description of their own, which can be edited like the ones for surveys. It is also possible to compress a multi-sectioned survey to a single-sectioned one. However, this is not encouraged and in some cases it is not even possible unless you change the sections accordingly.

For sectioned survey you can choose to display a status bar which illustrates the progress the user has made in a survey as a percentage of the survey. Single sectioned surveys do not have a status bar.

Underneath the status bar you can select the style to use for rendering the survey. These styles affect the layout of the complete survey. Predefined are four different styles. It is possible to further customize the layout of sections in the page for editing a section.

You can select several options for how a user can respond to a survey. The first option is to limit the user to one response per survey or allow answering multiple times to a survey. The second option is wether or not allowing a user to edit his old responses.

The display options (list/table/paragraph) are not yet functional. These will allow controlling the layout of surveys.

The section "Accessibility" allows you to control who can take a survey. At the moment this is limited to allowing the public access to the survey. Taking a survey requires the privilege "read" on the survey.

You can request notification whenever someone has answered to the survey, so you can instantly process the new response. You also have the possibility to send bulk mail concerning a survey, for example thanking everyone who has taken the survey or remind whoever has not yet filled in the survey to do so.

The last two options allow deleting a survey or making a copy of it. This is especially useful if you often have similar surveys that differ in details.

After the survey options you will find a list of all sections with their questions that are associated with this survey. If the survey is single-sectioned, the enclosing section will not be explicitly displayed.

Here you can edit the properties of sections, add new questions or reorder the existing questions by clicking on the up and down arrows.

Creating a question

There are different possibilities to add a new question to a survey. When starting the creation of a new survey you are prompted to enter a question. Later on you can always add new questions by selecting "add new Question" in a section or clicking "new" at a question. The difference between these two is that "New" will create the new question underneath the one you selected "New" at, "add new question" will just add at the end of this section.

You can enter a text for your question and decide, if aswering the question will be optional or required. Then you have to select a "presentation type".

There are different types of questions, and they require different types of presentation and different types of answers. The first step in creating a new question is choosing the presentation type. There are seven different type to choose here:

• One Line Answer - A question that requires the user to enter a word or a short phrase
• Essay Answer - A Textbox for entering larger texts
• Multiple Choice (Drop Down) - This presents the user a drop down list to choose one of several alternatives
• Multiple Choice (Radio Buttons) - This allows the user to choose one of several possible answers to a question by selecting a radio button
• Date - Presents the user an entry field for a date
• File Attachment - Allows uploading a file as the answer to a question

Depending on the choice for the presentation type, there are different further options for each type of question, further specifying the layout of the question. One Line and Essay answers need to specify the size of the input box, multiple choice questions need the choices from which to select the answer. This can be Yes/No, True/False (Not for checkbox questions) or an own set of responses. These have to be entered one choice per line in the textbox. For all questions you can select if the entry widget(s) should be displayed next to the question or below it.

Image answers

It is possible to add images for choices in multiple choice questions (radio buttons or checkboxes). The images that can be used for this reside in "/www/graphics/survey" To include, for example a smiley (file /www/graphics/survey/small_smiley1.gif) you just type "{small_smiley1.gif}" as a choice.

Making a multi-sectioned survey

If you are not only creating very short surveys you might want to split the survey into multiple sections. Another reason for sectioning a survey is the possibility to create branches, that are executed conditionally.

Once you have set the survey to multi-sectioned, you can add new sections to the survey by selecting "add new section". You can enter a name and a description for the section, as well as the position relative to the already existing sections.

If you indicate that this section should be a branch, this section will only be displayed, if a condition is met. After entering the data for the section, you will be prompted to select a condition. The possible conditions come from earlier questions in the survey that are multiple choice questions.

Conditions can be chosen from any multiple choice question, that stands before the current section. That way it is possible to base a branching decision at the end of a survey on a choice in the beginning of that survey or have two or more streams of a survey depending on an initial choice.

Editing a section

After the name of a section in a multi-sectioned survey you can find a link to edit the section properties. These are

• The section name - This will be spelled out in the head of the sections before the questions
• Section description - Actually this is not displayed anywhere
• Branch - If you select branching you will be asked to define a condition afterwards. See Branching for details
• Position - Specifies the order of sections in a survey. You can select after which sections this section shall be
• New Page after this section - If set to "No" multiple sections will be displayed on one page until the first section is met that requires a page break (regardless of wether it is actualy displayed ot not). A page break will automatically occur if the next section is a branch section and the question that determines the branch has not yet been answered.

Underneath this form there is a link to create or edit a custom template for rendering of this section. Like this it is possible for a designer to individually adapt the layout of the section.

For that purpose a default template will be generated which contains all the questions that are in the Survey. At the moment all survey styles feature a two-column layout with questions on the left and widgets on the right side. If you need a different layout you have to wrap it into a <tr><td colspan=2> tag inside of which you are free to place whatever layout you want.

The questions are already prefilled from the database, if you want, you can edit them to your needs. However, please do not change the <formwidget> and <formgroup> tags, which render the widgets that will be used for data entry unless you are very sure what you are doing and retain the original variable names. In general this should not be necessary.

The <formgroup> tags are for radio button and checkbox-groups. Inside these groups @formgroup.widget@ is used to display the radio button or checkbox and @formgroup.label@ holds the label of this option. For these especially holds what has been said before: Be careful with changing these.

"Apply" writes the template to the file system, from where it will be called every time this section is to be displayed. "Erase custom template" will delete the file and return to normal rendering of the section.

Underneath this form you will see a preview of the section. This uses the style selected for the survey, of course.

Please note that the predefined section templates are not tailored to every survey style but fit best with the Standard template. However, since you can modify everything, it should be easy to adapt them to match the rest of the survey, especially if you customize every section within the survey.

Measurement sections

Measurement sections are sections in which all questions are multiple choice questions and have the same set of possible answers. For example this could be a number of statements to which the user answering the survey could state "agree fully", "agree", "unsure", "disagree", "disagree heavily". Instead of typing all the same responses over and over again for each question, it is possible to create a measurement section.

You begin by creating a new section and add one question. Make it a Multiple Choice (Radio Buttons) and enter the choices you want for each of the questions. Then choose "edit" next to the name of the section. Set "Measurement section" to "yes". This first does a check, if this section can be made a meaurement section, that is, it only contains multiple choice (radio) questions that have all the same set of answers. If this check is positive, the section is transformed into a measurement section.

When adding new questions to a measurement section, you don't need to do much. you just enter the question text, the type, responses and the layout options are set automatically. Display also is affected by choosing a measurement section. The questions in such a section are arranged in a table with the answers given only once at the top for easier orientation.

The question catalogue

The question catalogue contains questions that are common to multiple surveys. They can be easily selected from a list to integrate them into a survey. However, they do not behave exactly as normal questions.

If a user has already answered a catalogue question in a previous survey, the answer he gave then will be preselected. Like that the user won't have to bother answering the same question multiple times.

Furthermore, catalogue questions have the option to associate special actions with them. These are updating a row in the database or executing tcl code. However, these catalogue questions can only be created by site-wide administrators, not by "normal" survey admins.

The definition of catalogue questions is done via the page "/wherever/survey/is/mounted/admin/predefined-question-admin". On this page you will find a list of the already defined catalogue questions. You can edit them there or create new ones.

The creation of catalogue questions is analogous to the creation of normal questions, only you have to select an action. If you select "Update DB", you have to give a table name, a column name and a Key column name to determine which DB row to update. If you want to write the answer as the new last name of a person into the database, for example, you would select table name: persons column: last_name key column: person_id The key column will always be matched against the user_id of the user filling out the survey.

The option "Execute Tcl-Code" ath the moment does the same as the option "Nothing". The exact behaviour of this option still has to be defined further. All options share, however, that previously given answers to a question will be prefilled. If the question is of the type "DB" and there has not yet been an answer to this question the value will be prefilled from the given DB row.