2009-09-21
QPL Reference Manual

By default, the questions you program are listed in order down one web page, using a vertical layout (where the your the answer field for your questions always sits below the question it goes with), and are automatically numbered sequentially starting at "1." There are a variety of commands that you can use to change these defaults.

Labeling Groups of Questions

You may label a group of questions by using the SUBTITLE command. The label is put on your questionnaire page and in the menu. A respondent may click on the label in the menu to jump to that part of your questionnaire, automatically creating a hypertext table of contents.

SUBTITLE Syntax

.SUBTITLE = "title goes here"

Note: The uppercase words indicate QPL commands and options, an asterisk indicates a default option, and the square brackets indicate optional information.

The SUBTITLE is always attached to the question that comes next. The label itself must be must be put inside double quotes and must be on one line.

.SUBTITLE = "Your Feelings about Colors"

.QUESTION = Q1, TYPE = MULT
What is your favorite color?
.ANSWER
Red
Orange
Yellow
Green
Blue
Indigo
Violet
Don't know
.NEXT

In this example, the heading, "Your Feelings about Colors" will be put above question Q1 and into the menu. This will be displayed in the respondent's browser as shown below.

SUBTITLE: Your Feelings about Colors

If the respondent clicks the "Display list of headings" link in the menu, a list of all the SUBTITLEs will be displayed, grouped by page. A respondent may click on a heading in the list to jump to that location in your questionnaire.

SUBTITLE Listed in Menu

The SUBTITLE command may be used to attach a label to any normal-layout question in your program.

To label questions in a MATRIX or COLUMNS layout, you must use the SUBTITLE command before the first question in the MATRIX or COLUMNS block.

.MATRIX = ON
.SUBTITLE = "title goes here"

.QUESTION
...

.QUESTION
...

.MATRIX = OFF

Insert a Page Break

Since there is no particular limit on how many questions you may put into your QPL web questionnaire, it is generally a good idea to break your questionnaire into pages. This makes it easier for the respondent to navigate Since there is no particular limit to how long one page may be, you can keep logically-related questions together. Or, if you are concerned that your respondents may miss questions that are below-the-fold (that is, where the respondent must scroll to see them), you may choose to keep your pages short.

NEWPAGE Syntax

.NEWPAGE [= "menu label"]

Note: The uppercase words indicate QPL commands and options, an asterisk indicates a default option, and the square brackets indicate optional information.

The NEWPAGE command only may be used outside of a QUESTION block. The next question after the NEWPAGE command will be started on the next page.

The NEWPAGE command may not be used on the first question or on any hidden question.

The NEWPAGE command is often used with the SUBTITLE command so that the question at the start of the next page is labelled with a heading.

.SUBTITLE = "More Questions about Colors"
.NEWPAGE

.QUESTION = Q2, TYPE = MULT
What is your favorite color?
.ANSWER
Red
Orange
Yellow
Green
Blue
Indigo
Violet
Don't know
.NEXT

In this example, question Q2 will start at the top of the second page and have the heading, "More Questions about Colors." This label will also be used in the menu.

NEWPAGE: More Questions About Colors

NEWPAGE and SUBTITLE

While this is the typical way to use the NEWPAGE command, there are other options.

Desired Result Syntax
Use the same label for the questionnaire page and the menu .SUBTITLE = "questionnaire label"
.NEWPAGE
Use different labels for the questionnaire page and the menu for the same location .SUBTITLE = "questionnaire label"
.NEWPAGE = "menu label"
Insert a page break but only put a label in the menu .NEWPAGE = "menu label"
Insert a page break but only put an automatically-generated label in the menu
(labels will be "Page" plus the current page number as in "Page 2")
.NEWPAGE

There is no option to create a page break but not put a hypertext link into the menu table of contents.

You may use the NEWPAGE command before question that is inside a MATRIX or COLUMNS block of questions. The MATRIX or COLUMNS layout will be broken (as if a MATRIX=BREAK or COLUMNS=BREAK command had been used) and then restarted on the next page. A SUBTITLE may be used immediately after the NEWPAGE, if desired, to label the new page.

Automatically Numbering Questions

Questions are automatically numbered starting at "1." You may change how they are numbered in various ways. You can turn the numbering off, change the starting number, or number using letters or a combination of letters and numbers.

