Current version: 1.4 ()

This survey form will allow you to run an online study. It runs in a very similar fashion to Bill’s online survey script, but has several notable improvements:

Setup of this survey form is a breeze. Simply download and unzip this zip file. Place the contents in their own folder. Make customizations to the files as necessary (details below), and when you are finished, point participants to the “study.php” file. That’s it!

Customization

In order to customize the survey form, you need to open the various files in a text editor like Notepad, Wordpad, or my personal preference, Notepad++ (which should be available on school computers, and is also free to download).

Initial Setup

First, open up “study.php” in your text editor. At the top of the file are a couple important variables to edit:

$email = 'userid@uwaterloo.ca'; // displayed if participants experience errors $requiredLogin = 'none'; // valid values: 'sona', 'password', or 'none'

Be sure that you only change what is in between the quotation marks (or what is highlighted red above). The text after the double-slash (//) gives a bit more detail about what each variable does.

The $requiredLogin variable accepts three values. If set to 'sona', participants will only be able to view the study if a Sona ID is passed through the URL (using ?sonaid=12345 at the end of the URL). If set to 'password', participants must log in using a given user ID and password (more details about this under passfile.txt). If set to 'none', no login is required, and anyone may access the study.

Directly below this is a variable identifying the various conditions of the study.

$conditions = array( array('a', 'b', 'c'), array('1', '2') );

The $conditions variable accepts studies of any complexity. Each row represents an independent variable, which is wrapped in an array() and separated by a comma. Inside each array() is a list of the levels of the independent variable. These can be named essentially anything you wish, but I would recommend keeping it short (one or two letters/numbers). When choosing a condition, the script will randomly select one of the levels for each variable.

Here are some examples of other studies that could be run:

// one IV with four levels $conditions = array( array('a', 'b', 'c', 'd') ); // three IVs, in a 3x2x2 design $conditions = array( array('a', 'b', 'c'), array('1', '2'), array('left', 'right') ); // just a simple survey with no conditions at all $conditions = array();

Finally, the last variable that can be set is for block randomization:

$blockRandom = true;

Setting this to true will turn on block randomization, and setting it to false will just use normal randomization that may lead to fairly lopsided cell sizes. See my standalone block randomization script for more details.

Creating/Editing Pages

The zip file comes with some sample pages that can be used as templates for your own study. By default, the page order is as follows:

  1. index.html
  2. consent.html
  3. page1.html (or declined.html if consent is declined)
  4. ...
  5. pagen.html
  6. thanks.html

This page order is very flexible. If you don’t need a consent page, just delete the “consent.html” file (presuming that $requiredLogin is not set to 'password', as this page is the page where participants can log in). If you need 17 pages, just create pages from “page1.html” to “page17.html”. The script will figure it out, and will skip over any missing pages in the default sequence. You may also specify your own page order if you wish.

There are a few specific constraints on page names and contents, as follows:

  1. “study.php” and “SurveyForm.php” cannot be renamed;
  2. “consent.html” (if it exists) must contain an HTML field called either "consent" or "vv0001", with values of "Accept" and "Decline"; and
  3. If $requiredLogin is set to 'password', “consent.html” must contain HTML fields named "sID" and "password".

Adding Variables to Pages

This survey form script allows you to name your variables whatever you wish. For example, a textbox could look like this:

Name: <input type="text" name="participant_name">

All the variable names are saved on the first line of your output file (output.txt), and if you use my output parser, it will automatically insert these names into the column headings of the resulting file. These variable names can also be used to insert responses from previous pages.

Your variables may be named whatever you wish, but they must be unique on the page (i.e. you can’t name all your variables “variable” or something), and they must contain only letters, numbers, hyphens, and underscores.

Setting Up Condition-Specific Content

There are two ways that you can set up content to be displayed for different conditions, and you are free to use whichever you prefer (or even both!).

First Method

The first way involves creating separate pages for each condition. This is done by naming page files in a specific fashion, such as “page1_a1.html”. The name of the file comes first, then an underscore, and then the designation of the condition. The script will always look for the most specific content first, and then move to less specific options. For instance, if I had a study with three independent variables, in a 3 (a, b, c) × 2 (1, 2) × 3 (x, y, z) design, and a participant was in the first level of each IV, the script would look for the page1 file in this order:

  1. page1_a1x.html
  2. page1_a1.html
  3. page1_ax.html
  4. page1_1x.html
  5. page1_a.html
  6. page1_1.html
  7. page1_x.html
  8. page1.html

Note that the order of the IVs listed in the filename is therefore important for two reasons. First, the script will not look for the condition ‘ax1’, because this is out of order (based on the order specified in the $conditions variable). Second, priority will be given to ‘a’ over ‘x’. This may cause conflicts if you have ‘a’-specific content and ‘x’-specific content for the same page. If this is the case, you may wish to use the second method below instead (or a combination of the two).

Second Method

The second way to set up condition-specific content involves condition inserts. These are specific codes that are read by the script to identify the proper content to be displayed. For example, if you wanted a specific word to be changed in “page1.html” based on your first IV, you could do so as follows:

… evaluate the following paragraph for its [%condition:'a':{meaning and coherence of arguments},'b':{grammatical structure},'c':{length}%]. Make sure you also …

Each condition insert must start with [%condition:, then include a comma-separated list of the contents to be displayed for each condition, then end with %]. This also goes from most specific to least specific (e.g., 'a1x' takes priority over 'a'). Any condition that is not represented will simply display nothing in that spot. The content to be displayed must come between the curly braces, and the only restriction is that you cannot use curly braces within the content. So, you can include HTML if you wish. While this means that you could show completely different questions to people in different conditions, I would recommend that you try not to as this may get very confusing when it comes time to look at your output.

Inserting Previous Responses

To insert a participant’s response from a previous page, put in an include insert. It looks like this:

[%include:'page4','response5'%]

This will include the participant’s answer to the variable called “response5” on page 4. Note that you should not include the “.html” in the name of the page, nor any condition-specific identifiers (e.g., don’t put 'page4_b3x'). The script will find the participant’s response regardless of what condition he or she is in.

You can also insert the variable number (i.e., if “response5” is the 5th variable on the page, so you could insert '5' instead of 'response5') if that makes easier for whatever reason.

If you wish to reference variables that were passed in through the URL (see below for details), set the parameter where the page name would go to 'url_variable' and then reference the variable name. For example, to access an ID passed in through the URL with ?participantID=12345, you would access it as follows:

[%include:'url_variable','participantID'%]

Specifying Custom Page Order

If you wish to name your files something other than the non-descript “page1.html”, “page2.html”, “page3.html”, etc., you may rename them whatever you wish (just no periods, and no underscores unless you’re specifying condition-specific content). Just add the following code to “study.php”, right underneath the $blockRandom variable:

$pageOrder = array( 'first-page', 'second-page', 'third-page', 'fourth-page' );

List the pages to be displayed, in order, without the “.html” at the end. Condition-specific content will still work properly, so you can have “second-page_a2y.html” if you wish. Note, however, that the login process will not work properly for participants unless you still have a “consent.html” page.

passfile.txt

The zip file includes a file called “passfile.txt”. This works identically to Bill’s script. Each user ID should be listed one per line, and its associated password should be on the same line separated by a space or tab character. You may pass in Sona IDs by including it on the same line, also separated by a space or tab character.

output.txt

Once participants begin completing your study, a file called “output.txt” will be created. This is essentially identical to the output file that Bill’s script provides. The major difference is that all the variable names for each page are stored on the first line of the output. Don’t delete this line—although if you do, it will just get recreated the next time the study is loaded.

Passing in Variables

Additional variables can be passed in through the URL. The most common one is the Sona ID, which can be passed in by adding ?sonaid=12345 to the end of the URL. Other variables can be passed in as well, if you wish, and should be separated by & characters (e.g., ?sonaid=12345&handedness=left&monkeys=lots). Keep in mind that participants will be able to see these variables in their address bar, so don’t pass in anything that ruins your deception. These extra variables will be stored in the output file.

Final Steps

As I said above, after you have customized your study to your liking, simply give the URL of the “study.php” file (e.g., “https://artsresearch.uwaterloo.ca/~username/the_study/study.php”). That’s it. No further setup needed. As long as the files are all in the same directory, everything should function correctly.

If you have any difficulties setting up your study, please email me (Jeff Hughes) and let me know. I’ll try to figure out what the issue is. Thanks!