(Do not bookmark this page, the location may change.
The current location can be found via this page.)

Current dynQuest Manual



Jens D.M. Rademacher
Centrum Wiskunde & Informatica (CWI, MAS), Amsterdam, the Netherlands
(Now University of Bremen)

Sonia Lippke
Universiteit Maastricht
(Now Jacobs University Bremen)


Reference:
J.D.M. Rademacher, S. Lippke. Dynamical online surveys and experiments with the free open source software dynQuest. Journal of Behavior Research Methods, 39 (2007) 415--426.
Recent changes (The software is under ongoing development and the published reference above may not describe the latest state.)

Frequent programming problems

System requirements: dynQuest requires Perl and a HTTP server, check this page for details and help.

Download:
Manuscript: up to date version (may differ slightly from the text on this page) [pdf].
Software: Please send request for dynQuest by Email to s.lippke at jacobs-university de

Up to date HTML manual:



Contents

1 Introduction

2 The Software

3 Programming the Trial
3.1 The Single HTML Page
3.1.1 Defaults and Conventions
3.1.2 Initial Page and Code Definition
3.1.3 List of Field Names
3.1.4 Required Entries
3.1.5 Dynamic Page Manipulation
3.1.6 Data Status
3.1.7 The Database
3.1.8 Error Handling
3.2 Linking Pages
3.2.1 Unconditional Links
3.2.2 Simple Conditional Links
3.2.3 History-Dependent Links
3.2.4 Randomized Links
3.2.5 Linking Priorities
3.2.6 Display the Linking Structure
4 Running a Trial in Practice
4.1 Checking the Layout
4.2 Preparation of the Trial
4.3 Data Management
4.4 Using the Data in Other Programs
5 Appendix
References

1 Introduction

DynQuest is a package of cgi-scripts, focused on linking dynamic trial pages. Its use requires some technical deliberations concerning HTML and file management, but it is nevertheless simple, reliable and transparent. It is freely available to researchers for computer-assisted and web-based trials upon request.


2 The Software

For user friendliness, dynQuest comes in two parallel versions, one for single PCs under Windows and the other for networked computers under UNIX or Linux, respectively (see Table 1). The basis of a trial for dynQuest is a flow diagram (see Figure 1) where the choice of the following page can depend on responses in the previous pages. The pages of the trial, which need to be in HTML format, may be created with any text or HTML editor (such as DreamWeaver or FrontPage).

Figure 1

Figure 1. The Multistage Model algorithm and rules for stage assignment (adapted from Lippke, Sniehotta, & Luszczynska, 2005).


The software runs in the background, invisible for the study participant, and manages the page flow and data storage. It analyzes the data submitted from the current page of the questionnaire, sends the appropriate follow-up page to the browser, and stores the new data in a database on the server.

The HTML pages contain text and forms for the questions, and encode the algorithm for the choice of the next page as programmed by the user (similar to the software PHP). Hence, the flow diagram is not implemented as a whole, but each node of the diagram is a HTML page that contains the links only to adjacent follow-up pages. DynQuest applies quite universally to create a database from interviews via web-browsers, and in addition follow links and manipulate pages depending on the data submitted. It has also proved useful for static questionnaires and registering students or future study participants. Similar commercial software is available, but the advantages of dynQuest are that it is easy to use and install, simple, transparent, focused on the purpose, and poses no restrictions on the layout of the trial pages. Furthermore, it is open source, free, platform independent, and it only uses standard capabilities of browsers (HTML forms and CGI); it does not use PHP, Java, JavaScript, Cookies or Pop-up windows.

The software package: The programs in the dynQuest package are text files (scripts) written in the (freely available) programming language PERL. DynQuest makes use of the common gateway interface (CGI) between web-browsers and servers, hence to use it on a single PC, an HTML browser, PERL, and an HTTP server (freely available, e.g., "apache") need to be installed (see Sections 4 and 5). Only basic HTML and operating system knowledge is required for running dynQuest. The main steps for making a dynamic questionnaire or intervention trial available on the internet are as follows:

  1. Check that the programming language PERL is available on your web account and that study participants can run the dynQuest CGI-scripts through a browser (see Section 5).
  2. Create HTML pages for the nodes of the flow chart of your questionnaire using the dynQuest commands for the linking structure (see Section ).
  3. Copy these pages and all relevant files (cf. Tables 1 and 2) from the dynQuest package into one folder.

The dynQuest files are open source software that can be redistributed and/or modified under the terms of the GNU General Public License as published by the Free Software Foundation. The original copyright of the files rests with the first author. The parts of dynQuest are listed in Table 1.

Table 1. Files of the software package for use on PC or Unix/Linux as indicate by the name.

File name

Function

dynQuest.pl.cgi (one for PC and one for Unix)

Main script, managing the flow of pages and database entries. PC and Unix version have the same names so that the same HTML pages can be used for both.

definitions.txt