These numbers are always put on the page that the respondent sees to the left of the question text. The width of this part of the page is set using the PAGEGUTTER command. They are also used when you put skip instructions into your questionnaire, such as when using a GOTO command on an answer to a multiple choice question. The skip instruction will be displayed on the page with the number of the question, such as "GO TO QUESTION #5."

QNUMBERING Syntax

.QNUMBERING [= ON* | OFF | INCREMENT | "#"]

Note: The uppercase words indicate QPL commands and options, an asterisk indicates a default option, the pound sign indicates a number, and the square brackets indicate optional information.

The QNUMBERING command must be used outside of a QUESTION block and changes the how the next question is numbered. The QNUMBERING setting remains in effect until another QNUMBERING command is used.

The automatic numbering also affects how questions will be automatically named.

By default, QNUMBERING is ON and will start numbering at "1."

Setting QNUMBERING to OFF stops numbering questions until another QNUMBERING command is used. Setting it back to ON continues the numbering where it left off.

.QNUMBERING = ON

.QUESTION = Q1
...

.QNUMBERING = OFF

.QUESTION = Q2
...

.QUNUMBERING = ON

.QUESTION = Q3
...

In this example, QNUMBERING is turned on at the start so question Q1 will be "1." Then it is turned off so question Q2 will not be numbered. And finally its turned back on before question Q3 so Q3 will be numbered "2."

You may also use the command to specify a starting number. You may set it to a decimal number, lower-case letter, upper-case letter, or a combination of a letter and number. Letter-based numbers are limited to two characters.

.QNUMBERING = "a"

.QUESTION = Q1
...

.QUESTION = Q2
...

.QUESTION = Q3
...

In this example, the starting number is set to "a," so the questions will be automatically numbered a, b, c.

.QNUMBERING = "A1"

.QUESTION = Q1
...

.QUESTION = Q2
...

.QUESTION = Q3
...

.QNUMBERING = INCREMENT

.QUESTION = Q4
...

In this example, the starting number is set to a combination number: A1. The "A" portion of the number is not changed from question to question until the QNUMBERING command is used again with the INCREMENT option. This option increments the major part of the number (in this case, A) and resets the minor portion of the number (back to 1, a, or A as appropriate). So here, questions Q1 to Q3 will be numbered: A1, A2, and A3. Question Q4 will be numbered: B1.

See more examples in Sample 1.

Hiding Questions

Though it may sound odd, there are a several reasons why you may want to put hidden questions into your questionnaire form. Since, in QPL, a question is just a place to put data, a hidden question is a place where you can put data that is hidden from the respondent. So this is how you can add data to a respondent's questionnaire record, such as some information that you already know about him, which will not be displayed on the form but will be exported from the web site with his answers to your questions. This can speed up your statistical analysis since you will not need to match the questionnaire data with other data.

It is also an easy way to personalize a questionnaire for a particular respondent. Since you can display the answer to a hidden question within the text of a visible question using the [name] syntax, you can preload each respondent's questionnaire data record information about them, such as the name of a specific program that you are asking about.

They can also be handy as a place to put questions that are not to used to hold data, but instead are just used as a place to define answer settings that you use elsewhere in your program using the .ANSWER = name syntax. Here, you are just speeding up your programing by defining, for example, a list of answers to a multiple choice question that you later use elsewhere in your program.

Hidden questions may be put anywhere in your program, but are typically put at the top in one group to make it easier to keep track of them. They do not need to be used on the same page where you use the [name] syntax to display a the answer to a hidden question.

HIDE Syntax

.HIDE [= ON | OFF*]

Note: The uppercase words indicate QPL commands and options, an asterisk indicates a default option, and the square brackets indicate optional information.

The HIDE command must be used outside of a QUESTION block. It changes the setting for all of the following questions until another HIDE command is used. Using the it without an ON or OFF option toggles the current status of the HIDE command.

.HIDE = ON

.QUESTION = Q1, TYPE = MULT
Color list template
.ANSWER
Red
Orange
Yellow
Green
Blue
Indigo
Violet
Don't know
.NEXT

.QUESTION = Q2, TYPE = STRING
Respondent's full name, pre-loaded before start of survey.
.ANSWER = 30
.NEXT

.HIDE = OFF

.QUESTION = Q3, TYPE = MULT
[Q2], what is your favorite color?
.ANSWER = Q1
.NEXT

