2010-07-12
QPL Reference Manual

One of the design goals for QPL6 was to make the questionnaire program the only file you need to edit to create your web site and analysis files. The QPL system will now always rebuild your entire web site after you make a change to your program and recompile the files. Another goal was to make it easier to write and read your program. To meet these goals, the syntax for a number of QPL commands has changed.

New command key words have been added to to replace old option codes (that were often used as the first character in the first line of text for a question), and new key words have been added to automate formerly manual tasks, such as putting content into your project home page.

This page provides a number of before-and-after examples of how these features were programmed in QPL5 and how the same effect is achieved in QPL6.

HELLO Command

In QPL5, a project home page (hello.htm for the local version and index.htm for the web server version), is created the first time you compile your project. Then you would need to edit that HTML page it created to add your content such as welcoming information, instructions, and contact information.

In QPL6, you enter this same information in your QPL program inside a HELLO block in your questionnaire program file, and use the same text formatting conventions as you would for formatting the text of a question.

.HELLO = "Begin"
Welcome to the NRE computer-aided telephone interview web site that will be used 
record interviews with federal officials
to determine the extent to which the four major 
federal land management agencies (U.S. Forest Service, Bureau of Land Management, 
National Park Service, Fish and Wildlife Service) 
and the Bureau of Reclamation have data about the amount of: 

=federal land and resources they manage; |
=federal land subject to land use designations; and |
=revenue generated from selected activities on federal lands.

For questions, contact \<a href\=\"mailto:katzz\@gao.gov\"\>Zoe Katz\</a\>.
.HELLO = OFF

The HELLO block starts with the HELLO command. You may specify the label for the log in button that appears at the bottom of the home page. In this case, it will be label, "Begin."

Then enter your content, taking care keep each line less than 500 characters long. It does not matter where you break your lines of text; they will be re-wrapped when displayed by the respondent's browser.

Use a blank line to create a space after the paragraph.

