2009-08-03
QPL Reference Manual

The QPL HomeSite add-in tools can simplify creating your project and getting it ready to deploy on your web server.

To take advantage of these tools, you should always use the "Create New Project" button () on the QPL tool bar to start a new project. The Create New Project button creates a template program and fills your project directory with all of the standard web site files.

QPL Tool Bar

Steps to Create a New Project

  1. Use the Windows Explorer to create a new folder for your project. (Each QPL project must be put in its own folder.)
  2. Close any open documents in HomeSite.
  3. Click once on the Create New Project button () on the QPL tool bar.
  4. Save the new program template in your new project folder. (Do not type any spaces in the file name. While Windows allows spaces, Linux does not. You will run into problems later if you will be deploying your project on a Linux-based web server. Also, do not type a file name extension. It will automatically be given a ".pg6" extension.)

The Create New Project button will save the program template in your project directory, insert your project's name into the file, and then copy of the standard QPL web site files to this directory. Now you may begin writing your QPL program by editing the program template file.

QPL Program Template

*****************************************************************************
** PROGRAM:                                                DATE:           **
**  AUTHOR:                                                 JOB:           **
**                                                                         **
**   TITLE:                                                                **
**                                                                         **
** PURPOSE:                                                                **
**                                                                         **
**                                                                         **
**                                                                         **
**                                                                         **
**                                                                         **
***************************************************************************** 
** CONVERT Options: /d /f /l /v /u
** BUILD Options: /s= /d= /p= /u=
***************************************************************************** 
** Global Settings

.TITLE = "Title Goes Here"
.SUBTITLE = "U.S. Government Accountability Office"
.CARD = 200

***************************************************************************** 
** Questions

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

.QUESTION = FINISH, TYPE = MULT
Have you finished this questionnaire?
.ANSWER        * The last answer, 'No,' will be checked by default.
Yes
No
.NEXT

Note: Do not delete the "CONVERT Options" and "BUILD Options" comment lines. These lines are used in HomeSite to modify how QPL will build your questionnaire web site. Use of these option lines are discussed in the Deploying a QPL Project That Was Built Using HomeSite™ page.

You can use the buttons on the right end of the QPL tool bar to help write your questionnaire program. They guide you through the options that may be used and then insert the question into your program at the current cursor position. You can further edit the question after it has been inserted into your program. The button on the QPL tool bar, for example, may be used to program a multiple choice question.

See the QPL Language Syntax page for a complete discussion of this programming language.

Building a Local Test Version of Your Questionnaire

You can build a version of your questionnaire that you can view with your browser without first deploying it on your web server. This version will look and act nearly identical to the web server version. It will put your whole questionnaire in on page and include the names you used for each question. It will not, however, be broken into pages (if you specified multiple pages), show the log in screen, or store or retrieve data from a data base.

This version of your questionnaire is intended to let you quickly develop a number of iterations of your instruments, make modifications and view the results instantly with your browser. You may also easily print the single page, with the variable names, to facilitate your note taking during pretests and modifications to the questionnaire program later.

When you are ready to deploy your survey, see Deployment for instructions on how to create the web version.

Steps to Create a Local Test Questionnaire

  1. Open your source questionnaire program in HomeSite (this file must have a ".pg6" file name extension).
  2. Press the HTML button () on the QPL tool bar.

Your questionnaire program will now be compiled and then converted into a set of HTML programs. If your program contains any syntax errors, a message will be displayed on the screen and all the lines in your program with errors will be bookmarked. Another document will also be loaded that lists all of the error messages. This document will have the same name as your program but will have a ".err" file name extension.

If your program compiles successfully, several web pages will also be built:

hello.htm
main.htm
menu.htm
job.htm

Note: The word "job," will be replaced with the name of your questionnaire program file.

Steps to View a Local Test Questionnaire

  1. Open the hello.htm file
  2. Click on the "Browse" tab at the top of the edit window (the home page is displayed)
  3. Click on the "Start log in" button on the home page (the questionnaire with the menu and navigation bar is displayed)
  4. Click on the "Cancel" button to close the questionnaire
  5. Click on the "Edit" tab at the top of the edit window to return to the editing mode

Steps to Make Changes in Your Program

  1. Open your source questionnaire program in HomeSite
  2. Edit the your program
  3. Press the HTML button () on the QPL tool bar again

Your program will be recompiled and, if that was successful, new HTML files will be created.

hello.htm

The hello.htm file is the home page for your questionnaire. This is the first page that your respondent will see when they start your questionnaire. This page contains a "Start log in" button that launches your questionnaire. You can open this file with your browser (or use the Browse tab in HomeSite) to view this file. You can also press the "Start log in" button to view your questionnaire as if it was deployed on a web server. That is, it will be launched with the menu of sections on the left, the navigation tool bar on the bottom, and your questionnaire in the main part of the screen. This lets you see how all the pieces will come together before it is deployed.

You should edit this file where indicated to add welcoming information about your questionnaire. This information could include:

Sample Home Page Information

<P>Welcome to the U.S. Government Accountability Office's     
Survey of GAO Assistant Directors on Access to Records.</P>