This example shows a couple uses of hidden questions. Here, HIDE is set to On at the start so questions Q1 and Q2 will not be displayed on the web form. The first question that will be displayed will be Q3, which will be automatically numbered as "1" since its the first visible question.

Question Q1 is just being used as an answer list template. While a column for this question will be created in the database, called Q1, it will always just be set to the value 8, since this question will default to the "Don't know" response. Question Q3 copies this answer list by setting ANSWER = Q1.

Question Q2 is defined to be a 30-character string field. If this respondent's data record is loaded with this set to his name, then question Q3 will display he starts the questionnaire.

The HTML preview of this program is shown below. Here, the underscore is used to show where the [Q2] value will be inserted when this project is installed on a web server.

HIDDEN Questions

The contents of hidden questions can only be set by writing an SQL program. This is typically done as part of setting up a project for deployment on your web server. Usually you will write an SQL program that creates both user account records and data account records. Below is a very brief example.

update1.sql Sample SQL Script

# update1.sql
# K. Dooley
# 2009-08-19
#
# Load user account and data records.
#

USE myfirstproject;

INSERT INTO user (q_uname, q_name, q_pswd) VALUES
	('able', 'Arthur Able', 'mango'),
	('baker', 'Bob Baker', 'banana'),
	('charlie', 'Chuck Charlie', 'melon');
	
INSERT INTO data (q_uname, Q2) VALUES
	('able', 'Arthur Able'),
	('baker', 'Bob Baker'),
	('charlie', 'Chuck Charlie');

In this example, the project was named myfirstproject.pg6, so the database name will be myfirstproject. One account is created for each of three respondents: able, baker, and charlie. The QPL 'user' table's q_uname field holds the respondent's user name, which he uses when logging in. Questionnaire records are put are put into the 'data' table. It also has a q_uname field which links this questionnaire record back to a user account. The second input statement puts the respondents' real name into the Q2 field was created with the hidden Q2 question above.

So, after the project is installed on a web survey and this update1.sql script is run to add these user accounts and data records, Arthur able will see his name in question Q3 after he logs in: "Authur Able, what is your favorite color?"

See the Deployment section of this manual for more information about creating respondent and administrator accounts, and preloading respondent information.

Set Question Width

A question is formatted inside a box that always has a specific width, but stretches vertically to hold your question and answer field. Your question text will be word wrapped inside the question text area of the box using the box's WIDTH setting. The charts below shows the edges of this box in red for a question using the default, or normal, layout, and in the MATRIX and COLUMNS layouts.

The Question Box - Normal

Normal

For questions using the normal layout as shown above, the WIDTH may be set up to the total width that is available in the question area of the page. This is the current setting for PAGEWIDTH minus the room needed for the menu, which is always 150 pixels. If you are not using the menu, then you may set the WIDTH to be as large as the PAGEWIDTH setting.

The Question Box - MATRIX

Matrix