Text file that contains definitions of keywords and other dynQuest options; these may be changed by the user at will (Section 3.1.1).

showQuestUnix.pl.cgi,
showQuestPC.pl.cgi

Analyze and display the link structure (flow chart) (Section 3.2.6).

cleanQuestUnix.pl.cgi,
cleanQuestPC.pl.cgi

Remove redundant entries from the database (Section 3.1.7).

To run a specific trial, further files beyond those containing the questions are needed, or may be helpful (see Table 2).

Table 2. Required and optional files not contained in the dynQuest package.

File name

Function

Required or optional

fieldnames.txt

Lists all field, i.e., variables, names (Section 3.1.3)

Required. If not in folder, no data will be saved.

defaultDataFile.txt

"Data Base"; contains data status of all submissions

Optional. In case it is not in the folder, it is newly created (Section 3.1.7).

showPageNames.txt

Causes current file name to be displayed (Section 3.2.6)

Optional. Helpful for piloting and checking the trial prior to the actual data collection.

showLastForm.txt

Causes entries on prior page to be displayed (Section 3.2.6)

Optiona. Helpful for piloting and checking the trial prior to the actual data collection.

Users can open and view all files listed in Tables 1 and 2 in a text editor. We recommend not to change the CGI scripts. If there are questions or comments, please contact the authors. The software is under ongoing development and further functions may be added in the future.

Limitations of the software: The layout of the trial needs to be programmed and checked by the user (advanced HTML editors can do this). Correct programming of dynQuest commands and spelling of item names is not assisted, and there is no help or software documentation beyond this article. There is no automatic management of database files other than backups when purging the database (see Sections 3.1.7 and 4) (file management software can do this). The algorithm for choosing follow-up pages is somewhat limited concerning possible logical operations (see Section 3.2). There is no indication or estimate of the number of remaining questions or pages in a trial (suitable questionnaire design can compensate this). DynQuest cannot check whether a participant's codeword is already in use by another participant, and the internet communication channels are not secured against third party interception or manipulation (which can be managed with other software).

As indicated, most of these aspects can be overcome in conjunction with other software. In particular, we expect combinations with the HTML preprocessor PHP to be fruitful. However, a discussion of details would go beyond the scope of this article.

Installation: dynQuest itself does not require any installation. Simply copy all relevant files into the folder of the trial pages. Note that the folders with scripts and HTML pages need to be accessible by the web-browser of study participants (see Sections 4 and 5).


3 Programming the Trial

Relevant elements of a trial are:

  1. Page names of the trial pages, that is, the nodes in the flow chart (e.g., Figure 1) of the trial,

  2. links and linking condition between pages, that is, the edges of the flow chart (e.g., Figure 1),

  3. field names, that is, the names of items that participants can respond to, and

  4. item values to be stored in the database as a response for a question with predefined possible responses (e.g., degree of agreement with a statement, range 1 to 5).

Each node in the flow chart of the trial is encoded in an HTML form (within an HTML file) containing the items, together with all outgoing edges, that is, the linking information to all follow-up nodes, invisible to the participant. Each item of the questionnaire requires a unique field name that is used as the name of the HTML form elements concerning this item and as the column header in the database. For instance, items that inquire about the degree of agreement with statements often come in groups and may be arranged row wise in a table whose columns contain fields that the participant can select. In HTML, such a selection can be realized, for example via so-called radio buttons that can be activated by the participant; however, we do not discuss general HTML programming in this article.

The HTML form of a node must submit data to dynQuest via the so-called post method. Typically, the HTML code (located anywhere within the HTML body) is:

<form method="POST" action="dynQuest.pl.cgi">
...
</form>

Upon submission, the form data will be stored in the database, which is an automatically generated text file according to a given list of all field names (see Table 2). This database can be imported easily for post-processing and (statistical) analysis into database or statistics software, such as SPSS or Excel (cf. Section 4.3).

After storing data, the follow-up page will be sent to the participant's browser by dynQuest according to the encoded linking, which allows for answer-dependent, static (answer independent), or randomized links and manipulation of page contents. The correspondence between trial information and HTML form data is as follows.

Table 3. Correspondence of Trial and HTML form data.

Trial

HTML form

Item name

Input field name (<input [...] name=[...]>)

Item value, if predefined

Input field value (<input [...] value=[...]>). Typically several such form elements correspond to one item with different values, e.g., a set of radio buttons.

Item that is invisible to the participant, e.g., indicator of current page

Hidden field (<input type="hidden" [...]>)


The flow chart edges (cf. Figure 1 and the example below) are encoded either in hidden fields or in the names and values of items. For instance, the form element name "next_sport" with value "page3a_1" by default means that when activating this form element (which might be a radio button for "Volleyball"), the page "page3a.htm" will be loaded next, and the value "1" will be written into the database in the column "sport". The HTML code for this and another radio-button for "soccer" with value "2", linking to another file could be:

<form method="POST" action="dynQuest.pl.cgi">
Your favorite sport:<br>

<input type="radio" name="next_sport" value="page3a_1">

Volleyball<br>

<input type="radio" name="next_sport" value="page3b_2">

Soccer<br>

<input type="submit" name="submission" value="send data">
</form>

(The keyword "next", the suffix "htm" and the separator symbol "_" can be changed at will in the file "definitions.txt"; see Section 3.1.1.)

DynQuest makes frequent use of so-called "hidden" fields ("<input type="hidden""), which are not shown in the browser, but whose values are submitted. These fields can be inserted anywhere within the HTML form that submits data to dynQuest. The only exception is several competing links on one page (see Sections 3.1.1 and 3.2.5).

In the following, details of the HTML programming for dynQuest and its functionality are discussed.


3.1 The Single HTML Page

In this section, we discuss all elements concerning a single HTML page; linking of pages will be described in Section 3.2. The following subsections are relatively independent and do not need to be read in order. These subsections are: 1. Defaults and Conventions, 2. Initial page and code definition, 3. List of field names, 4. Required entries, 5. Dynamic page manipulation, 6. Data status, 7. The database, and 8. Error handling.


3.1.1 Defaults and Conventions

The file "definitions.txt" contains all keywords and symbols for dynQuest programs that may be changed by the user. These are listed line wise with a brief explanation separated from the keyword/symbol itself by an ASCII tabulator. Note that this file contains settings for both a single PC and network (UNIX) environment. Throughout this article we refer to the default settings.

Since certain symbols are meaningful for dynQuest, some care has to be taken in naming files and items. Keywords of the definitions file cannot be used as item or file names, but the use of the separator symbol is somewhat flexible and is described in detail in the respective sections. The HTML suffix set in the definitions file will be added whenever it is not contained in a file name received from a form.

Since text fields in HTML forms have a default value, dynQuest allows to define a "non-value", by default the minus sign "-". If this value is encountered, the item is considered unanswered.

Further conventions and assumptions about the HTML forms are as follows:

  1. If several form elements with the same name are submitted, the first of these in the order of submission (by standard this is the order within HTML file) will be used.
  2. If several simple conditional or unconditional links are submitted, the last of these will be used (see Section 3.2.5).
  3. If semicolons and line breaks/carriage returns are encountered within submitted data, they will be replaced by commas or "|", as they interfere with the database structure (see Section 3.1.7).
  4. showQuest (see Section 3.2.6) assumes that an input form element is contained entirely in one line of the HTML file, e.g., there is no line break between "<input" and "name=" for the same input element. It assumes also that between two input fields there is a line break in the HTML file.

3.1.2 Initial Pageand Code Definition

On the first page of the trial an individual code is determined for each participant (other questions can be contained on the page). This code identifies the entries in the database that belong to the same participant and is used to control multiple submissions when purging the database (see Section 3.1.7). The code can be either defined by the participant, for example as a selection of letters from first and last name and birthplace, or it will be set automatically to the current date and time with precision up to one second. The automatic setting will be chosen when no code defining field is contained on the page. Code defining fields are indicated by the keyword for code definition (by default "CODEDef"), that is, "CODEDefx", where "x" is not relevant for dynQuest, but should be different to distinguish fields. For instance, two code words can be inquired by the HTML code (somewhere within the HTML form):

<input type="text" name="CODEDef1" value="-">
<input type="text" name="CODEDef2" value="-">

The values of all these fields are concatenated in the order of the form, for example, "Boston", "Paula", becomes "BostonPaula", and written into the database under the item "dqcode". Usually code defining fields are required fields (see Section 3.1.4).


3.1.3 List ofField Names

The only information about the trial that is not contained in the HTML pages themselves (and the settings file "definitions.txt") is a complete list of all field names that occur in the entire trial. This list needs to be provided by the user (via any text editor) in form of a text file with line breaks between fieldnames, for example:

fieldname1
fieldname2
...

The spelling has to match precisely the one in the HTML pages beware of blanks, lowercase versus capital letters, etc. The ordering of these names is also used in the database, but it need not match the ordering in the trial. Since this file is read after each submission, it can be manipulated during a trial, for instance to add items. The program showQuest can be used to generate this list automatically (see Section 3.2.6).


3.1.4 Required Entries

Answers can be "required" in the sense that the page named (by default) "missingRequired.htm" is loaded when a required field has not received data. Study participants are thus forced to answer all such questions to get to the following trial page. The content of this page should encourage the participant to go back (by the 'back' action/button of the browser) and complete the answers. However we caution the user that study participants may get frustrated and drop out.

The requirement is implemented by a hidden field with name "require" (by default) whose value is a list of fieldnames that are required with separator symbol in between (by default "_"); for example, at an arbitrary position within the HTML form write:

<input type="hidden" name="require" value="field1_field2_field3">

