Tags

The majority of the survey language consists of an XML-based set of "tags". These are written in the style common to HTML, XML and SGML. Most of the tags define variables (usually questions), but there are also tags related to page routing and configuration.

In the reference, a name of an optional parameter is written as PARAMETER, while a required parameter is written as PARAMETER.

In the following text an "open" tag will denote a tag which have contents apart from its parameters, and is written in the form TAG PARAMETERS...(contents)/TAG. A "closed" tag does not have any contents apart from its parameters, and must be immediately terminated in the form TAG PARAMETERS... /.

Markup

Apart from the tags, there is also a set of specific codes used to modify the HTML output. These are in the form {code}...{/code}. They are used, for example, to boldface a word in a caption. The extra markup can be used in all places in the code that end up as visible output. Examples are in the CAPTION parameter of a question or inside a CUSTOM block.

Includes

The SURVEY markup allows linking to external files during different phases of the survey's life span: they can be included before or after syntax parsing. This can be used, for example, to include one common set of questions into many surveys, or to keep large blocks of HTML code outside the definition of questions.

Snippets

Finally, there are perl "snippets". This is perl code which can be inserted in the survey and execute during various instances of the survey life span. Examples could be for producing a large MATRIX from an array of values. The perl snippets are fed through the "Safe" module and will not allow any interaction with the file system.

SURVEY

The SURVEY tag is the top-level container of the survey. All other data is contained within the SURVEY tag. The survey tag is always open.

MAILCOPY

The MAILCOPY tag specifies that an email containing the data submitted by the latest respondent should be sent to a specified email address. While this tag is possible to place anywhere in a multipage chain, it makes most sense to place it in the last page.

Note that configuration of default email address and SMTP host takes place in survey.conf and thus isn't possible to change by the user.

SECURITY

The SECURITY tag and its subtags specifies how access should be permitted (or not permitted) to security domains of the survey.

The SECURITY tag is open and may contain the following subtags:

All security tags have a LEVEL parameter used to restrict or open access to the security domain.

BOOLEAN

The BOOLEAN tag specifies an on/off checkbox kind of style question. The BOOLEAN tag is always closed.

CHOICE

The CHOICE tag specifies an array of possible options. The user may be single choice or multiple choice depending on the state of the MULTIPLE parameter (see below). The CHOICE tag is always open and must contain at least one CHOICEELEMENT.

The CHOICEELEMENT subtag of the CHOICE tag represent one respondent-selectable answer to the object's question.

The DBCHOICEELEMENT subtag of the CHOICE tag represents an array of possible answers. The array(s) must have been either imported via the IMPORT tag, or created in a perl snippet.

CUSTOM

The CUSTOM tag specifies one or more objects, visually designed by the author of the survey. The CUSTOM tag is always open and contains HTML code.

Note that the CUSTOM tag can also be used to insert any HTML data into the survey. It does not necessarily have to specify a variable. Whether it does is specified by the VARIABLES parameter.

Explanation of escaped. To be written.

LICKERT

The LICKERT tag specifies a scale with discreet values ranging between two opposites. The default function is to range with five steps between "true" and "false". The LICKERT tag is always closed.

LIST

The LIST tag specifies a list of string from which the respondent can choose one. The LIST tag may be presented so that only a few of the strings are displayed at a time (so that the respondent has to scroll to view more of the list). A LIST tag is always open and must contain at least one LISTELEMENT.

The LISTELEMENT subtag of the LIST tag represent one respondent-selectable answer to the object's question.

The DBLISTELEMENT subtag of the LIST tag represents an array of possible answers. The array(s) must have been either imported via the IMPORT tag, or created in a perl snippet.

MATRIX

The MATRIX tag specifies an array of variables, each of which can take a single- or multiselect answer. The MATRIX consists of MATRIXCOLUMN and MATRIXROW tags, which defines the possible answers to all the questions in the array, and the questions themselves. Depending on the settings of the UNIQUECOLUMNS and UNIQUEROWS parameters, either the rows or the columns will be chosen as being the axis carrying the variables.