<P>You will need the user name and password that we sent you in an
e-mail message to log onto this system.  You can, if you want, change
your password at the log in screen by checking the "Change password"
option.</P>

<P>You may exit the questionnaire at any time by pressing the "Exit"
button at the bottom of the page.  The next time you log in, 
your questionnaire will be restarted at the last question you entered.
Whether or not you change your password, please remember to keep your 
password in a safe place.</P>

<P>You may log in to your questionnaire and edit your responses as often
as you like.  You may bookmark this page to make it easier to start 
the questionnaire again.</P>

<P>If you have any questions about this survey, please contact:</P>
Margaret Armen<BR>
Phone: (202) 512-8262<BR>
e-mail:  <A href="mail to: armenm@gao.gov">armenm@gao.gov</A></P>

<P>Christine Davis<BR>
Phone: (202) 512-8290<BR>
e-mail:  <A href="mailto:daviscf@gao.gov">daviscf@gao.gov</A></P>

<P>Thank you for participating in this survey.</P>

This page also determines if a respondent's browser allows JavaScript to be run on web pages and if so, which version of JavaScript it uses. If JavaScript has been disabled on the respondent's browser, the Start Log In button will not be displayed. Instead, a message will be displayed to the respondent that says that JavaScript must be enabled on his browser in order to use this questionnaire. If the respondent then enables JavaScript and refreshes this page, the Start Log In button will appear.

This page also specifies which data base should be used. You may run any number of QPL projects on your web server as long as each project is located in a separate directory on the server and uses a separate MySQL data base.

When you build the web server version of your project, by pressing the PHP button, a new home page file will be created called "index.htm." You will need to copy the welcoming information you added to the hello.htm file to this new file. This is necessary because the web questionnaire files are launched differently from the home page than your local test files. See Deploying a QPL Project That Was Built Using HomeSite™) for more information.

The hello.htm and index.htm pages are only created the first time you click on the HTML or PHP buttons on the QPL toolbar. Because of this, any changes you make to these files are not lost when you re-compile your questionnaire program. On the other hand, any changes you make to your project's title or subtitle will not be updated in these files if they have already been created. In this case, you can fix the titles either by deleting the hello.htm and index.htm files and then rebuilding the project, or by carefully editing the files.

You should not change the name of your project's .pg6 file name after it has been compiled. This name is used in the index.htm file to locate the data base that will be used for your project when it is deployed on a web server. Changing the name of a project that has already been compiled will result in files that will not correctly fit together when the project is deployed. If you need to change a project's .pg6 file name, you should either copy the renamed file to a new directory and build the new version of the project there or delete all the files in your current directory, except for the .pg6 file, and start building the the project from scratch (first clicking on the green button to recover fresh copies of the standard files, and then clicking on the HTML and PHP buttons to rebuilt your project).

main.htm

The main.htm file used to load the job.htm, menu.htm, and qpl_nav.htm (navigation bar) into frames in one browser window. This file is only created the first time you build a project. (A different version of this file, main.php, is created when you use the PHP button to create a version of your project that can be deployed on a web server. See Building the Web Version of Your Questionnaire Using HomeSite for more information.) This file can be edited so that the menu or navigation bar, or both, are not used. See Changing the Default Page Layout for more information.

job.htm

This is the HTML version of your questionnaire program (with the name of your program replacing the word "job"). You can view this file with your browser or by using the Browse tab in HomeSite.

This file looks and works the same as the web server file that you will create later with the following exceptions:

Everything else looks and functions as it will when you deploy the web server version:

You should not edit this file. If you make changes to your source questionnaire program, any changes you made here would be lost when you recompile.

You should not deploy this file to your web server. It does not contain any server-side programming that will capture the respondent's information and store it on a server. This version is only intended for for development.

This file, when created using the /e option, can be used as an email-able message. In this case, it is pasted into the "HTML Message" field of the "Edit Message" administrative page for your project. See the Email section of this manual for more informatiion.

Pop-Up Help

The Help button on the navigation toolbar at the bottom of the questionnaire page can be customized so that it displays your project administrator's name, phone, email address, or other information.

While you should put the contact information on your project's home page (index.htm) and your email message announcing the the survey, it is useful to put here too since it is accessable directly from any page on your questionnaire.

The contact information for the pop-up help is entered after the project has been deployed on the web server. The project System Administrator can set this after logging into the project and going to the Default Project Settings page. (Only the System Administrator can see and edit the settings on this page.)

Enter your contact information into the "Assistance note..." field "Default Project Settings" page. HTML coding may be used to create a working mailto link.

Sample Contact Information Snippet

If you have any questions about this survey, please contact:<br><br>
   
Jim Elgas at (202) 512-4173<br>
e-mail: <a href="mailto:elgasj@gao.gov">elgasj@gao.gov</a><br><br>

or<br><br>

Jose Ramos at (202) 512-2632<br>
e-mail: <a href="mailto:ramosj@gao.gov">ramosj@gao.gov</a><br>

At GAO, our routine is to copy the contact information from the home page (index.htm) as an HTML snippet and use it here.