Coding Questionnaires with jsp

Is current?: 
Yes

Coding Questionnaires with jsp

Topics covered in this tutorial:

A. Why jsp?

B. Explanation of the jsp template basics

C-D. Editing the Questions and Responses

E. Fancy (but easy!) options: text presentation, randomization, planned missingness

F. Common Errors

 

A. Why jsp?

There are other templates available for collecting questionnaires, demographics and related data … why use jsp?

- For a detailed list of the options and features of jsp, go here (link coming soon! for now, see text at the very end...)

- In short, this template:

  • presents users with one question at a time
  • users select their response by clicking on it (versus a drop-down menu)
  • is ideal when you have many questions and want to minimize: 1. question-skipping, and 2. your coding time

 

B. The Code - Basics

Files:

jspbasic.jsp (template)

 

Overview:

The template file contains: a bit of header information that sets up global options, then a section that defines the response options/scales, then a section defining the questions, then a few lines to call the questions … and then 1300 lines of code to run the questionnaire that you needn’t touch!

 

Don’t Change

Lines 1-4: Set up the language, encoding, etc.

Lines 6, 7, 9: Options related to display of questions and response options

 

You Might Change, But Probably Not

Line 8: Default font type, size and colors [1]

 

IMPORTANT! You will edit

Lines 14-20: response options/scales

Lines 26-33: question text, plus the scale/options to use from the names above

 

You Might Change, If You Start to Get Fancy

Line 36, 40: Call the questions defined in lines 26-33

 

After line 40 … don’t touch it!

 

[1] Colors are html hexidecimal codes. Want chartreuse text on a medium aquamarine background? See below for an exhaustive list of colors and codes http://www.computerhope.com/htmcolor.htm

 

C. Editing the Response Options

The response options are defined in template lines 12-21. The name of the group of response options is defined (line 12), there is a line for general options (line 14), then the individual response options are listed (lines 15-20). The entire group of response options is delimited by curly brackets “ { “ and “ } “ (lines 13 and 21). Every line 14-20 must have a comma after it, and all the information in a given line is itself surrounded by curly brackets. For the response options and the questions (below), the lines that you edit should be of the general format:

{ {“info”} , {“info”} , {“info” , “info” ,”info”} },

... the most common error is to forget a single quote, curly bracket or comma (it’s easy to do!)

 

Line 12: String[][][] ratings =

This defines the name of the response options, which we are calling "ratings". Do not change this name.

 

Line 14: {{"ratings"},{"ncols","1"},{"flow","horizontal"},{"direction","left"}},

The options global to this group of response options. You do not need to change these.

The different scales or response options you want are listed in lines 15-20. They are generally of the format: name the option set (so you can refer to it later when defining the questions), list the response options (buttons)

Line 15: {{"rate1"},{"options","Male", "Female"}},

 

rate1: the scale name that you will call later, pairing it with 1 or more questions. Must be unique to this file.

options: do not change the word “options”, but after it enter your response options, surrounded by quotes “ ” and delimited by commas “ , “

 

The next response options have code between the name and the response options themselves. This extra code specifies that these response options are different from the others, in this case, because you want the response buttons listed in 9 columns instead of 1 long column. Each of the 3 pieces of information: 1. name of the response options, 2. extra specifying code, 3. response options themselves, is enclosed in curly brackets and delimited by a comma.

Line 16: {{"rate2"},{"ncols","9"},{"options","[18..64]","65+"}},

this specifies to have the numbers 18 to 64 as separate buttons, then the button “65+”, all in 9 columns of buttons.

 

D. Editing the Question Text and Calling Options from Above