The MATRIXCOLUMN defines a column in the MATRIX. In MATRIX's default mode of operation, this is a possible answer to a question defined in a MATRIXROW. A MATRIX block must contain at least one MATRIXCOLUMN.

The MATRIXROW defines a row in the MATRIX. In MATRIX's default mode of operation, this is a question, with its possible answers defined by MATRIXCOLUMNs. A MATRIX block must contain at least one MATRIXROW.

MEMO

The MEMO tag specifies an open answer multi-line text field.

TEXT

The TEXT tag specifies an open free-text one line field. The field can be limited to only accepting numerical values within a range. The TEXT tag is always closed.

CONSTANT

The CONSTANT tag specifies a constant value, which is not affected in any way by the user. This could, for example, be the revision of the questionnaire. The CONSTANT tag is always closed.

DATETIME

The DATETIME tag represents a time and/or datestamp of the moment when the respondent submitted his answers. The actual contents of the stamp is set in the FORMAT parameter. The DATETIME tag is always closed.

The FORMAT parameter contains character codes representing different parts of a date/time stamp.

ENV

The ENV tag fetches a value from the environment, such as the respondent's IP number, or the server's apache version. The ENV tag is always closed.

There is no restriction in which environment variables that can be read. This is completely dependent on which variables are set by the server. Thus, there is no way to list all possible variables here. However, there are a number of common variable names which are often used in web server environments.

IMPORT

The IMPORT tag fetches one or more variables/values from a database table and inserts them into the survey as if they had been submitted by the user. The IMPORTed variables are treated as any other variables and are thus possible to use for routing and in dynamic markup.

The IMPORT tag can contain one FILTER subtag and must contain at least one VARIABLE subtag.

Each VARIABLE subtag defines a variable fetched from a field in the database table specified in the IMPORT tag.

The FILTER subtag defines the criteria for narrowing the selection from the database table specified in the IMPORT tag. If no FILTER tag is specified, the first record in the table will be used.

Note that you can use the dynamic markup in the FILTER parameters. Thus, it's perfectly OK to say CRITERIA="userid={$uid$}" if "uid" was, say, a TEXT occurring earlier in the survey chain.

Each ARRAY subtag constructs a new array from all the values of a table column.

TIMER

The TIMER tag represents the time (in seconds) it took for the respondent to answer the survey (in practise time from load to submit). The TIMER tag is always closed.

CASEROUTE

The CASEROUTE defines a conditional branching depending on the value of one previously submitted value. The CASROUTE basically consists of a SWITCH parameter telling which variable to evaluate, and a number of CASE subtags defining possible values and routes.

The CASEROUTE tag must contain at least one CASE tag.

IFROUTE

The IFROUTE defines a conditional branching dependent on one or more boolean conditions, such as whether a variable value is less than a certain constant. The IFROUTE tag contains IF subtags, each of which defines a condition by in its turn containing a list of boolean conditions (see below).

The IFROUTE tag must contain at least one IF subtag.

Each IF tag must contain at least one of the following subtags:

All boolean condition tags have the following parameters.

RANDOMROUTE

The RANDOMROUTE defines a conditional branching where the next page is randomly picked from a list.

The RANDOMROUTE tag must contain at least one ALTERNATIVE tag.

ROUTE

The ROUTE tag defines an unconditional route. This should not be confused with the CONTINUE parameter in the SURVEY tag. By using the ROUTE tag, one sends the respondent to the next page in a survey containing several pages. With SURVEY's CONTINUE, the respondent is sent to a page outside the survey.

SEQUENCE

When having written a survey with more than one page, the last page must contain a SEQUENCE tag, listing all the pages that were contained in the survey. This should also include pages that the user did not see because of having been routed past them. The SEQUENCE tag must contain at least one FILE subtag.

When finally submitting or downloading data, it is the SEQUENCE tag which tells the system which pages (and in consequence variables) to include.

