2009-08-11
QPL Reference Manual

There are a number of project-wide commands that you may use to control what people see when they arrive and leave your web site, and how they may use your web site to access questionnaires.

Project Title and Subtitle

A project always has a title and subtitle that displayed at the top of the home page, log in page, case selection page (if used), the first page of your questionnaire, and the exit page. These are also used to label the summary statistics page a respondent may view and are used as labels in the SAS and SPSS statistical programs that the system can create.

TITLE and SUBTITLE Syntax

.TITLE = "title goes here"
.SUBTITLE = "subtitle goes here"

Your TITLE and SUBTITLE labels must be put inside double quotes and must fit on one line.

.TITLE = "My Questionnaire Project"
.SUBTITLE = "My Company"

Here, the project title will be "My Questionnaire Project," and the subtitle will be "My Company," on all the web site pages.

You may modfiy the project title and subtitle after you project has been installed on a web server. To do this, you log in as an administrator and then go to the Default Project Settings page and make your changes.

You may use the QPL format shortcuts to modify the appearance of your text when displayed in the respondent's browser, such as using italics to highlight a word.

You may only set the project title once in your program. The first SUBTITLE command you use will become the project subtitle. Later SUBTITLE commands will be used to label sections of your questionnaire.

Including Another File in Your Program File

If you will be routinely modifying the standard phrases in your QPL projects, you can put all of your changes into one .pg6 file and then use the INCLUDE command to insert your new phrases into your program.

INCLUDE Syntax

.INCLUDE = "path\filename.pg6"

The INSERT command tells the QPL compiler to stop reading your main questionnaire file, then read the contents of your included file, and then continue reading your main questionnaire file again, as if the two files were one big program. Thus, where you put the INSERT command depends upon what you are inserting.

You can put any type of QPL commands in an include file. And you may use any number of INCLUDE commands in your program. Further, your included files may themselves contain INCLUDE commands.

.INCLUDE = "c:\qpl_utils\my_phrases.pg6"

In this example, the program file called "my_phrases.pg6," will be inserted into the current program where the INCLUDE command was used. It is usually a good idea to include the full pathway to your file if it is not located with your main program.

Creating Your Project Home Page

Projects always have a starting, or "home," page that is the first thing that a respondent sees when he comes comes to your web site. This page is used to welcome a respondent to the site, confirm to him that the site is genuine (such as by including a commercial security certificate logo), provide some background information about the survey or indicate what he needs to complete the survey, and provide contact information should he need help or have questions.

This is just an ordinary HTML web page that a respondent can see without logging in. He may also bookmark this page to make it easier to come back to the survey later. (Note: Individual pages of the questionnaire form may not be book-marked because the respondent is first required to log in before the system will show a questionnaire page.)

The home page also tests whether a respondent's browser allows JavaScript, which is a programming language that runs inside the respondent's browser and is required by the QPL system. If the respondent has JavaScript turned off, the log in button will not be displayed (preventing him from logging in). Instead, he will see a message that says JavaScript is required to use the system.

On the live production server, the home page is always put into a file called index.htm. Usually, web servers are configured so that this file will be displayed if a person enters a URL that only points to a folder on a web server. So, for example, you may give someone a link to your web site such as "https://www.mywebsite.com/myproject/" instead of the complete path to the file, "https://www.mywebsite.com/myproject/index.htm."

When building your local test files, the home page is always put into a file called hello.htm. Here, you may view the hello.htm file with your browser and click on the log in button to display your finished questionnaire. Although the log in page is not displayed and the local version of your questionnaire is not split into pages, it does give you an opportunity to see how information on your home page fits with information on your questionnaire as you step through the same pages as the respondent without the extra work of installing the project on a web server.

You create the contents of your home page in your QPL program file using the HELLO command.

HELLO Syntax

.HELLO [= ON | "Begin"]
	...
	...
.HELLO [= OFF]

The home page information must be put inside a HELLO block. The starting HELLO command may be set to ON, or may be set to the label you want to use for the log in button that is displayed at the bottom of the page. By default, this button will be labeled, "Begin questionnaire."

There is no particular limit to how much text inside a HELLO block, though you should consider how long the page will be when viewed by a respondent. Generally, it is good to only have a few paragraphs of information so that the log in button is visible on the page with out scrolling.