Note that in the standard settings "-" is considered as a non-value, so the same error page will be loaded if this value is encountered in a required item. To describe the precise missing item, the user can add another hidden item, by default "requireErrMsg", containing a list messages in the same order as in the above field, e.g.

<input type="hidden" name="requireErrMsg" value="You did not reply to 1._We miss a response to 2._Please answer question 3.">

These messages can be printed at an arbitrary position into the error page by using the dynamic page manipulation for the field "requireErrMsg" (see Section 3.1.5).


3.1.5 Dynamic Page Manipulation

Since dynQuest scans the HTML pages of the trial when sending them to the participant's browser, it can manipulate the page contents. In its current version, dynQuest allows to display previous data of a study participant in the current trial page, which is a useful dynamic component for individualized interventions. There are two alternative possibilities to implement this function.

  1. For convenient programming with a HTML editor, a hidden field can be used whose name, by default, is "dynQuest.showData", and whose value is a field name; it is important that the value follows the name in the HTML file. This hidden field will be replaced with the item value taken from the data status (see Section 3.1.6). For example, if the study participant was previously asked for an activity with the item named "activity" and s/he answered "wall climbing", then the HTML code (within the HTML form):

    You decided to start <input type="hidden" name="dynQuest.showData" value="activity"> . Where do you want to do <input type="hidden" name="dynQuest.showData" value="activity"> ?

    would be replaced by

    You decided to start wall climbing. Where do you want to do wall climbing?

  2. A new type of field can be used, by default named "dynQuest.showData", that contains the fieldname. For the above example in this variant write

    You decided to start <dynQuest.showData="activity">. Where do you want to do <dynQuest.showData="activity">?

    would be replaced by

    You decided to start wall climbing. Where do you want to do wall climbing?

We remark that more sophisticated dynamic page manipulation can be realized, for instance in combination with the free software PHP.


3.1.6 Data Status

The data management of dynQuest is partly client-based in the following sense. A hidden field is inserted into all pages that are sent to the participant's browser containing the trial data submitted up to this point by the participant; we refer to this data as the "data status". Upon submission of a form, the new data is appended to the data status, which is written into the database (see Section 3.1.7). Note that the participant could theoretically manipulate the HTML pages and send arbitrary data to dynQuest, in particular an arbitrary data status.

However, his mechanism avoids searching the database for previous entries to update a participant's data status, and it makes the database a precise log of activity. This serves as a precaution against manipulation or loss of data in case the database was deleted before the participant ended the trial.


3.1.7 The Database

All submitted data are stored in a text file, by default called "defaultDatafile.txt". If this file does not exist, it is created automatically using the list of field names (see Section 3.1.3). The location of the database is set in the definitions file; in particular, it can be in another, secure folder. We recommend making the database unreadable to web-clients.

The precise format of the database is as follows: The first line contains all fieldnames separated by semicolons in the order of the list of field names. Five additional columns are inserted by dynQuest: The first column in the database is the participant's code "dqcode" (see 3.1.2), and the last four columns are as follows. The name of the previously used HTML file, the name of the currently used HTML file, the date and time this entry was written into the database, for example, "15-Aug-2005 9:37:17", and the version of dynQuest that wrote this entry, for example, "2005-Nov-9", respectively. If the database is set to be readable, it can also be viewed in the browser, e.g., via

"http://www.userpage.fu-berlin.de/~slippke/dynQuest/defaultDataFile.txt".

Each line following the header contains the corresponding data of a participant as retrieved from her/his submissions. Note that in case of an existing database, dynQuest compares submitted items with the list of field names, and, ignoring the structure of previous entries to the database, it simply appends a new line to the database. Since new lines are added each time a person submits a form, the database can be read as a log of activity, which allows finding possible errors in the database. Typically, only one of the entries from a participant is relevant for later data analysis, and a natural choice is the data set with the largest number of non-empty items. This entry is usually (but not necessarily) the chronologically latest entry. The choice of entry with most data is implemented in the program "cleanQuest.pl.cgi" that can be run directly from a web-browser using its name as a URL, for example:

"http://www.userpage.fu-berlin.de/~slippke/dynQuest/cleanQuestUnix.pl.cgi".

More precisely, cleanQuest associates a data set to a participant if the code (Section 3.2.1) and the first N items (e.g., sociodemographic data) coincide, where N can be set in the definitions file but is zero by default. It then compares the number of entries of all associated data sets and keeps the one with the largest number of non-empty items. This algorithm is quite robust, for instance, participants can go back and forth in the trial with the browser without changing the outcome. A summary of the changes is displayed in the browser, see Figure 2.

Figure 2

This is cleanQuest Version 2005-Nov-12

Number of identifying entries: 0

Created a backup copy using the command:
cp defaultDataFile.txt "defaultDataFile.txt-2005-Nov-12_13:51:33"

Reading uncleaned database...

... read 8 entries. Writing cleaned database...

... done. Cleaned database has 2 entries.


Figure 2. Sample browser output of cleanQuest.