The questions are defined in template lines 24-34. Similar to the response options, the name of the set of questions is defined (line 24), there is a line for general options (line 26), then the individual response options are listed (lines 27-33). The entire question set is delimited by curly brackets “ { “ and “ } “.The template has just one “set” of questions, a set being questions that are given a name (here, “basic”) and defined between two curly brackets. More than one set is possible (see Fancy #1). The format of this code is very similar to the response options above.

 

Line 24: String[][][] basic =

This defines the name of the set of questions, in this case “basic”. You can change it if you like, but the name in lines 24, 26 and 38 must match!

 

The line 26 defines some options for this set of questions (and only those questions given this name and within this set of curly brackets):

Line 26: {{"basic"}, {"nelem","7"}, {"musthave","0"}, {"group","0"}, {"gminmax","7.7"}, {"gplace","0"}, {"gorder","0"}, {"gsequence","fixed"}, {"prefix","<br/>Please respond to the following question.<br/>"}},

 

basic: the questionnaire name, or whatever name you’d like for this set of questions … you can change if you like BUT IT MUST MATCH THE NAME IN LINES 24 and 38!!!

nelem: number of elements (questions) in this set

gminmax: also number of elements … these 3 numbers must match if you want all the questions to appear

musthave, group, gplace, and gorder: deal with fancy options like presenting a random subset of the questions in the set to participants, you will most likely leave these alone

gsequence: “random” or “fixed”.  “Random” will randomize the order of questions within this question set. “Fixed” will present the questions in the order you list them.

prefix: general directions that appear above each and every question. Can be omitted, just delete all the content {"pre … question.<br/>"} and make sure that the ending characters }, appear after your last option, e.g.  

…"}, {"gorder","0"}, {"gsequence","fixed"}},

 

Lines 27-33 are the actual questions in this set. They are of the format: 1. Variable name, 2. Which of the response options should be put with this question (“choices”), 3. Question text (“stem”). Again, each piece of information is surrounded by curly brackets and delimited by a comma, with a comma at the end of the line and the whole line surrounded by curly brackets.

Line 27: {{"gender"},{"choices","rate1"},{"stem","What is your gender?"}},

 

gender: the name of your variable in the output file. Must be unique in the ENTIRE STUDY (unless you like headaches).

rate1:  the scale from above to display with this question

stem: like the options line above, don’t change the word “stem” but put the question text here. You can use the html tags <u> </u>  to underline, <b> </b> to bold and <i> </i> to italicize some or all of the text.

 

Note: you can have a scale that is defined in the first set of code (template lines 14-20), but never paired with a question. It isn’t ideal to have a lot of extra scales that aren’t called, but the code will run without problem. You cannot, however, put a scale name next to a question if that scale is not defined earlier.

 

Lines 36-40 call the set or sets of questions from above:

ArrayList <String[][][]> scales = new ArrayList <String[][][]> ();

  scales.add(basic);

int nscales= 1;

 

Again, the name “basic” MUST match the name you’ve given the question set above (template lines 24 and 26).

int nscales is the number of scales. It’s 1 here, see below for examples > 1.

 

E. Getting Fancy

 

Here are some not quite “advanced” but potentially useful options in jsp-land

  1. Two questionnaires, one fixed and the other random within that questionnaire

          - bonus code: intro screen!

  1. Multiple-select options – participants can indicate 1 or more boxes

          - bonus code: colors and special characters!

  1. Planned missingness: having participants answer only a random subset of questions from a questionnaire

 

Getting Fancy 1: One fixed-order question set, one random-order question set

Files:

jspfancy1.jsp (template)

 

Lines 1-10 are the same as the basic template.

 

The same scales are included in the “ratings” section, and one is added in line 15:

{{"inst1"},{"options","Next"}},

… this is to print a “Next” button on the instructions page (below)

 

The following “questions” set is added in lines 25-29. This will code an intro screen with no questions and the text above. Participants will get to “practice” the sequence “click once to select and turn the button yellow, twice to move on.” This might be useful if you are concerned people won’t understand the system on your first “real” question. The text beyond “stem” can be edited to anything you like.

 

String[][][] instruct =

{

{{"instruct"}, {"nelem","1"}, {"musthave","0"}, {"group","0"}, {"gminmax","1.1"},{"gplace","0"},{"gorder","0"},{"gsequence","random"},{"prefix","<br/>Instructions:<br>"}},

{{"inst01"},{"choices","inst1"},{"stem","Before we begin the study, we'd like to ask you a few questions about yourself. Please answer the following questions by selecting the box that best describes your answer."}}, 

};

 

Lines 31-46 take the 7 questions from the basic jsp and split them into 2 scales.

The “basic” scale now has 4 questions about demographics and will be presented in a fixed order:

String[][][] basic =