The SEQUENCE tag must contain at least one FILE subtag. Each FILE subtag points to one of the pages that were contained in the survey. Filenames may be absolute or relative, but may not be URLs.

NEWLINE

The NEWLINE tag inserts one or more linefeeds in the visible output. This is usually used to get more space between question objects. See also the SURVEY tag's AUTONEWLINES parameter. The NEWLINE tag is always closed.

COMMENT

The COMMENT tag usually does nothing. It is available as a support for the author of the survey, so he can insert notes of his own in the survey file. The COMMENT tag is always open and may contain any text.

Color

Color codes can be inserted in any visible output, such as in a question's CAPTION parameter. It is the used in the form "This is some {red}amusingly colored{/red} text". With this example "amusingly colored" would be red while the rest of the text would have the default text color (see the TEXTCOLOR parameter of the SURVEY tag).

The following color codes are defined:

Other colors can be defined manually using the custom HTML markup.

Font styles

Font styles can be inserted in any visible output, such as in a question's CAPTION parameter. It is the used in the form "This is some {i}emphasized{/i} text". With this example "emphasized" would be in italics while the rest of the text would be plain.

The following style codes are defined:

Graphics

The currently only graphics-related special markup is one used for pasting images in visual output. By writing, for example, CAPTION="{image}happyface.jpg{/image}", the image "happyface.jpg" would appear where the caption text would normally be.

Special

Special characters can be inserted in any visible output, such as in a question's CAPTION parameter. A special character is a character which does not mix well with XML syntax, and which therefore have to be coded. Examples of such characters are " and .

An example would be hving the following CAPTION: "I think x {[} y", which would be printed as "I think x y".

The following special characters are defined:

Custom HTML markup

By using the special character markup, it is possible to insert any HTML code in the output. It is possible, but somewhat cumbersome. For example, inserting a br in a TEXT's CAPTION would look like this:

TEXT NAME="test" CAPTION="Line 1{[}br{]}Line 2" /

In other words, one has to insert the special escape codes for the parts of the HTML markup.

Including external files

External files may be included into the survey at two different stages during the survey' life cycle. The first is before parse. This causes the contents of the linked file to be parsed as if it was a part of the survey code. The second is after parse, in which case the contents will simply be pasted verbatim into the visual output.

The before parse link can be inserted anywhere in the survey file. The after parse link can only be inserted in visual output, such as in a CUSTOM block or in a CAPTION.

Referencing previous variables

References to variable answers submitted on an earlier page can be inserted in all visible output, such as in a question's CAPTION. The types of references available are:

For example, an as-is insertion could be:

TEXT NAME="test1" CAPTION="How old are you, {$respname$}?" /

.. which would result in, for example, the caption "How old are you, Joel?"

Suppose a previous page contained a CHOICE listing possible fruits. A caption insertion example could then be:

LICKERT NAME="test2" CAPTION="Do you want a {%fruitsel%}?" /

.. which would result in, for example, the caption "Do you want a banana?"

Suppose a previous page contained a CHOICE for selecting respondent gender. A selection insertion could then be:

TEXT NAME="test3" CAPTION="What is your name, {!gender/0:boy,1:girl!}?" /

.. which would result in, for example, the caption "What is your name, boy?"

Perl snippets

Perl snippets allows executable code to be inserted into the survey without voiding the system security. This is possible since all the included perl code is passed through the Safe module, which denies all forms of system access.

Snippet blocks are executed either before parse, after parse or submit time. Thus a snippet can be used to produce survey code. If printed as {..}, it will be executed before parse, if {\..\} after parse and if {|..|} at submit time. Snippets executed after parse can only be inserted into visible output, such as CUSTOM blocks or CAPTIONs, wherease snippets executed before parse can be put anywhere in the code. Submit-time perl can only be placed within the SUBMIT tag.

  { .. code to execute before parse .. }
  {\ .. code to execute after parse .. \}
  {| .. code to execute submit time .. |}