Socrates QE: Questionnaire HOWTO

Duco Dokter

Revision History
Revision $Revision: 1.3 $$Date: 2003/10/16 21:55:02 $$Author: wyldebeast $
Initial draft

Table of Contents

Introduction
The Socrates questionnaire DTD
questionnaire
rendering
questionnaire-flow
answer-set
section
item
question
answer
option
flow-choice
Incorporating Multi-Media
Using the questionnaire to obtain a score
Timing

Introduction

This document describes how to create a questionnaire that can be rendered by the Socrates Questionnaire Engine. The engine handles questionnaires defined in XML format, according to a specific DTD. This document will explain the DTD, and explain how to use the DTD to create your own questionnaire. It should be made very clear however, that Socrates is just a rendering framework, not the rendering per se. The actual rendering is up to the user, who defines rendering by creating Velocity templates, or XSL stylesheets.

The Socrates questionnaire DTD

The Socrates questionnaire DTD is roughly structured as follows: questionnaire : section* section : item* item : question answer item* answer : option* or in words: a questionnaire consists of sections, a section consists of items. An item in general is a question, and a set of possible answers. In the case of Socrates, this is defined as an answer, that is either a list of options, or a reference to a predefined answer. Furtheron, the questionnaire holds information on rendering and the flow of the questionnare (if question X is answered as A, skip question Y). Following sections will describe the DTD elements and their attributes in more detail.

questionnaire

Definition: 
!ELEMENT questionnaire 
	  (description, author?, rendering?, questionnaire-flow, answer-set?, section*) 

!ATTLIST questionnaire
	id      ID    #REQUIRED
	name    CDATA #REQUIRED
	version CDATA #IMPLIED

Element

The root element for the questionnaire. The element can hold a description of the questionnaire, to be renderd for instance on the opening page. The questionnaire element can also hold information on rendering, flow and the required predefined answer sets. Finally, the questionnaire consists of a number of sections (or just one for that matter).

Attributes

The questionnaire has the following attributes:
id

Unique identifier for this questionnaire within user scope

name

Unique name within user scope

version

Several versions of a questionnaire may coexist. This can be used for sequential surveys, for example to redo a survey every year.

rendering

Definition: 
!ELEMENT rendering EMPTY 
!ATTLIST rendering
	class	             (Item|Section|Questionnaire) "Section"
	number	             CDATA                        #IMPLIED
	timeout	             CDATA                        #IMPLIED
	timed                (true|false)                 "false"	
	section-random-order (true|false)                 "false"
	item-random-order    (true|false)                 "false"
	answer-random-order  (true|false)                 "false"
	random-select        CDATA                        #IMPLIED
Although you might wonder what rendering information is doing in then XML definition, we need to define at least _some_ rendering information. Again, it is up to the implementing application to decide what to do with this info.

Element

The rendering element is empty; only it's attributes are used.

Attributes

class

What constitutes a page: item, section or questionnaire.

number

How many of them per page

timed

Should timing info be kept? This would maintain time information per page. See the section on timing for more details

timout

Should the page time out?

section-random-order

Should sections be randomly ordered?

item-random-order

Should items be randomly ordered?

answer-random-order

Should answers be randomly ordered?

random-select

Select a number of 'things' from the rendering class; if class is Section, this means a number of items, if class is Questionnaire, it is a number of sections. The value for this attribute is the number of 'things' to select.

questionnaire-flow

Definition: 
!ELEMENT questionnaire-flow ( flow-choice* ) 
!ATTLIST questionnaire-flow
The questionnaire flow holds all the flow choices. This means information on skipping certain items. The element is a container for flow choices.

Element

Attributes

answer-set

Definition: 

!ELEMENT answer-set (answer*)
The answer-set is a container of predefined answer sets.

section

Definition: 
!ELEMENT section (description, author?, item*)
!ATTLIST section
	id          ID #REQUIRED
	name        CDATA #IMPLIED
The section element is the second organizational unit, next to the questionnaire. The use is very simple: if you need sections, here's your tag. If you don't, you'll have to specify at least one section, to contain your questions.

Element

The section holds a description and a number of items.

Attributes

id

Unique id within the questionnaire

name

A preferrably unique name within the questionnaire. This can be used as the section title for istance.

item

Definition: 
!ELEMENT item (question, description, answer, item*, client-side-action*) 
!ATTLIST item
	id                 ID     #REQUIRED
	label              CDATA  #REQUIRED
        type	           ( multiple-select | single-select | open | custom ) "open"
	custom-type        CDATA  #IMPLIED
        render-type        (radio | select | check | text | textbox ) #REQUIRED
        category           CDATA  #IMPLIED
        weigth             CDATA  #IMPLIED
	required           (true|false) "false"
	semi-close         (true|false) "false"
	semi-close-prefix  CDATA  #IMPLIED
The item may well be the core element of the questionnaire: it contains the actual question and it's possible answers (or references to them).

Element

The item holds a question, and may have an additional description. The latter can for instance contain info to be rendered in a tooltip, etc. The item element has all the information on a question. In a special case, the item can contain just about anything, for instance an image some text, etc. This enables incorporation of for instance multi-media. See section 3.0 for details. The item can have sub items, that will than share the other attributes of the item, like it's answer set.

Attributes

id

Unique id within the questionnaire

label

Must be unique within the scope of a questionnaire. This can be used as a variable name in the naming of elements and in javascript code.

type

What kind of question is this? In case of custom, it's up to the the user to define the required action in this case. The custom-type can than be used to provide a user specified type.

custom-type

User defined type.

render-type