This example also demonstrates the use of some of the new QPL6 formatting short-cut characters. The equal sign (=) will be replaced with the bullet character and the vertical bar (|) will be replaced with a line break character when the QPL compiler builds your web pages. (See Text Format Options for more information.

Also note that HTML tags may be entered in your text but that the special HTML characters must be escaped using the back slash character (\).

The HELLO block ends with another HELLO command with the OFF option.

The home page is rebuilt every time you recompile your project. Never edit the hello.htm or index.htm files; your changes would just be lost the next time you recompile your project. Only change your content inside the HELLO block and then recompile your project.

HELP Command

Both QPL5 and QPL6 let you enter your project contact information (i.e., who to contact if you have questions about using the web survey site) once and then display it in a variety of pages, such as the page that is display after a person exits your questionnaire or in an error occurs and a Notice page is displayed.

In QPL5, your project contact information would be entered on the web site after the project was deployed by the System Administrator.

In QPL6, you can put your contact information in a HELP block in your questionnaire program file. This information will be put on the menu on the left side of the questionnaire page, on the exit page, and in any error Notice pages that may be displayed.

.HELP = ON
For questions, contact \<a href\=\"mailto:katzz\@gao.gov\"\>Zoe Katz\</a\>.
.HELLO = OFF

The HELP = ON command starts the HELP block, and ends at the HELP = OFF command.

You may enter your contact information next. While there is no limit on how long your contact information may be, there is limited space to display it on the questionnaire menu.

Format your text using the same methods as you do when programming questions.

HIDE Command

Hidden questions are used as places to store data about a respondent which you have preloaded from some data source when you deploy your project on a web server. This data can be used within the text of other questions on the survey form to customize the wording to a particular respondent. And the data loaded into a hidden question will be included with the answers to visible questions when you export the survey results for analysis.

In QPL5, a question was hidden by putting the number '0' (zero) into the first column of the first line of the question text. Only STRING and NUMBER questions could be hidden.

QPL5

.QUESTION = Q1, TYPE = STRING
0This is a hidden question.
.ANSWER = 35
.NEXT

In QPL6, questions are hidden by putting them inside a HIDE block. Any number of questions my be hidden inside one HIDE block. Any type of question may be hidden. Generally, these questions are put at the top of your program before the visible questions.

QPL6

.HIDE = ON

.QUESTION = RNAME, TYPE = STRING
Pre-loaded name of respondent.
.ANSWER = 35
.NEXT

.HIDE = OFF

In both QPL5 and QPL6, you may use the name of a hidden question in square brackets to display the current contents of a hidden question within the text of another visible question.

.QUESTION, TYPE = MULT
Welcome [RNAME]!

What is your favorite color?
.ANSWER
Red
Green
Blue
.NEXT

Here, if you had preloaded the name, "Jack Taylor," in the hidden RNAME question for this reponsdent, then he would see this question as shown below.

Welcome Jack Taylor!

What is your favorite color?

NEWPAGE Commands

Both QPL5 and QPL6 let you divide your questionnaire into any number of pages. You may put any number of questions on one page. If you use more than one page, navigation buttons are automatically added to let the respondent move forwards and backwords through the pages.

In QPL5, the option character '>' used at the start of a SUBTITLE string was used to indicate when a question should start on a new page.

QPL5

.QUESTION = Q36, TYPE = STRING
.SUBTITLE = ">My Subtitle Goes Here"
My question
.ANSWER = 35
.NEXT

In QPL6, a new page is started when you use the NEWPAGE command.

QPL6

.NEWPAGE
.SUBTITLE = "My Subtitle Goes Here

.QUESTION = Q36, TYPE = STRING
My question
.ANSWER = 35
.NEXT

Unlike QPL5, you may start a new page without also declaring a subtitle in QPL6.

.NEWPAGE

.QUESTION = Q36, TYPE = STRING
My question
.ANSWER = 35
.NEXT

In this case, the label for the link to this page on the menu will default to the page number, such as "Page 3."

You may, however, use the NEWPAGE option to name the page link on the menu.

.NEWPAGE = "My Page Link Label Goes Here"

.QUESTION = Q36, TYPE = STRING
My question
.ANSWER = 35
.NEXT

The label for this page link will be, "My Page Link Label Goes Here." Since no SUBTITLE command was used, no title will appear at the top of this questionnaire page.

SUBTITLE Command

The SUBTITLE command is used to label a group of one or more questions. This label will also be displayed in the list of links in the menu to the left of your questionnaire that lets a respondent navigate through your form.

In QPL5, the SUBTITLE command had to be used inside the question it was associated with. It also could be used with the '>' option to start this question on a new page when your project is deployed on a web server.

QPL5

.QUESTION = Q36, TYPE = STRING
.SUBTITLE = "My Subtitle Goes Here"
My question
.ANSWER = 35
.NEXT

In QPL6, the SUBTITLE command may now be put before the question that it is associated with. This makes your questionnaire program more readable.

QPL6

.SUBTITLE = "My Subtitle Goes Here"

.QUESTION = Q36, TYPE = STRING
My question
.ANSWER = 35
.NEXT

The '>' option is no longer used to break pages. This option has been replaced with the NEWPAGE command, which is discussed above.

QNUMBERING Command

QPL automatically numbers the visible questions in your questionnaire, and uses these numbers when it displays links for skip instructions to add to multiple-choice or check-all-that-apply questions. If you add a new question to your program and recompile, all the questions will be automatically renumbered including any skip instructions.

In QPL5, you could suppress the question numbering for an individual question by putting the '#' character at the start of your question text. This question would be not be numbered, and the question numbering would continue at the next question.

QPL5

.QUESTION = Q37, TYPE = VOID
#This question will not have a question number.
.ANSWER
 
.NEXT

In QPL6, this option has been replaced by the QNUMBERING command, which also adds more numbering options. To suppress the numbering now, you must set the QNUMBERING command to OFF. All off the questions that follow this command will not be numbered until you use this command again and set it to ON.

QPL6

.QNUMBERING = OFF

.QUESTION = Q37, TYPE = VOID
This question will not have a question number.
.ANSWER
 
.NEXT

.QNUMBERING = ON

The QNUMBERING command must be used outside of a question block.

MATRIX Command

Normally, QPL will layout each question vertically, with the question text above the answer field. You may optionally choose a horizontal, or matrix, option which puts the question text on the left and the answer field on the right. It also stacks multiple questions in this layout together in rows so it is suitable for a series of related questions that have the same type of answer field.

In QPL5, this layout was implemented using various option characters (+, =, -) at the start of the text of each question to control when the matrix layout started and ended. A second digit could also be used to control the row shading and automatic question numbering.

QPL5

.QUESTION = Q35, TYPE = MULT
+What is your favorite color?
.ANSWER
Red
Green
Blue
.NEXT

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

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

In this example, the + sign option in each question was used to create on group of questions that will be displayed horizontally with the questions in the left columns and the colors as row headings in the right columns. Radio buttons are put in the intersections of the columns and rows of the layout.

In QPL6, this same effect is now done using a MATRIX block. Set this command to ON before your first question in a block, and then end the block by setting it to OFF after the last question.

QPL6

.MATRIX = ON

.QUESTION = Q35, TYPE = MULT
What is your favorite color?
.ANSWER
Red
Green
Blue
.NEXT

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

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

.MATRIX = OFF

The same rules apply about what question types may be used inside the same MATRIX block. A MATRIX block may only contain all MULT questions with the same answer list, or all CHECK questions with the same answer list. Other types of questions that have only one answer field, such as STRING or NUMBER, may be mixed in the same MATRIX block.

Also notice in the QPL6 example that the answer list of a previous question will be automatically copied to the next question if the next question has the same question type and has no specifically defined answer list. So here, the same list of colors will be used for questions Q35, Q36, and Q37.

POPUP Command

Sometimes it is useful to give the respondent additional information about question only when they need it. A common technique is to insert a link that, when clicked by the respondent, will display a new, smaller, browser window that contains the information such as a glossary of terms or an expanded definition. This is sometimes called a "popup" window.

In QPL5, you had to use a template HTML file to enter your extra information using HTML tags, and then create a special anchor tag that used JavaScript that would launch your special popup web page in a new window.

In QPL6, special popup windows may be created using a POPUP block inside your questionnaire program. Inside the block, you write your text using the same techniques as you do when writing questions. You may create any number of POPUP blocks in your program. You give each POPUP block a unique name, and then use that name delimited by carets (^) in the text of a question where you want the link to that popup window to appear.

.POPUP = MYBACKGROUND
.TITLE = "background information"
This survey is being conducted 
as part of our effort to study these
issues. We will report your responses
to Congress.
.POPUP = OFF

...

.QUESTION = Q1, TYPE = VOID
Welcome to our survey.

If you would like more information
about our survey please see the ^MYBACKGROUND^.
.ANSWER
.NEXT

Here, one pop-up window is created using the name, MYBACKGROUND, and a title "background information." A link to this pop-up has been inserted into question Q1 by using the name of the question surrounded by caret (^) characters. When you compile your program and view your questionnaire in a browser, ^MYBACKGROUND^ will be replaced with a hypertext link called "background information." When you click the link, the MYBACKGROUND popup box will be displayed.

POPUP blocks may be put anywhere in your program though they are usually put near the beginning, after your home page information and before the start of your questions.

You may use any number of links to the same popup box in questions in your program.

SUMMARY Command

Although each page of a multiple page questionnaire is displayed with a Print button, pressing this button would only just print that page. Further, if a respondent typed a very long response to an OPENEND question, such that the respondent needed to use the scroll bar on the form control to see all of the contents, only the text was visible at one time in the form control would be printed.

In QPL5, you could get around this limitation by adding a page after your last question that contained a VOID question with an anchor tag that used JavaScript to run a program on the web server that would generate a new web page that summarized all of the respondent's answers.

This is no longer necessary in QPL6. A link in the menu to the left of your questionnaire form called "View and print a summary of your responses." is created by default when you compile your program. Clicking on this link creates a new browser window the current respondents answers.

You may, if you wish, remove this link from the menu by setting the SUMMARY command to OFF.

.SUMMARY = OFF

The summary report that is displayed has also been enhanced slightly. In QPL5, if the respondent had not answered a STRING or MULT question, then that question would not be included in the report. In QPL6, the question is included with a note that the answer is blank. Also, the report is automatically updated with any changes the respondent made to the page they were viewing when they clicked the summary report link.

You may still use the drop variable (/dv name...) or keep variable (/kv name...) CONVERT Options to control what questions are included in the report. A new option, hidden question (/hq) has been added that drops all of the hidden questions from the report without having to specifically name them (on the CONVERT Options line in your program if you are using the HomeSite HTML editor).