{

{{"basic"}, {"nelem","4"}, {"musthave","0"}, {"group","0"}, {"gminmax","4.4"}, {"gplace","0"},{"gorder","0"},{"gsequence","fixed"}},

{{"gender"},{"choices","rate1"},{"stem","What is your gender?"}},

 

The “colors” set has 3 questions and will be presented in a random order:

String[][][] colors =

{

{{"colors"}, {"nelem","3"}, {"musthave","0"}, {"group","0"}, {"gminmax","3.3"}, {"gplace","0"},{"gorder","0"},{"gsequence","random"}},

{{"color"},{"choices","rate5"},{"stem","Of the choices listed below, what is your <u>favorite</u> color?"}},

 

Each of these sets of questions will need their own line of options that are general to the set (lines 33, 42), and need the same format of commas and curly brackets as before. Other than that, the questions code is the same as when all 7 questions were in 1 set.

 

Lines 50-54 specify the order of the scales, and that 3 are to be presented. Line 54 must match the number of scales.add lines.

  scales.add(instruct);

  scales.add(basic);

  scales.add(colors);

int nscales= 3;

Getting Fancy 2: Multiple-Select and Fancy Text

 

Files:

Jspfancy2.jsp (template)

Jspfancy2.expt.xml (experiment file that runs the template)

 

Lines 1-10 are the same as the basic template.

 

For simplicity, only 4 questions are used in this example.  Lines 14-18 present the scales.

Line 16 has 2 new options

{{"rate2"},{"maxsel","3"},{"minsel","1"},{"options","<span style='color:#2554C7'>Blue</span>","<span style='color:#FF0000'>Red</span>","<span style='color:#FFFF00'>Yellow</span>","<span style='color:#FFA500'>Orange</span>","<span style='color:#347C2C'>Green</span>","<span style='color:#4E387E'>Purple</span>","Black"}},

maxsel and minsel specify that between 1 and 3 options may be selected for questions using this scale.

Instead of just listing the option Blue as usual, “Blue”, this code makes the actual text blue (see list of colors in link above).

"<span style='color:#2554C7'>Blue</span>"

 

Line 17 introduces special characters and font colors

{{"rate3"},{"options","<span style='color:#E4287C'>&hearts;</span>","<span style='color:#347C2C'>&clubs;</span>","<span style='color:#4E387E'>&Omega;</span>","<span style='color:#2554C7'>&diams;</span>","<span style='color:#737CA1'>&psi;</span>"}},

… instead of plain text between the “ <span …> </span> “ tags, there are codes indicating various special characters. Special characters (including arrows, umlauts, etc) can be used with text, any place where you would normally enter text, e.g. question text, instructions, response options. There are many lists online, for example see

http://htmlhelp.com/reference/html40/entities/symbols.html

 

Getting Fancy 3: Item Subsets, or Planned Missingness

 

Files:

Jspfancy3.jsp (template)

 

Everything is the same as the basic template, except for line 26:

{{"basic"}, {"nelem","7"}, {"musthave","1"}, {"group","0"},{"gminmax","3.3"}, {"gplace","0"},{"gorder","0"},{"gsequence","random"},{"prefix","<br/>Please respond to the following question.<br/>"}},

musthave specifies that item 1 must always be displayed

gminmax specifies that 3 items will randomly be selected from the set of 7 to display (but #1 will always be displayed, set musthave to 0 to have no items guaranteed to be selected). If you entered {"gminmax","1.7"} then some set of items will be selected, which could include between 1 and 7 (all) questions

gsequence indicated that the order of the questions will also be random

 

F. Common Errors

If your code does not run at all (you see a page of errors and no questions), you may have:

- forgot a comma at the end of an option or a semicolon ( ; ) at the end of a section, missing a quote ( “ ) or parenthesis ( {  } )

- you changed the name of the questionnaire in 1 spot and did not update it in the other two (template lines 24, 26 and 38)

 

If your code runs but isn’t what you wanted, you may have:

- a scale/question mismatch

            For example, in the options section …

            {{"rate1"},{"options","Male", "Female"}},

            {{"rate2"},{"options","Blue","Red","Yellow","Orange","Green","Purple"}},

            In the questions section …

            {{"color"},{"choices","rate1"},{"stem","What is your favorite color?"}},

            {{"gender"},{"choices","rate2"},{"stem","What is your gender?"}},

… these are switched, the color question should be paired with scale rate2, and the gender question with the scale rate1

- more than 1 scale with the same name, for example:

            {{"rate1"},{"options","Male", "Female"}},

            {{"rate1"},{"options","Blue","Red","Yellow","Orange","Green","Purple"}},

                 … will only use the 2nd scale for questions calling “rate1” , so the code

            {{"gender"},{"choices","rate1"},{"stem","What is your gender?"}},

                 … will display the question

            What is your gender?

            Blue           

            Red           

            Yellow                etc.

- more than 1 question with the same name

            {{"gender"},{"choices","rate1"},{"stem","What is your gender?"}},

            {{"gender"},{"choices","rate2"},{"stem","What is your age?"}},

… this will display the age question twice. If you see a question twice in a row, check your variable names to make sure they are unique!

- added a question to the set but forget to update the nelem and gminmax – very likely the problem if, when testing, the questions run but stop at a certain point, and hitting the buttons does not advance the question

 

If the changes you’ve made aren’t showing up when you re-run the study

- it’s likely that the cache needs to be refreshed. This can be done by clicking the jsp cache refresh on your study folder index page.  See here (link coming soon!).

 

 

Why Use jsp?

Some advantages and features of this jsp template:

- Users click on the answer they want, rather than selecting from a drop-down menu. This is more intuitive and user-friendly, particularly for a large number of items (state or country of residence are good examples)

- One question is presented at a time, with an index of what question the user is on.

- Participants may decline to answer, but they must decline every question individually by clicking in a little box on the lower right, the position of which moves around depending on the scale. It is much easier for users to just answer the questions, and so overall response rates are higher than formats where many questions can be declined at once.

- When you code a questionnaire, you only enter in the scale once, and each question that calls that same scale refers to that code. In other formats you might have to enter the same scale every time, which can be annoying for long questionnaires.

- Advanced options (some to be taught later!) are possible

- dependencies: user will see another question if they select some options and not others

Example A: one response option is “Other” and if selected follow-up information is asked

Example B: users select their highest level of education, if they have attained a degree they are asked their area of study, if they have a HS education or less they do not see the follow-up question

- free response text box

- text validation

Example: asked for zip code, code checks to make sure 5 numbers are entered. If user enters “banana”, a pop-up window asks them to enter numbers. The number of times a pop-up window alerts the user can be changed (alerts every time, alerts only the first time).

- multiple responses

Example: ethnicity/race question that mimics the census format

- However, if you want a matrix of questions – for example, a scale at the top and multiple questions in rows, all on the same page, you will need to use html

- Overall, jsp is most useful if many questions are needed (e.g. detailed demographics and a questionnaire or four)

 

 

To view the files below once you have them uploaded to your directory on pi.psyc.virginia.edu, use the link  https://pi.psyc.virginia.edu/implicit/showfiles.jsp?user=YOURNAME&study=DIRECTORY

If you didn't put the file in a directory, use the link: https://pi.psyc.virginia.edu/implicit/showfiles.jsp?user=YOURNAME&study=

For example: https://pi.psyc.virginia.edu/implicit/showfiles.jsp?user=hschaefer&study=

Comments

Some of you may want to change the direction of the response options to counterbalance the order in which response options are presented. For instance, let's say you want half of your participants to see male first and you want half of your participants to see female first. Here's what your code would look like...

In the ratings section...

// Male presented first
{{"rate1a"},{"direction","left"},{"options","Male", "Female"}},

// Female presented first
{{"rate1b"},{"direction","right"},{"options","Male", "Female"}},

In the basic section you would then create a separate variable for each order...

{{"gender1a"},{"choices","rate1a"},{"stem","What is your gender?"}},
{{"gender1b"},{"choices","rate2a"},{"stem","What is your gender?"}},

Finally, you can collapse gender1a and gender1b in your data (maybe in a new variable gender1) after you have checked that there are not order effects.

Right now the questionnaire/page title is default set to "Survey: Section 1." You will probably want to update this at some point to match the name of your questionnaire. To do that, go to...

Line 802:
<title>Survey: Section 1</title>

And just like you would in a basic html file, here you would update the title text between the title tags.