Before purging the database, cleanQuest creates a backup copy of the untouched database with the same name plus the current date and time (see also Sections 4.3). In addition, all changes to the database are recorded in a log file with the suffix ".log". Hence, the default database file is purged, so that subsequent submissions are appended to a purged database. To avoid misuse, we recommend restricting access to the cleanQuest script. Note that it may be quite slow to clean large (several megabytes) databases, in which case we recommend to move the database to a different location so that dynQuest will automatically create a new empty database upon further submissions (see Section 4).


3.1.8 Error Handling

If an internal error is encountered, for example, missing data in a link, a missing file, or an unreadable database, a brief error message describing the problem will be displayed. Additional text can be defined in the definitions file. By default "Please contact" and an email address set in the definitions file is displayed.


3.1.9 Numerical functions

We have currently implemented the following functions that involve numerical computations; further function can be easily added. Generally, the result of the computation is stored in another field, which can then be displayed on a follow-up page or used for linking from the current page. All field/variable names must be listed in the fieldnames files. If an argument that should be a number does not satisfy a C-floating point number pattern, the result of the computation will be "NaN" (Not a number) and the item is considered unanswered. Each such field has a name of the form "dq-x" where "x" stands for the computation type, e.g. "sum" for summations. The order of computation for several such fields on one page is the ordering on the page, if the field name contains a unique appendix for each computation. For instance, if the names "dq-sumA" and "dq-multA" and "dq-sumB" are used in this order in the HTML form, will lead to a computation in the order 1. dq-sumA, 2. dq-multA, 3. dq-sumB. If the ordering is irrelevant, one can simply use the name of field itself multiple times and the ordering then is: BMI, summation, multiplication, quotient, range check.


3.2 Linking Pages

In this section, we discuss the possibilities to link pages of the trial. Subsections can be read in any order and are: 1. Unconditional links, 2. Simple conditional links, 3. History dependent links, 4. Randomized links, 5. Linking priorities, and 6. Display the linking structure.


3.2.1 Unconditional Links

The basic type of links are static so that the same follow-up page will always be loaded, independent of the answers. Such a link is programmed by inserting a hidden field element, by default with the name "next" whose value is the name of the HTML file. In case this file name does not contain the HTML suffix set in the definitions file, the suffix will be added to the name. For example, to unconditionally link the current page to the page "node2.htm" write (within the HTML form):

<input type="hidden" name="next" value="node2.htm">

In case the suffix ".htm" is set in the definitions file one may equivalently use:

<input type="hidden" name="next" value="node2">

 


3.2.2 Simple Conditional Links

The simplest dynamic/conditional link depends on a single answer, that is, a single form element that can be activated by the participant. This is programmed by a form element whose name is the keyword for linking and the field name with the separator in between. For example, suppose a radio button should assign the value "1" to the field name "rglmt4" and link to the file "t4-10.htm". The HTML code for this (in the default settings) is:

<input type="radio" name="next_rglmt4"
value="t4-10_1">

Instead of radio buttons, one can use text fields or pull-down menus. A pull-down menu example is :

<select size="1" name="next_sex">
<option selected>gender</option>
<option value="figure_1_m_1">male</option>
<option value="figure_1_2">female</option>
</select>

Table 4 lists the relevant properties of the form element for dynQuest.

Table 4. Properties of the simple conditional link field element relevant for dynQuest.

Next

Linking keyword for dynQuest.

rglmt4

Name of the item (field name) in the field names file and database.

t4-10

Name without suffix of the next HTML page that will be loaded if this form element is activated and the page submitted.

1

Value of the item for the database, if this radio button was activated.

Note that the last separator symbol in the value is assumed to separate file name and field value. Hence, the value for the database cannot contain the separator symbol, but the file name can. For example, by default "page_3_1" is interpreted as "page_3.htm" and field value "1".

Pseudo-conditional link: A simple conditional link is in fact unconditional if contained in a hidden field because these are always submitted. The difference to unconditional links is that for a pseudo-conditional link data for the given item is written into the database.

Detect missing values: Using the flow diagram, it is usually possible to reconstruct the items a participant has seen, but left unanswered. However, this is not possible for randomized links. In general, it can be more convenient to obtain a missing value for unanswered items automatically, such as the value "99". This can be realized by a pseudo-conditional link in addition to a visible simple conditional link. For instance, in addition to the previous example, use:

<input type="hidden" name="next_rglmt4" value="t4-10_99">

It is important that this hidden field lies after the visible field within the HTML form, because if the visible field is activated, then dynQuest will receive the values "t4-10.htm_1" and "t4-10.htm_99" for the same form element name "next_rglmt4". By convention, the first of these will be used (see Section 3.1.1). By linking to an error page that describes the precise missing item, answers can be required more specifically than with the general require mechanism (see Section 3.1.4).


3.2.3 History-Dependent Links