One of: radio, select, check, text, textbox. We couldn't think of any other, but let us know.

category

Assign a category to this question. This can be used for example to measures scores over a full questionnaire per category.

weight

Assign a weight to this question. Can be used to calculate overall score for a questionnaire. See the section on scores.

required

Is the question required

semi-close

Can be used to tell the renderer to render an extra text field.

semi-close-prefix

What to ask with the open text field.

question

Definition: 
!ELEMENT question (#PCDATA) 
!ATTLIST question
This element holds the text for the actual question.

answer

Definition: 
!ELEMENT answer (label?, description?, option*)
!ATTLIST answer
	id              ID    #IMPLIED
	ref-id          CDATA #IMPLIED
	tooltip         CDATA #IMPLIED
	default         CDATA #IMPLIED
	size            CDATA #IMPLIED
	mask            CDATA #IMPLIED
The answer holds either a list of possible answers to a question (options), or a reference to a pre-defined answer set.

2.8.1 Element

Attributes

id

Unique id within the questionnaire

ref-id

Reference to the ID of an answer within an answer set

tooltip

May be used to render a tooltip on an answer

default

Default answer

size

Size, for instance for a text box

mask

Regular expression definition of the answer, handy for open questions.

option

Definition: 
!ELEMENT option (#PCDATA) 
!ATTLIST option
	value  CDATA #REQUIRED
	score  CDATA #IMPLIED
The option is a possible answer to a question. The value is in fact an id to this option, used in data storage. The score attribute can be used to assign a score (numeric) to an answer, and to calculate overall score for a questionnaire.

flow-choice

Definition: 
!ELEMENT flow-choice (description) 
!ATTLIST flow-choice
        id          ID     #REQUIRED
	from        IDREF  #REQUIRED
	to          IDREF  #IMPLIED
	condition   CDATA  #IMPLIED
	left        CDATA  #IMPLIED
	operator    CDATA  #IMPLIED
	right       CDATA  #IMPLIED
Flow choice elements define information on what path should be followed through the questionnaire. Without any flow control, the items are beeing displayed in the order they are defined in the XML file. A single flow-choice tells a questionnaire when to go from one item to another item. Suppose there are a set of items defined, in a single section. They are named (id and label are identical for ease and convieniance) s1i1 to s1i10. Here are some examples on flow-choice flow-choice id=fc1 from=s1i2 to=s1i4 left=s1i1 operator="==" right=2 descriptionthis will skip s1i3 if the answer given at s1i1 equals to 2/description/flow-choice flow-choice id=fc2 from=s1i3 to=s1i6 left= operator="true" right= descriptionthis will always skip from s1i3 to s1i6. something like an unconditional jump/description/flow-choice flow-choice id=fc3 from=s1i6 to=s1i10 left=s1i6 operator="IN" right="1,3,5,7,9" descriptionthis will allow a jump from s1i6 to s1i10 if s1i6 equals 1,3,5,7 or 9/description/flow-choice More examples can (eventually) be found in the test questionnaire 'test-flowchoice.xml'

Element

A flow-choice can hold a description element. This can be used to explain what the purpose is of a certain flow-choice definition.

Attributes

id

The unique id of this element

from

The id of the item for which this flow-choice defines whether it should jump (or not)

to

The id of the item where the questionnaire should jump to if the conditions of this flow-choice are met.

condition

Obsolete, as in not used right now. If we decide to build a parser, this attribute will hold a single string representing the condition for wich the flow-choice must be activated.

left

The left part of the condition for this flow-choice. usually the label of an item.

operator

The operator part of the condition for this flow-chioce ( , , ==, !=, =, =, IN, true )

right

The right part of the condition for this flow choice. Usually the value of an option.

Incorporating Multi-Media

This is still a rather tentative section. We will provide the possibility of incorporating multi-media as soon as possible, so as to be able to show pictures, movies, play sounds etc. in between questions. This will most probably be realized by incorporating URL's. If you have any ideas, let us know.

Using the questionnaire to obtain a score

One obvious use for a questionnaire/survey is to obtain a numeric score, for instance when using it as an exam. This means that the answers should have a specific score, and that the score can be calculated when the questionnaire is finished. This use has been enabled with the following options:
  • the item (question) can be 'weighed' by setting the weight attribute as a numeric value
  • the option (one possible answer) can be given a numeric score
  • the item can be given a category
Typical use would be allong the following lines: an item can be weighed and categorized, answers (options) can be valued with a score. When finishing the questionnaire, the overall score can be calculated by adding item.weight * option.score for all questions. This can also be done per category. Typical use would require all options to hold a score, unless questions are purposely left out of the overall score.

Timing

There's two ways of using timing within a Socrates questionnaire; both are related to the rendering of a single page in a browser window. The first timing option is used to time the number of milliseconds between entering and leaving the page, triggered by the ONLOAD and ONUNLOAD events of the BODY tag of the page. This timing option is useful to measure response times to single questions, or complete sections, or the whole questionnaire for that matter. The option is related to the rendering definitions for the questionnaire: whatever is rendered per page is timed. The second timing option is setting a fixed time for a page, after which the next page is rendered. This is achieved by a timer starting on page load, by the ONLOAD event of the BODY tag, and a clock with a pre-defined resolution (defaults to 100 milliseconds). Both options can be defined in the rendering tag of the questionnaire: * attribute timed sets the first option to true or false. The default is false; * attribute timeout takes a numeric argument, specifying the number of milliseconds a page should be displayed. It is up to the creator of the page templates or transformations of the rendering elements to do something useful with these attributes.