The WIDTH is used to set the width of the question text area on the left of the question box when the question is used in a MATRIX layout. The total size of the question box here defaults to the PAGEWIDTH size minus the room needed for the menu (150 pixels), if it is used, and the PAGEGUTTER which is used to display the question number (default is 35 pixels). The default WIDTH setting is half of the available space. You may use the MATRIXWIDTH command to set it to a smaller size. The answer columns will be evenly distributed using the remaining space (i.e., (MATRIXWIDTH - WIDTH)/ # of answer columns).

Only the WIDTH setting of the first question in a MATRIX is used to set the MATRIX dimensions. WIDTH settings on other questions in the MATRIX will be ignored.

If the answer columns appear unevenly sized, then your browser was not able to fit the contents and is trying to do the best it can to display your matrix questions. To fix this, you may make the WIDTH of the question text column smaller in order to provide more room for the answer columns, make your PAGEWIDTH wider, reduce the number of answer columns, or shorten the text in the answer columns.

The Question Box - COLUMNS

Columns

The width of column of questions in a COLUMNS layout is set by evenly dividing by the number of columns used from the total available question text area.

You may use the WIDTH command to change the width of invidual questions, but the total width of all the quesitons in a row may not exceed the available question text area. Only the WIDTH settings of the questions in the first row are used to set the column widths.

WIDTH and MATRIXWIDTH Syntax

.WIDTH [= #]        (1 to PAGEWIDTH-150 if menu is used, else PAGEWIDTH)
.MATRIXWIDTH [= #]  (320 to PAGEWIDTH-150 if menu is used, else PAGEWIDTH)

Note: The uppercase words indicate QPL commands and options, a pound sign indicates a number is used, the square brackets indicate optional information, and the information in parentheses show the range of allowable values.

WIDTH is always set using the number of pixels on the page (one inch is 72 pixels).

You can change the default setting for one or more questions in your questionnaire by using the WIDTH outside of a QUESTION block. All the following normal layout questions will use that width setting, or until another WIDTH command is used.

You can change the width of an individual question by using the WIDTH command inside its QUESTION block. Here, only the setting for this question is changed, not the current default WIDTH setting.

.WIDTH = 620

.QUESTION = Q1, TYPE = MULT
Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
Ut iaculis tempus lectus. Pellentesque quis commodo mauris. 
Nulla id turpis massa.
.ANSWER
Nam malesuada aliquet augue, id auctor eros aliquet quis.
Duis ac nisl vitae enim malesuada hendrerit.
Aenean at dui enim, at fermentum nulla.
.NEXT

.QUESTION = Q2, TYPE = MULT
.WIDTH = 300
Praesent dui quam, feugiat nec mattis at, auctor vel ligula. 
Integer blandit feugiat pharetra. Vivamus nulla leo, pharetra nec 
aliquam nec, vestibulum non elit.
.ANSWER
Suspendisse porttitor ipsum ipsum, non mollis purus.
Morbi mollis bibendum lectus, vitae varius neque rhoncus eget.
Integer pulvinar arcu ac nibh laoreet in porta nisi dapibus.
Curabitur consequat lacus ut lectus porta cursus.
.NEXT

.QU = Q3, TYPE = MULT
In interdum auctor sem eget tristique. Donec turpis nunc, tincidunt 
quis lobortis sit amet, blandit vel ligula. Nulla facilisi. Duis 
a lectus nisi. Aliquam fringilla accumsan mi, sed venenatis metus 
accumsan scelerisque.
.ANSWER
Suspendisse volutpat commodo ligula, ac fermentum justo viverra faucibus.
Nullam at nunc ut arcu semper fermentum vel sit amet ligula.
Proin vitae sapien vel magna tempus vehicula sed nec est.
Mauris id ipsum ut lorem imperdiet condimentum in at nibh.
.NEXT

.WIDTH
...

In this example, the first WIDTH command was used before any questions and so it sets the default for all normal layout questions to 620 pixels (the maximum the WIDTH could be when using a menu and the default PAGEWIDTH settings: 620 = 770 - 150). Question Q2 has a WIDTH command so it will over-ride the default and set the width for just this question to 300 pixels. Question Q3 has no default WIDTH so 620 will be used there. Finally, a WIDTH command is used without an option setting so the system default of 490 pixels will be restored and then used for any later questions.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut iaculis tempus lectus. Pellentesque quis commodo mauris. Nulla id turpis massa.
...
Praesent dui quam, feugiat nec mattis at, auctor vel ligula. Integer blandit feugiat pharetra. Vivamus nulla leo, pharetra nec aliquam nec, vestibulum non elit.
...
In interdum auctor sem eget tristique. Donec turpis nunc, tincidunt quis lobortis sit amet, blandit vel ligula. Nulla facilisi. Duis a lectus nisi. Aliquam fringilla accumsan mi, sed venenatis metus accumsan scelerisque.
...

The default WIDTH setting for questions in a MATRIX and COLUMNS layouts are independent of the WIDTH setting for questions in a normal layout. You may set the default MATRIX WIDTH by using the WIDTH command inside a MATRIX block before any questions. This sets the default width that will be used in later MATRIX blocks. This works the same way for questions in COLUMNS blocks, though is generally less useful.

.MATRIX = ON
.WIDTH = 200

.QUESTION
...

.MATRIX = OFF

...

.MATRIX = ON

.QUESTION
...

.MATRIX = OFF

Here, the default width with of the question text stub was set to 200 pixels for all the questions in the first MATRIX block. This 200 pixel setting will also be used in the next MATRIX block. But, since the WIDTH command was used inside a MATRIX block, it does not change the default width for normal or COLUMNS questions.

Laying-Out Questions Horizontally

By default, questions are put on your web page vertically with the text of your question on top and the answer input field(s) below. You can save space on your form when you have a series of questions that have the same answer list by laying them out horizontally with the question text on the left and the answer input field(s) arrayed in columns in same row on right.

MATRIX Layout

To change the layout of one or more questions, you must put the questions inside a MATRIX block. There are no changes needed to the questions themselves. This lets you easily experiment with your layout by just adding and removing the MATRIX starting and stopping commands around a group of questions in your program.

MATRIX Syntax

.MATRIX [= ON | OFF* | BREAK]
[.MATRIXROWSHADING [= ON* | OFF] ]
[.MATRIXDKSHADING [= # | ON* | OFF] ]
[.MATRIXWIDTH [= #] ]  (320 to PAGEWIDTH-150 if menu is used, else PAGEWIDTH)
[.WIDTH [= #] ]        (1 to PAGEWIDTH-150 if menu is used, else PAGEWIDTH)
[.BOLD [= ON | OFF] ]
[.ALIGN = [ ON | OFF ] ]
[.ANUMBERING [= ON | OFF | "1" | "A" | "a"] ]
[.INDENT [= ON | OFF* | # ] ]

Note: The uppercase words indicate QPL commands and options, an asterisk indicates a default option, the pound sign indicates a number, and the square brackets indicate optional information.

To put one or more questions into a horizontal layout, you first must set the MATRIX command to ON. Then all of the following questions will be put into a horizontal layout until you set the MATRIX to OFF.

The MATRIX = BREAK option lets you break a long list of questions into groups. This is typically used when listing multiple choice or check-all-that-apply questions to in order to re-display the column headings for the answer values. It may be important to re-display the answer labels if it is likely that the respondent can not see them when answering a question in the matrix because the label row has scrolled off his screen.

The MATRIXROWSHADING command controls whether the MATRIX will be displayed with special alternating row shading. This shading makes it easier for a respondent to see that questions are arranged in rows. It is ON by default. Setting it to OFF removes the row shading.

The MATRIXDKSHADING command may be used to shade the right-most columns in a MATRIX of MULT questions. By default, if there are more than two answer columns, the last column will be shaded. In this case, the right-most column is usually the "Don't know" answer so this shading is intended to visually separate this from the other answers, such as an extent scale. Setting it to a number sets the number of right-most columns to be shaded (if, for example, you wanted to distinguish between a "No answer" and a "Don't know" situation, you would set this to 2 to shade the two right-most columns). (Note: You may also use the ! syntax to shade individual columns.)

The MATRIXWIDTH command may be used to change the width of the MATRIX. By default it is set to the total available width of the question area of the web page. You may set the width to the number of pixels. And this works with the WIDTH command which may be used to set the size of the question text area. (See discussion of the WIDTH command above for more infomation.)

The MATRIXROWSHADING, MATRIXDKSHADING, MATRIXWIDTH commands are optional and their default values will be used in your MATRIX block if you omit them. If you use one, then that new value will become the default value that is used for this and all later MATRIXes, or until the command is used again to change the value. For example, if you use the MATRIXROWSHADING command to turn the shading off in your first MATRIX, it will also be set to OFF in all your later MATRIXes unless you use it again to turn shading back on.

The WIDTH, BOLD, ALIGN, ANUMBERING, and INDENT commands are also listed here because their default settings can be different for questions in a normal layout and in MATRIX and COLUMNS blocks. When any of these commands is used outside of a MATRIX block, then it sets the default for all of the following questions including questions inside of MATRIX blocks. But, if it is used inside of a MATRIX block, then it sets the default for only questions in this and later MATRIX blocks. (This behavior is the same for COLUMNS blocks.) This lets you adjust these display options in just your first MATRIX block. You may omit them in later MATRIX blocks since they will be automatically carried forward. You can use this to make your programming more efficient since you can adjust your settings for all or a series of MATRIXes in one place.

.MATRIX = ON
.WIDTH = 200

.QUESTION = Q1, TYPE = MULT
What is your favorite color?
.ANSWER
Red
Orange
Yellow
Green
Blue
Indigo
Violet
Don't know
.NEXT

.QUESTION = Q2, TYPE = MULT
What is your mother's favorite color?
.ANSWER
.NEXT

.QUESTION = Q3, TYPE = MULT
What is your father's favorite color?
.ANSWER
.NEXT

.MATRIX = OFF

In this example, three questions (which all have the same answer list) are put into one MATRIX block. MATRIX is set to ON before the first question then set to OFF after the last question. The WIDTH command is used to reduce the size of the question text area on the left from the default (half of the available question area on the form) to allow more room for the answer columns.

Answer lists do not need to be explicitly written for questions Q2 and Q3 since they immediately follow question Q1 and are the same type of question (MULT) as question Q1.

MATRIX Layout

As you can see above, the answer list is displayed in a heading row across the top of the MATRIX. This same heading row is also created if you are creating a MATRIX of check-all-that-apply (CHECK) questions. The respondent may also see the label for a particular radio button or check box by hovering his mouse pointer over it.

You may mix different types of non-MULT and non-CHECK questions together in one MATRIX since the other types of questions only have one answer input field (and thus always only need on answer column in the MATRIX layout).

.MATRIX = ON
.MATRIXROWSHADING = OFF
.WIDTH = 150
.ALIGN = RIGHT
.BOLD = ON

.QUESTION = Q8, TYPE = STRING
What is your name?
.ANSWER = 35
.NEXT

.QUESTION = Q9, TYPE = NUMBER = "### years"
How old are you?
.ANSWER
.NEXT

.QUESTION = Q10, TYPE = LDATE
When did you graduate from High School?
.ANSWER
.NEXT

.MATRIX = OFF

Here, STRING, NUMBER, and LDATE questions are mixed together in one MATRIX layout.

The MATRIXROWSHADING command is used to turn the alternating row shading off. The WIDTH command is used to narrow the space used for the question text. The ALIGN command is used to right-align all the question text, and the BOLD command is used to display all the question text of all the questions in the MATRIX.

MATRIX with mixed question types

Here, you can see the affects of modifying the default MATRIX options. Also note that no heading row is used when the MATRIX contains non-MULT and non-CHECK questions.

See more examples in Sample 1.

Laying-Out Questions in Columns

You may use the COLUMNS command to array your questions in two to 25 columns across the web page. This lets you do things as simple as just putting two questions next to each other horizontally, or creating a large spreadsheet-like table with many columns and rows.

COLUMNS Layout

Like the MATRIX command, you must use the COLUMNS command to start and end a block of questions you wish to have in your layout. You do not need to make any changes to the questions themselves. But, unlike the MATRIX layout, you may use any type of question in one COLUMNS block.

COLUMNS Syntax

.COLUMNS [= # | ON | OFF | BREAK]
[.COLUMNSHEADINGS [= ON | OFF*] ]
[.COLUMNSROWSHADING [= ON | OFF*] ]
[.WIDTH [= #] ]        (1 to PAGEWIDTH-150 if menu is used, else PAGEWIDTH)
[.BOLD [= ON | OFF] ]
[.ALIGN = [ ON | OFF ] ]
[.ANUMBERING [= ON | OFF | "1" | "A" | "a"] ]
[.INDENT [= ON | OFF* | # ] ]

Note: The uppercase words indicate QPL commands and options, an asterisk indicates a default option, the pound sign indicates a number, and the square brackets indicate optional information.

To put two or more questions into a COLUMNS layout, you first must set the COLUMNS to the number of columns you wish to have. Then all of the following questions will be put into the columns row by row. For example, if you are using two columns, the first question after the COLUMNS command will be put in the first column of the first row, the second will be put into the second column of the first row. Then the third question will start the next row, etc., until you end the block by setting the COLUMNS command to OFF.

You must fill your COLUMNS block completely with questions. That is, each row in the block must have a question for each column.

Questions are always put into a COLUMNS block using the normal, or vertical layout. (You may not use MATRIX command to put them in horizontally.) By default, questions are just put into columns and rows one after another just as they would appear normally with the question text on top and the answer fields below.

You may not use the HIDE command to prevent questions from being displayed inside a COLUMNS block.

By default, the available space for questions is evenly divided so that each of your columns has the same width. You may use the WIDTH command inside the questions in the first row of your COLUMNS block to adjust the size of individual columns. The total width of the questions in the first row, however, may not exceed to the total space available for questions.

Setting the COLUMNSHEADINGS to ON will instead use the question text from the first row of questions to create a header row across the top of the COLUMNS layout. Then below this only the answer fields of your questions are put into the layout.

The VOID question type has special behavior when COLUMNSHEADINGS is ON. Unlike other question types, its question text is put into the row with the answer fields of other questions and its answer text is put into the heading row at the top with the question text of other questions (i.e., its behaviour is opposite of the rest of the types of questions). This lets you label individual rows in your COLUMNS layout.

The COLUMNSROWSHADING command may be used to shade the rows of your COLUMNS layout in alternating colors. This is OFF by default.

The COLUMNSHEADINGS and COLUMNSROWSHADING commands are optional and their default values will be used in your COLUMNS block if you omit them. If you use one, then that new value will become the default value that is used for this and all later COLUMNS, or until the command is used again to change the value. For example, if you use the COLUMNSROWSHADING command to turn the shading on in your first COLUMNS, it will also be set to ON in all your later COLUMNS unless you use it again to turn shading off.

The WIDTH, BOLD, ALIGN, ANUMBERING and INDENT commands are also listed here because their default settings can be different for questions in a normal layout and in MATRIX and COLUMNS blocks. When any of these commands is used outside of a COLUMNS block, then it sets the default for all of the following questions including questions inside of COLUMNS blocks. But, if it is used inside of a COLUMNS block, then it sets the default for only questions in this and later COLUMNS blocks. (This behavior is the same for MATRIX blocks.) This lets you adjust these display options in just your first COLUMNS block. You may omit them in later COLUMNS blocks since they will be automatically carried forward. You can use this to make your programming more efficient since you can adjust your settings for all or a series of COLUMNS in one place.

.COLUMNS = 2

.QUESTION, TYPE = MULT
What is your favorite color?
.ANSWER
Red
Orange
Yellow
Green
Blue
Indigo
Violet
Don't know
.NEXT

.QUESTION, TYPE = OPENEND
.OPENENDCOLS = 25
.OPENENDROWS = 5
Please explain why this is your
favorite color.
.ANSWER
.NEXT

.COLUMNS = OFF

In this example, two columns are created since the COLUMNS command was set to "2." And since only two questions are used, they will be put side-by-side on the page and then the layout will go back to normal.

Simple COLUMNS Layout

As you can see here, the questions are put into evenly spaced columns. The answer field for the OPENEND question was resized (using OPENENDCOLS = 25) to make it fit better in its column.

.QUESTION, TYPE = VOID
The next questions ask about you and your family. Please answer them
to the best of your ability.
.ANSWER
.NEXT

.COLUMNS = 3
.COLUMNSHEADINGS = ON
.QNUMBERING = OFF

* Row 1 --------------------- 

.QUESTION, TYPE = VOID
Tell me about you.
.ANSWER
Person
.NEXT

.QUESTION, TYPE = STRING
Name
.ANSWER = 10
.NEXT

.QUESTION, TYPE = NUMBER = "##"
Age
.ANSWER
.NEXT

* Row 2 --------------------- 

.QUESTION, TYPE = VOID
Tell me about your mother.
.ANSWER
Person
.NEXT

.QUESTION, TYPE = STRING
Name
.ANSWER = 10
.NEXT

.QUESTION, TYPE = NUMBER = "##"
Age
.ANSWER
.NEXT

* Row 3 --------------------- 

.QUESTION, TYPE = VOID
Tell me about your father.
.ANSWER
Person
.NEXT

.QUESTION, TYPE = STRING
Name
.ANSWER = 10
.NEXT

.QUESTION, TYPE = NUMBER = "##"
Age
.ANSWER
.NEXT

.QNUMBERING = ON
.COLUMNS = OFF

This example demonstrates a number of things you can do with a COLUMNS layout.

First, it is common to use a VOID question before a group of questions in a COLUMNS layout to introduce or explain to the respondent how to complete the following questions.

Then the layout is set to use three columns, and the COLUMNSHEADINGS command is set to ON so that the questions from the first row will be used to label the columns in the layout. Since this is set to ON, VOID questions can be used to label each row in the layout.

The QNUMBERING command is set to OFF so that none of the questions in the layout will be numbered, making it appear to the respondent as if they all belong to the leading VOID question.

Comments are used to mark each row of your questions. These are just for your convenience to make it easier to keep track of your questions. Each row in the layout must have one question for each column in your layout.

Finally, the COLUMNS layout is turned off and the question numbering is turned back on.

Advanced COLUMNS Layout

See how the question question text from the VOID questions has been used to label each row of the layout, but that the question text from the first row of questions is used to create column headings at the top of the layout.

The question text you enter for later rows of questions (other than VOID questions) is not displayed at all on the web page. The text of these questions, however, is used when the QPL compiler is used to build your SAS or SPSS statistical analysis program or when when viewing the Summary Statistics page on your web site (after logging in as an administrator) so you may want to make them more descriptive than this example. (Note: You may use the LABEL command to replace the question text of the first row of questions with something that is more descriptive for your later analysis.)

See more examples in Sample 1.

Indenting Questions

By default, normal questions, and MATRIX and COLUMNS layouts are left-justified on the page. You may use the INDENT command indent the entire question, MATRIX, or COLUMNS layout to the right. The amount of space used for the question text is reduced by the amount of space used for the indent, so that the overall size of the layout is not changed.

INDEX Syntax

.INDENT [= ON | OFF* | # ]

By default, the INDENT is set to OFF (i.e., the INDENT amuont is zero). Setting it to ON indents a question by the current PAGEGUTTER size (default is 35 pixels). You may also specify an indent size by setting it to the number of pixels.

.QUESTION, TYPE = STRING
What is your name?
.ANSWER = 20
.NEXT

.QUESTION, TYPE = STRING
.INDENT = ON
What is your name?
.ANSWER = 20
.NEXT

In this example, the INDENT is set to ON in the second question so it is moved to the right by the amount of the PAGEGUTTER setting.

Second question is indented

Like other question format commands, such as BOLD and ALIGN, the INDENT command may be used outside of a question to change the default setting for all questions that are using the normal layout. The changed default setting will affect all of the following questions until another INDENT command is used.

.INDENT = ON

.QUESTION, TYPE = STRING
What is your name?
.ANSWER = 20
.NEXT

.QUESTION, TYPE = STRING
What is your name?
.ANSWER = 20
.NEXT

In this example, the default INDENT is set to ON so all of the following questions using a normal layout will be indented by this amount.

Normal global indent is on

The INDENT command may be used when starting a MATRIX layout to indent the whole layout to the right.

.MATRIX = ON
.INDENT = 35

.QUESTION, TYPE = STRING
What is your name?
.ANSWER = 20
.NEXT

.QUESTION, TYPE = STRING
What is your name?
.ANSWER = 20
.NEXT

.MATRIX = OFF

In this example, the default INDENT is set to 35 pixels so all of the questions in the MATRIX layout be indented.

Matrix indent is on

Individual questions within a MATRIX layout may not be separately indented.

A COLUMNS layout may be similarly indented by using the INDENT command at the start of the COLUMNS layout. The width of each column in the layout will be proportionally reduced by the amount of the indent, so that right edge of the layout remains unchanged.

.COLUMNS = ON
.INDENT = 35

.QUESTION, TYPE = STRING
What is your name?
.ANSWER = 20
.NEXT

.QUESTION, TYPE = STRING
What is your name?
.ANSWER = 20
.NEXT

.COLUMNS = OFF

In this example, the default INDENT is set to 35 pixels so all of the questions in the COLUMNS layout will be indented.

Columns indent is on

Since the INDENT forces are readjustment of the columns, any WIDTH command used must be after the INDENT command, or inside a question in the first row.

The INDENT command may be used on individual questions that are in the first row of a COLUMNS layout. An INDENT used here will set the indent for all of the questions in the same column.

If you are not numbering the questions in the COLUMNS layout, you may set the INDENT to a negative number to outdent a column of questions to reclaim some of the space used by the PAGEGUTTER. The negative indent size must be less than the width of the PAGEGUTTER. For example, if the PAGEGUTTER is set to 35 pixels, then the maximum negative indent allowed is 34 pixels.

.COLUMNS = 2
.COLUMNSHEADINGS = ON
.COLUMNSROWSHADING = ON
.INDENT = ON  * Indent the COLUMNS block

.QUESTION, TYPE = STRING
What is your first name?
.ANSWER = 20
.NEXT

.QNUMBERING = OFF

.QUESTION, TYPE = STRING
.INDENT = -34  * Outdent this column of questions
What is your last name?
.ANSWER = 20
.NEXT

.COLUMNS = OFF

In this example, the first INDENT indents the COLUMNS block by the amount of the PAGEGUTTER setting (default is 35 pixels). The second INDENT outdents the second question into the number gutter space, which gives the second question a greater width. If this COLUMNS block had more rows, all of the questions would inherit the same negative indent.

Negative indent on second question in columns layout

See more examples in Sample 1.