In this section, we describe a conditional link that requires possibly more than one participant's answer (that might also go back to earlier pages) to match a prescribed list of values. For instance, if the participant's gender was inquired on the first trial page, one can distinguish male and female participants on a later page of the trial without asking for the gender again.

The keyword for this link is by default "nextHistory" and is implemented by a hidden field whose name consists of the keyword, a file name for the true case, and/or a file name for the false case separated by the separator symbol (by default "_"). The hidden field's value needs to be a list of pairs of field names and values that all need to match for the true case. Here field names and values need to have the separator symbol in between, and pairs are distinguished by two separators. For instance, the form element (within the HTML form) (note there is a typo in the pdf preprint)

<input type="hidden" name="nextHistory_trueFile_falseFile" value="field1_value1__field2_value2">

means the following: If the data for "field1" and "field2" in the data status (Section 3.1.6) precisely (!) match the values "value1" and "value2", respectively, then the file "trueFile.htm" (can be any other name) will be loaded next, else the file "falseFile.htm".

To realize history dependent branching for more than two alternatives it is possible to omit either the entry "trueFile" or "falseFile", that is,

name="nextHistory_trueFile"

for the true case only, and for the false case only set

name="nextHistory__falseFile".

Multiple linking is then implemented by a sequence of such single case history dependent links, which corresponds to a logical "or" combination. Note that there must be a line break between each of these HTML form elements in the HTML file. The processing of these links is displayed if a file named (by default) "showMsg.txt" exists.


3.2.4 Randomized Links

Randomized control groups can be realized by a randomized choice of the next file from a list. This is implemented by a hidden field, by default with the name "randomize", whose value is a list of file names with separators in between. Each time the page is called, a file from this list is chosen pseudo-randomly and invisible to the participant by the PERL command "rand(k)". Here "k" is the length of the list; and the integer rand(k) is used as the index of the file in the order of the list. For example, if participant A submits a form with

<input type="hidden" name="randomize" value="file1_file2_file3">

then the function rand(3) may yield the value 1, so "file1.htm" will be loaded. If participant B submits the same form sometime later, rand(3) may be 3, so "file3.htm" is chosen, and so on. Note that uniform distribution of choices can only be expected for large numbers of participants.

Note also that a study participant might skip group-specific questions, so that the random group assignment would not be detectable. Therefore, we recommend introducing a variable that stores the group assignment via a hidden field (or a pseudo-conditional link). For instance, if participants are randomized on page "t2_8.html" to either the page "t2_8a.html" or "t2_8b.html", then the following construction gives a group assignment:

On page "t2_8a.html": assign the value 1 to the variable "randomgroup" via

<input type="hidden" name="randomgroup" value="1">

On page "t2_8b.html" assign the value 2 via

<input type="hidden" name="randomgroup" value="2">


3.2.5 Linking Priorities

If more than one linking command is given on a page, priorities decide upon the choice of link in the following order:

1. History-dependent link

2. Randomized link

3. Depending on the naming and ordering in the HTML page, simple conditional link or Unconditional link have priority 3 as discussed below.

As an illustration, if a history-dependent and a simple conditional link are both activated, then the history-dependent link will be chosen. However, care has to be taken within point 3 of the above list according to the conventions listed in Section 3.1.1: The choice of link depends on the ordering of the form elements on the HTML page and their names. Suppose the conditional link is activated, then the resulting four cases are listed in Table 5.

Table 5: Priority of simple conditional and unconditional links.

Names \ order

Conditional first

Unconditional first

Equal

Conditional is chosen

Unconditional is chosen

Different

Unconditional is chosen

Conditional is chosen

Generally, if several simple conditional and unconditional links are submitted, then the last of these will be chosen; by HTML standard, the order in the HTML file is the order of submission. However, if several such links with the same name are submitted, then the first will be chosen.

We remark that these priorities and ordering dependence allows requiring items more specifically, and missing items can be traced (see Section 3.2.2).


3.2.6 Display the Linking Structure

The program showQuest (in the scripts "showQuestPC.pl.cgi" and "showQuestUNIX.pl.cgi") can be used to plot the complete linking structure of the trial, that is, the entire flow chart, by recursively analyzing the programmed links (see Figure 3). To use showQuest, set the file name of a trial page - usually the first - at the position described in the file "definitions.txt". It is convenient to start showQuest directly from a web browser so that the output is displayed in the browser window. For this, use the name as URL, for example "http://localhost/dynQuest/showQuestPC.pl.cgi". ShowQuest also creates a list of all field names that can were encountered and stores these in a file named "fieldnames-sq.txt" by default. This file can be used as the list of field names (see Section 3.1.3).

Figure 3

This is showQuest Version 2006-Mai-18

line 1

 

 

2

3

 


 