The text for the home page is entered using the same rules as entering text for questions. (See Text Format Options.

You should not edit the index.htm file that this system creates. It is recreated every time you recompile your program so any changes you make will be lost.

.TITLE = "Survey of School Districts That Have Eliminated Reduced-Price Fees in the ..."
.SUBTITLE = "U.S. Government Accountability Office"

...

***************************************************************************** 
** Hello page

.HELLO
+Welcome to our survey!+

To log into the questionnaire, you will need the user name and password that we sent you. 

You may bookmark this page to make it easier to start the questionnaire again. 

We suggest that you review the questionnaire before completing it on line to determine 
if consultation with others is needed. Click \<a title\=\"Get PDF copy of survey\" 
href\=\"studentmeals1.pdf\"\>here to download a PDF read only copy\</a\> for
review purposes. (You will need Adobe Acrobat Reader software to view this PDF file.) 
Please feel free to share this PDF file with others within your school district who may have 
expertise on specific questions or sections of the survey. However, please have only +one+ 
individual enter the collected data into the actual web questionnaire.

Please complete this questionnaire within about two weeks of receipt or by +December xx, 2008+.  
We understand there are great demands on your time; however your cooperation is critical to 
providing the Congress with complete and balanced information on the experiences of
school districts that have eliminated reduced-price fees for students.

If you have questions, please contact either:

Caitlin Cricke at 312-220-0000, (\<a href\=\"mailto:Cricke\@gao.gov\"\>Cricke\@gao.gov\</a\>) or 

Rosa Torres at 312-220-0001, (\<a href\=\"mailto:Torres\@gao.gov\"\>Torres\@gao.gov\</a\>) 
.HELLO

This is a typical example of how to construct a "hello" page. After the project is compiled, this will appear to the respondent as shown below.

Sample finished home page

The phrase that appears at the bottom of the page, "Click on the button below to begin.," may be changed using the default phrase syntax. The code for this phrase is 216.

.216 = "Click on this button to start the questionnaire."

This example shows how to use the default phrase syntax to change the sentence to "Click on this button to start the questionnaire."

Using a graphic on your home page that visually identifies your organization is a good way to help reassure the respondent that he has the right web site.

You can use a JPEG, GIF, or PNG graphic file as a logo. PNG files are preferred as they can be made with transparent backgrounds which will let your logo blend well with your project's color scheme.

The graphic logo is always put at the bottom of the home page below the log in button. Generally, you will want to size your logo graphic so that it is about 250 pixels wide by about 100 pixels tall, although this is flexible.

After creating your graphic file, you should copy it to your QPL project development folder with your QPL program. You should not use any spaces or uppercase letters in the file name (this will save trouble-shooting problems later if you deploy your project on a Linux, Unix, or Mac web server where file names are case sensitive and are not so easily handled if they have spaces). Then, in your questionnaire program you use the LOGO command to tell the QPL compiler to use your graphic logo file.

LOGO Syntax

.LOGO = ON* | OFF | "file name"  [ = "alt tag phrase..." ]

Note: The asterisk indicates the default and the square brackets indicate optional information.

You also may use the LOGO command to not display a logo graphic by turning if OFF.

If you set it to the name of your graphic file, you may also add a phrase that will be displayed to the respondent if he hovers his mouse cursor over the graphic.

.LOGO = "mygraphiclogo.png" = "My Graphic Logo"

In this example, the PNG graphic file, mygraphiclogo.png, has been copied to the project directory. The LOGO command will modify the home web page to show this graphic at the bottom of the page, and the browser will display the label, "My Graphic Logo" when the respondent hovers his mouse cursor over it.

Logging In To Your Project

A key part of running your questionnaire web site not only involves creating the form, but also managing how each or your respondents may access their copy of your form which has their personal responses. The QPL system has a number of scenarios that you may choose from to fit your particular application.

QPL bases its management of respondents by maintaining a user account list that is separate from the questionnaire results list. When your web site is deployed, you can use its administrative pages to see and edit user accounts, including creating new accounts, changing passwords, closing accounts, and putting certain accounts into groups. Every respondent must have a user account before they may complete a questionnaire. The questionnaire a respondent completes is marked with the user name he used to log in with.

A respondent may log into your project as often as he wishes until his account expires or you close the account.

If you plan to tightly control who may respond to your questionnaire, you should create an account for each respondent before you launch your project and then only allow people with existing accounts to access it. There are several ways to create an account for a respondent. You may...

If you do not know who the respondents are, you may...

All of these scenarios are controlled using the following commands.

ACCOUNT, AUTHENTICATION, and EXPIREDATE Syntax

.ACCOUNT = EXIST* | CREATE | ANONYMOUS
.AUTHENTICATION = NORMAL* | LDAP
.EXPIREDATE = yyyy-mm-dd

Note: The asterisked (*) options show the default setting that will be used if the command is not used in your program. The EXPIREDATE must be set using this year, month, day format (ex. 2010-12-01).

ACCOUNT and AUTHENTICATION scenarios

ACCOUNT Options

OptionComment
ANONYMOUSNo account is required. Anyone will be allowed to respond to the questionnaire. No log in page is displayed to the respondent and no user information is collected (unless you ask specific questions as part of your questionnaire). A respondent must finish the questionnaire in one sitting; he cannot reopen his questionnaire and update the responses later. A new blank questionnaire is always displayed. One respondent may log in and complete any number of questionnaires.
CREATEUser may create an account. A log in page will be displayed to the respondent. If the user name that he enters is not already listed in the system, he will be prompted with another page that asks him to enter his full name and the password that he wants to use when accessing this questionnaire. He can use this user name and password to re-open and edit his responses again later.
EXISTUser must have an account. A log in page will be displayed to the respondent. He must enter a user name and password that has already been loaded into the system. He will not be given access to a questionnaire unless a correct user name and password are entered. You must supply this information in a spreadsheet that minimally lists each respondent's user name and email address.

Be careful using the anonymous option. Here, anyone may create any number of new questionnaire records. All of the new questionnaire records are assigned to the built-in "anonymous" account. Also, you can not follow up with people who haven't finished your questionnaire because you do not know who they are. Instead of running your survey anonymously, you may prefer to run it confidentially. That is, the respondents have accounts so you may control what questionnaire records they may access and you can follow up with those who have not completed questionnaires, but assure respondents that you will not release any information that would identify how an individual responded.

When letting a respondent create their own account, the respondent must supply an email address which has a valid domain name before the account is created. An email message will be automatically sent to the respondent if the account is created with their account information, including the user name and password the respondent entered if a FROM email address has been set in your questionnaire program. The respondent may use this account to log into the same questionnaire again later. He may log in as often as he wishes until his account expires.

AUTHENTICATION Options

OptionComment
NORMALThe respondent must enter a user name and password that matches user account information that was previously loaded into this system (or previously created by this user if users are allowed to create their own accounts).
LDAPThis may be used for intranet applications within your agency or company if your organization uses LDAP to maintain user accounts and passwords. QPL may be configured to use your organization's system to let a respondent used their real account to log into a questionnaire. Here, the respondent must (1) enter a user name that matches account information that was previously loaded into this system and (2) a user name and password that matches his organization's network user account. If respondents are allowed to create their own accounts, this option will automatically create an account for a respondent if the user name and password match a network account.

If the survey is not anonymous, you may specify how a respondent's identity is checked.

If the LDAP option is used with the ACCOUNT=CREATE command, then an account for a new user will only be created if the user enters a user name and password that can be authenticated against the organization LDAP server. The respondent's name and phone number will be copied from the LDAP server to the user account in your project. You can use the administrative user account pages on your web site to see who has logged in and created accounts.

If the LDAP option is used with the ACCOUNT=EXIST option, then the account must already exist in your project (with the respondent's actual network user name), but the project password must be blank. When the respondent logs in, the system will first check that he has an account for the project, and then check his user name and password with the LDAP server. If both checks are successful, he is allowed to log in. (Note: If a user's project password is not blank, then the system will use that to authenticate a respondent and skip the LDAP check. This way, you may mix both LDAP-based accounts and local project accounts in the same questionnaire project.)

EXPIREDATE

The EXPIREDATE command is used to set the default date that respondent accounts will expire. This is the date that will be used if you are letting respondents create their own accounts (with ACCOUNT=CREATE) or if you are creating an account for someone on the project web site. You may over-ride this default by specially setting a different expiration date for a respondent on his user account page on the web site or when loading accounts with an SQL script.

The EXPIREDATE also will prevent new accounts from being created on your project web site if this date has passed.

.EXPIREDATE = 2009-09-25

In this example, the default expiration date is set to midnight on September 25, 2009. The exact time used depends upon how your web server has been configured (i.e., whether it is set to use the local time where the server is located or GMT).

You may change the default expiration date after you have launched your project web site by updating the Default Project Settings page on the site.

Letting Respondents Access Multiple Questionnaires

After you have determined who may log into your project web site, your next step is step is to determine exactly what each respondent may access. Here too, there are a variety of options that you may use to tailor the system to your specific needs.

You may let a respondent...

Further, you may mix and match these scenarios within the same project. Since the QPL system separately maintains the list of users from the list of questionnaire results, it is perfectly ok to let some respondents access only one questionnaire but others access multiple questionnaires, or some have have pre-filled questionnaire records while others do not. Each questionnaire record will be automatically labeled with user name of the person it belongs to plus the group code that two or more uses may have used to update the record.

CASES Syntax

.CASES = ONE* | MANY | CREATE

Note: The asterisked (*) option shows the default setting that will be used if the command is not used in your program.

CASES Scenarios

CASES Options

OptionComment
ONERespondent may access only one questionnaire case. The respondent may only edit one questionnaire. This questionnaire will be displayed immediately after he logs in. If a questionnaire does not already exist, one will be created when he logs in.
MANYRespondent may access more than one questionnaire case. After the respondent logs in, a new page will be displayed that lists all his questionnaires. The respondent may only access cases that already exist. (If no cases exist, then one new case will be created when the respondent logs in.)
CREATERespondent may add new questionnaire cases. If a respondent has not created a questionnaire record yet, then a new one will be created the first time he logs in and that questionnaire will be opened. If the respondent has one or more questionnaire records, then a list of questionnaire records will be displayed on a new page and the respondent may pick one to edit. This list also will display a "New" option at the top of the list which will let him create a new questionnaire record.

Modifying the Case Selection Page

If a respondent is allowed to access more than one case, the respondent will see the case selection web page after logging in which will list the cases that he may open. When he clicks on the name of a case, the questionnaire for that case opens normally. When he exits from that questionnaire, the case selection web page is displayed again so he may pick another case. Or he may log out of your web site by clicking on the "Cancel" button.

Case selection page

If you have set up user accounts with group codes, the case selection page will show all the cases he shares with other people in the same group. It also will show who has cases currently checked out and when each case was last edited and by whom.

By default, the case selection page will just list all of the a respondent's questionnaires using the internal case identification number. You may use the commands below to instead use more meaningful information, such as the subject of that particular questionnaire. For example, if the questionnaire was about schools, you perhaps would want to list the names of a respondent's schools here.

SELECTCASE... Syntax

.SELECTCASEBY = question name 
.SELECTCASELABEL = "My Column label.." 
.SELECTCASEALT = "CONCAT(..."
.SELECTCASEFORMAT = LONG* | SHORT
.SELECTCASEREQUIRED = ON | OFF*

Note: The asterisked (*) options show the default setting that will be used if the command is not used in your program.

SELECTCASEBY

The SELECTCASEBY command is used to specify which question in your questionnaire can be used to uniquely identify the case for the respondent. Typically, you would set this to the name of a STRING question that holds a short text phrase. In the example shown above, this was set to a STRING question called SCHOOLNAME. If you do not specify a question, the internal case identification number will be displayed.

.SELECTCASEBY = SCHOOLNAME

.QUESTION = SCHOOLNAME, TYPE = STRING
What is the name of this school?
.ANSWER = 40
.NEXT

If you are only letting respondents open cases that you have pre-loaded, you should make this a hidden question. This way you can display the answer to the question to the respondent in the case selection page and within the text of other questions on your form, but the respondent cannot change the answer.

SELECTCASELABEL

The SELECTCASELABEL command lets you specify a label for the column heading. In the above example, it was set to "School Name." If you do not use this command, the name of the question will be used to label the column.

.SELECTCASELABEL = "School Name"

SELECTCASEALT

The SELECTCASEALT command lets you create a more complex case label using SQL syntax to create a label based on the values to one or more questions. Typically, you would use the SQL 'CONCAT' function to build a unique phrase, or one that has extra information such as the questionnaire completion status, by concatenating one or more question values together.

.SELECTCASEALT = "CONCAT(SCHOOLNAME, ' (', ELT(FINISH, 'Completed', 'Not Completed'), ')'"

In this example, the SELECTCASEALT command is set to an SQL phrase that will concatenate the name of the school, SCHOOLNAME, with the status of the case, FINISH. The SQL ELT function is used to convert the codes for the FINISH question (i.e., 1=Completed and 2=Not completed) to strings that can be combined with the string name. Parentheses are added just for visual clarity. If the record for Douglas MacArthur Elementary School was not completed, the link on the case selection page will be displayed as shown below.

Douglas MacArthur Elementary School (Not completed)

You can also use this technique to apply CSS styles, such as color-coding the case selection list according the FINISH question status. Here, you could put an HTML SPAN tag around the school name and then add a CLASS that applies the background color. Then add CSS styles in STYLE block in your program to define the colors.

.SELECTCASEALT = "CONCAT('<SPAN CLASS=finish', FINISH, '>', SCHOOLNAME,  '</SPAN>')"

.STYLE
SPAN.finish1 {background-color: green;}
SPAN.finish2 {background-color: red;}
.STYLE

.QUESTION = FINISH, TYPE = MULT
Have you finished this questionnaire?
.ANSWER
Completed
Not completed
.NEXT

In this example, two SPAN classes are created in the STYLE block: finish1 and finish2. The SQL CONCAT function will build the HTML needed when it reads the data record by concating the FINISH question value, either 1 or 2, with the word 'finish' to result in one of our class names (finish1 or finish2). So, using using the same data as above, the CONCAT function will build the following HTML snippet...

<SPAN CLASS=finish2>Douglas MacArthur Elementary School</SPAN>

which will then be displayed on the respondent's browser page as...

Douglas MacArthur Elementary School

The SELECTCASEALT argument must fit on one line in your program which limits what you may do to about 500 characters.

SELECTCASEFORMAT

The SELECTCASEFORMAT command may be used to display a less detailed version of the case selection page. This short version may be useful if your respondents are not sharing cases (and thus do not need to see who may have a case checked out) or if you are targeting your project to work well on an iPhone. By default, the LONG format shown above will be used. Setting it to SHORT will display the page as shown below.

SHORT case selection page

SELECTCASEREQUIRED

The SELECTCASEREQUIRED command may be used to force the case selection page to always be displayed. Normally, if a user has no cases or only one case, the questionnaire will be displayed immediately after he logs in. Setting this ON will cause the case selection page to be displayed even if only the "New" option listed (to create a new case).

Creating User Accounts in Your Program

As mentioned above, a respondent must have an account on your project web site before he may complete your questionnaire. You may use the ACCOUNT command to restrict access to only people for whom you have created accounts or let potential respondent create his own account.

There are several ways to create user accounts for your respondents, and you may use any of the methods or any combination of methods depending upon your needs. And these same methods may be used to create accounts for your project administrators. Administrative accounts let a user log into your project web site to monitor activity on the site, update user accounts, and export data from the site for analysis.

To create a user account, you may...

In practice, if you have many respondents, creating an SQL script is usually preferred since you can test it and make corrections until it works correctly. And you can use a variety of means to programatically convert a respondent list to an SQL script.

Creating accounts on the web site is usually just done when you need to create only a few accounts, or add accounts after you have launched your project.

Creating accounts in your questionnaire program with the USER block is usually limited to creating only accounts for your project administrators since you likely only have one or two people that need these accounts.

USER Syntax

.USER [= ON | username]
[.NAME = "My Name"]
[.PHONE = "123-123-1234"]
[.GROUP = "group code"]
[.PASSWORD = "password" | BLANK | RANDOM*]
[.STATUS = CLOSED* | NORMAL | SUPERUSER | MANAGER | ADMIN | DATAADMIN]
[.EMAIL = "name@domain.com"]
[.EXPIRE = yyyy-mm-dd]
	...
[Comments about the user go here.]
	...
	...
.USER [= OFF]

Notes: The square brackets indicate optional information and asterisks indicate the default option if a command is not used.

Only one account may be created with one USER block. And a user block must start and end with a USER command. Within this block, you may define various attributes for the account, such as the account holder's real name and phone number. You may put any number of USER blocks in your program to create all the accounts you need for your project.

.USER
.USER

This example shows the minimum information needed to create one account. Since no attributes are set, the account account will be created with default settings. This will create one Closed account where the user name is 'user1', the password is a random five-digit number.

More typically, however, you would also set at least some of the attributes to better describe the user and assign a particular type of account.

.USER = johnsona
.NAME = "Axel Johnson"
.PHONE = "202-512-0000"
.PASSWORD = "m5ryw5sh1ngt0n"
.STATUS = NORMAL
.EMAIL = "axel@mydomain.com"
.EXPIRE = 2009-09-25
This normal user account was created in the
questionnaire program file.
.USER = OFF

In this example, a Normal respondent account is created for Axel Johnson. His log in user name is "johnsona" and his password "m5ryw5sh1ngt0n." His phone number and a comment about how this account were created are also added, though this information is generally only used by an administrator when he looks up an account on the project web site (see below). The respondent's email is set and will be used if you use the email functions on the web site to send him a message. The account expiration date is also set to September 25, 2009. If Axel attempts to log in after this date, he will see an error message from the system that says that his account has expired and to contact the project administrator for assistance.

User account web page for Axel Johnson

STATUS Options

OptionComment
CLOSEDThe account exists but may not be used to log into the project web site.
NORMALRespondent user account.
SUPERUSERAn account the may be used to open any questionnaire and edit the responses.
MANAGERAn administrative account that only may be used to view project status information, including summary statistics, transaction logs, and reports that may have been created by the System Administrator.
ADMINAn administrative account used by the person who is administering the project. It includes Manager capabilities plus the ability to view and update user accounts.
DATAADMINAn administrative account used by the person who is supervising the project. It includes Manager and Administrator capabilities, plus the ability to export respondent data from the web site for more detailed analysis.

The STATUS command may not be used to create a System Administrator account. This account includes all the Data Administrator capabilities, plus the ability to change the project default settings, create reports, run maintenance routines, and send email messages from the site to respondents. At GAO, this account is reserved for the team who deploys and manages projects for the survey design staff.

Other Commands

Still need to flesh out this section...

Other Commands

Command Comment
.PRINTBUTTON [= ON* | OFF ] print button on the form. Is ON by default. - using command w/out argument toggles default Note: When this is used in a POPUP block, it affects the button on the popup page.
.ARCHIVEDATE = 2008-01-01 must enter ISO date with leading zeros if necessary. Not used for any live activity on the site. Just a place to keep track of when a site could be archived.
.AUTHOR = "friendly name"
.FROMNAME = "friendly name" friendly version of the the FROM address, used on public create account function AND email system
.FROM = "name@gao.gov" used on public create account function AND email system

Also updated the qpl_login and qpl_db_functions to use the new FROM address instead of the author name to send out messages to respondents who are having trouble logging in or have just created a new account. And added these as new fields to the Default Project Settings page. Need to test this auto-emailing stuff on buster to see if it works. AND need to pull out the boilerplate message text to the new ERTable[] array in qpl_project_local.inc so it can be easily changed.
.REPLYTO = "name@gao.gov" used in email system - - email address is copied from FROM if not used (syntax is not checked)
.RETURNPATH = "name@gao.gov" used in email system - - email address is copied from FROM if not used (syntax is not checked)
.LIVEUPDATE = ON* | OFF Add setting to control whether the real-time Ajax updates occur. If LIVEUPDATE is ON and the form is only a single page, then the Cancel button won't be displayed since it would be too late to abandon any changes the user made.

The real-time ajax updates occur when a form field losses focus (i.e., onBlur()). All QPL questions will update onBlur execept QUESTIONNAIRE (its fields are already updated when the page is loaded) and UPLOAD (which posts an uploaded file only when the Submit or Next page buttons are clicked.

If LIVEUPDATE is OFF, then the Summary Stats listing will likely not be up-to-date, since that can be viewed from any page, so one should not have LIVEUPDATE=OFF and SUMMARY=ON at the same time.
CARD The CARD command is used to set the maximum card image size when your data is exported from the MySQL database on your web server to a "flat file" that you can use to statistically analyze your results with SPSS or SAS. See CARD Command in the Short Answer Question page.
INCLUDE The INCLUDE command is used to insert portions of your program from one or more files. See the INCLUDE Command on the Changing Default Phrases page.