index.htm: : -> wave101.htm
...
wave111.htm:  : -> wave112.htm
wave112.htm(random) : -> wave114a
wave114a.htm:  randomgroup:1 -> wave120
wave120.htm:  : -> wave121.htm
wave121.htm:  : -> end
wave112.htm(random) : -> wave114b
wave114b.htm:  randomgroup:2 -> wave114b1
wave114b1.htm:  quiz1t1:1 -> wave114b2b
wave114b2b.htm:  quiz2t1:1 -> wave114b3b
wave114b3b.htm:  quiz3t1:1 -> wave114b4b
wave114b4b.htm:  : -> wave120
wave114b3b.htm:  quiz3t1:2 -> wave114b4b
wave114b3b.htm:  quiz3t1:3 -> wave114b4a
wave114b4a.htm:  : -> wave120
wave114b3b.htm:  quiz3t1:99 -> wave114b4c
wave114b4c.htm:  : -> wave120
wave114b2b.htm:  quiz2t1:2 -> wave114b3b
...


Wrote list of field names to file 'fieldnames-sq.txt'.

 

Figure 3. Sample (partial) output of showQuest from a trial flow diagram; at "..." part of the output is not shown in this figure; line information refers to the description in the text.

The structure of the trial can be recovered from this output, which thus allows checking for errors in link programming. For instance, the first line in the output in Figure 3 means that after page "index.htm", the page "wave101.htm" always follows. (Between the first and second lines some output is not shown here.) The third line means that a randomization occurs on page "wave112.htm", and that the first group is sent to page "wave114a.htm". The fourth line means that page "wave114a.htm" contains a simple conditional link, which links to "wave120.htm" if the value "1" is submitted for the variable "randomgroup". In fact, here this link is a pseudo-conditional link to store the group assignment (see Section 3.2.2). Several of the following lines refer to simple conditional links, for example, the last line means that page "wave114b2b.htm" links to "wave114b3.htm" under the condition that item "quiz2t1" was given the value "2".

Note that showQuest makes assumptions about the form of the HTML file (see Section 3.1.1).

Often one checks the trial by doing it, which is assisted by plotting the name of the currently used HTML file and the data that have been retrieved from the previous page. This is activated if files named (by default) "showPageNames.txt" and "showLastForm.txt", respectively, with arbitrary contents exist in the directory of the trial pages.


4 Running a Trial in Practice

In the following, we will describe some aspects of practically running a PC- and www-based trial to help overcome initial barriers for beginning users.


4.1 Checking the Layout

The appearance of the HTML pages needs to be programmed and checked by the user, which is supported by advanced HTML editors. Different browsers may display the same HTML page differently, which theoretically requires to check the trial with different browsers and different default settings of these browsers. However, practically these differences have played no great role in terms of usability of the trial for the study participants and interviewers.


4.2 Preparation of the Trial

A typical barrier for the beginning user is how to install the software to make the trial work. As mentioned in Section 2, there is no installation of dynQuest itself. All files simply need to be in a folder that can be accessed from a web browser through the HTTP server and in which CGI scripts can be run. For the apache server, this is usually the default setting for the "htdocs" folder and its subfolders; on a UNIX system the administrator should be contacted.

In Section 5, we describe how to check that the scripts work on your system. We emphasize that in order to use dynQuest, the trial pages must be accessed through the HTTP server, that is, the URL of the server, for example "http://localhost/dynQuest/startpage.html" for a local server, and not "file:/...". A typical problem is that programming errors for the linking result in wrong routes from one page to the next. To check the flow structure, one can simply click through the single pages to check them individually or use the program showQuest (see Section 3.2.6). For the latter, the start page must be defined in the definitions file. The program showQuest is started, for example, via "http://localhost/dynQuest/showQuestUnix.pl.cgi".


4.3 Data Management

Since dynQuest safely stores the data into the database, the remaining data management tasks for the user are to avoid loss and corruption of the database. This requires well-organized backups, which is partly done by cleanQuest when purging the database (see Section 3.1.7) and can be further automatized by additional software. We recommend to separate cleaned and uncleaned databases in different folders and media, and to adopt a naming scheme using date, time, and the person who stored or cleaned the database. Moreover, cleaning a large active database may cause a timeout on a browser that is awaiting data, and so the size of the active database file should be kept small (as a guideline less than a megabyte). This can be done by either regularly purging the database with cleanQuest, or by moving it to another location so that dynQuest will start a new database. Note that in the latter case, entries from the same participant may be spread over different files.


4.4 Using the Data in Other Programs

Analyzing data requires appropriate software, and a barrier might be how to import the data into that software. Since the database is a text file where items are separated by semicolons and data sets by line breaks (see Section 3.1.7), it can be easily imported into all common databases, spreadsheets, and statistics software such as SPSS. However, this requires to adhere to the rules of the software for importing data in this format. For instance, in SPSS use the file menu "read text file" and follow the Text Import Wizard. Default settings are appropriate, except for "Are variables included in the top of your file?" (choose YES), "Which delimiters appear between variables?" (no other than SEMICOLON), and "Specification for variable(s) selected in the data preview" (check whether Data Format is Numeric, String or Date/Time and check number of Characters). Note that syntaxes for data management can be saved for later use.



5 Appendix

Checking the scripts on your Computer:

  1. Run perl <scriptname> from the prompt where <scriptname> is any dynQuest file with the suffix ".cgi". You may have to use a path, e.g., c:\apache\perl\bin\perl <scriptname>.

  2. Check the location of the PERL executable on your system. For the PC version, the setting is "c:\apache\perl\bin\perl.exe", for UNIX "/usr/bin/perl". If these settings are not valid on your system, open all dynQuest scripts in a text editor and adjust these in the first line of each ".cgi" file.

  3. For the UNIX version, also check that the commands "/usr/local/bin/lockfile -6 -r 10" and "/sbin/rm" work. These manage attempts of simultaneous access to the database. If the paths or commands on your system are different, change the settings in the file "definitions.txt" accordingly.

References

Bailey, R. D., Foote, W. E., & Throckmorton, B. (2000). Human sexual behavior: A comparison of college and Internet surveys. In M. H. Birnbaum (Ed.), Psychological experiments on the Internet (pp. 141-168). San Diego: Academic Press.

Baron, J., & Siepmann, M. (2000). Techniques for creating and using Web questionnaires in research and teaching. In M. H. Birnbaum (Ed.), Psychological experiments on the Internet (pp. 235-265). San Diego: Academic Press.

Birnbaum, M. H. (1999). Testing critical properties of decision making on the Internet. Psychological Science, 10, 399-407.

Buchanan, T., & Smith, J. L. (1999). Using the Internet for psychological research: Personality testing on the World Wide Web. British Journal of Psychology, 90, 125-144.

Cummins, C. O., Prochaska, J. O., Driskell, M. M., Evers, K. E., Wright, J. A., Prochaska, J. M., & Velicer, W. F. (2003). Development of review criteria to evaluate health behavior change websites. Journal of Health Psychology, 8(1), 55-62

Evers, K. E., Prochaska, J. M., Prochaska, J. O., Driskell M.-M., Cummins, C. O., & Velicer, W. F. (2003). Strengths and weaknesses of health behavior change programs on the Internet. Journal of Health Psychology, 8(1), 63-70.

Gosling, S. D., Vazire, S., Srivastava, S., & John, O. P. (2004). Should we trust web-based studies? A comparative analysis of six preconceptions about Internet questionnaires. American Psychologist, 59, 93-104.

Kirsch, S. D. K., & Lewis, F. M. (2004). Using the World Wide Web in health-related intervention research. Computers, Informatics, Nursing, 22, 8-18.

Krantz, J. H., Ballard, J., & Scher, J. (1997). Comparing the results of laboratory and World-Wide Web samples on the determinants of female attractiveness. Behavior Research Methods, Instruments, & Computers, 29, 264-269.

Lippke, S., Sniehotta, F. F., & Luszczynska, A. (2005). Social cognitions across the stages of behavior change. A comparison of two stage models. Polish Psychological Bulletin, 36(1), 43-50.

Lippke, S., Ziegelmann, J. P., & Schwarzer, R. (2004). Initiation and maintenance of physical exercise: Stage-specific effects of a planning intervention. Research in Sports Medicine, 12, 221240.

Mar, C. M., Chabal, C., Anderson, R. A., & Vore, A. E. (2003). An interactive computer tutorial to teach pain assessment. Journal of Health Psychology, 8(1), 161-173.

Morrow, R. H., & McKee, A. J. (1998). CGI scripts: A strategy for between-subjects experimental group assignment on the World-Wide Web. Behavior Research Methods, Instruments, & Computers, 30, 306-308.

Nigg, C. R. (2003). Technology's influence on physical activity and exercise science and application: The present and the future. Psychology of Sport and Exercise, 4, 57-65.

Schwarzer, R., Luszczynska, A., Schz, B., Scholz, U., Ziegelmann, J. P., & Lippke, S. (2006). Adoption and maintenance of four health behaviors: Theory-guided longitudinal studies on dental flossing, seat belt use, dietary behavior, and physical activity. Manuscript submitted for publication.

Westen, D., Novotny, C. M., & Thompson Brenner, H. (2004). The empirical status of empirically supported psychotherapies: assumptions, findings, and reporting in controlled clinical trials. Psychological Bulletin, 130, 631-663.

Williams, J. E., McGraw, K. O., & Tew, M. D. (1999). Undergraduate labs and computers: The case for PsychExps. Behavior Research Methods, Instruments, & Computers, 31, 287-291.

Wolfe, C. R., & Reyna, V. F. (2002). Using NetCloak to develop server-side Web-based experiments without writing CGI programs. Behavior Research Methods, Instruments, & Computers, 34(2), 204-207.

Wolfe, C. R. (1992). Using Authorware Professional for developing courseware. Behavior Research Methods, Instruments, & Computers, 24, 273-276.