2009-08-28
QPL Reference Manual

There are a number of commands the let you modify the overall look of your QPL-generated web site. These include the color scheme, menu, and size of the web page.

Web Page Dimensions

By default, the web questionnaire page will be 770 pixels wide, including a menu bar on the left side of the page. The chart below shows what commands can be used to modify various aspects of the page dimensions.

Page layout measurments

Default Project Settings

The chart below shows that the various default width settings and page measurements.

Default width settings

PAGEWIDTH and PAGEGUTTER Syntax

.PAGEWIDTH = #      (320 to 1660 pixels)
.PAGEGUTTER = #     (10 to 70 pixels)

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.

Both of these commands measure the page in pixels (one inch is 72 pixels).

PAGEWIDTH

The PAGEWIDTH command sets the total width of the browser page that will be used for your questionnaire form. Your questionnaire form will always be rendered with this width regardless of how the respondent may resize their browser window. By default, it is set to 770 pixels so that it will fit nicely on a browser a respondent who's computer monitor is set to 800 by 600 pixels. (It is less than 800 to allow the browser some room to display its window edges and a scroll bar button.) This size also works well should a respondent choose to print the page vertically on 8.5 by 11 inch paper.

The PAGEWIDTH and PAGEGUTTER commands may only be used once in your questionnaire program and must be used before any questions are programmed. These settings will be used to determine the maximum allowable limit on the widths of the following questions.

PAGEGUTTER

The PAGEGUTTER command sets the size of the column that is used to hold the question number. The question numbers will be right-aligned in this space at the top of the question text.

Color Scheme for Web Pages

The web pages that QPL generates will use various background colors to make it easy for respondent to recognize the various parts of the page, such as the menu area and individual rows in a question. By default, various shades of grey are used. You may pick a custom color scheme that is based on the web page background color you select. All of the colors used on the web page will be derived from this color. Various shades of the same color as well as harmonious colors are automatically applied to all of the colored elements on the page.

Sample color scheme

In this example, the base color scheme chosen was a medium green which shows on the web page as the background under the menu. All of the other colors on the page are derived automatically from this color. Question text, however, is always black.

COLORSCHEME Syntax

.COLORSCHEME = name | hex [ = offset ]  (offset: 1 to 5, default is 2)

Note: The lower-case words show what type of argument is used and the square brackets show optional information.

You may set the base color using one of the standard HTML color names, such as ForestGreen, or by using the hexidecimal color number (which is #228B22 for ForestGreen). You must include the pound sign at the start of the hexidecimal number. The Palette button (Homesite Palette Button) in HomeSite can be used to select a color and insert the hexidecimal number into your QPL program. Other graphics programs have similar tools to pick colors and get the name or number needed here.

You may select a base color of any hue, but you should select medium values for the saturation and luminosity (lightness) so that you will see some noticiable variation when QPL creates various shades of the same color. Generally, saturation and luminosty values of 128 (#7f) work well.

You may also change the default harmonious color scheme by also setting the offset value. An harmonious color is chosen by selecting the color that is an even multiple of 60 degrees away from your base color when viewed on a color wheel.

By default, the COLORSCHEME offset multiple is set to 2, so it will pick the harmonious color that is 120 degrees away from your base color. So, in the above example, a green color is chosen, the harmonious color will be blue.

.COLORSCHEME = #7b9b5a = 5

In this example, the same green base color is used, but the offset is changed from 2 to 5. The effect will be that menu is shown with the same color but the questionnaire part of the page uses a red color that is 300 degrees away on the color wheel.

The harmonious color offset can be useful if you have a family of related questionnaires. You can unify the look by starting with the same base color, but make each one look special by using different offsets.

Changing the Color of Individual Elements

While using the COLORSCHEME command makes it easy to set all of the colored elements on your web page, you may over-ride its settings of individual elements if you need to.

.BACKGROUND = element = name | hex | TRANSPARENT

Note: The lower-case words show what type of argument is used and the square brackets show optional information.

To change the color of an element, you must use the the BACKGROUND command with the name of the element, and the new color for the element (using the HTML name or the hexidecimal color value). If you do not want to use background color for an element, you may set the color to TRANSPARENT. In this case, the color that is beneath an element will be displayed.

BACKGROUND Elements

ElementDescription
BODYMain background color.
FORMQuestionnaire form background.
ROWHEADERColor used in MATRIX or COLUMNS heading row.
ROWColor used in MATRIX or COLUMNS rows row shading is off.
ROW1First color used in MATRIX or COLUMNS rows row shading is on.
ROW2Second color used in MATRIX or COLUMNS rows row shading is on.
ROWDKMATRIX color used in the right-most or Don't Know columns.
MENUROWColor used to highlight headings by pages on the menu.
MENUROWONColor used to highlight the current page on the menu.
HRColor of the horizontal rule used to mark page breaks in the local HTML version of your form.
BUGColor of the text used to display the QPL credit at the bottom of the questionnaire form.
NAVBBMenu navigation button outline color.
HOVERColor of questionnare hypertext link when mouse cursor hovers over it.
HOVERMAINColor of other hypertext
HOVERMENUColor of hypertext link used in the menu when mouse cursor hovers over it.
HOVERMENUNAVBBColor of menu navigation button when mouse cursor hovers over it.
POPUPBackground color of popup box.
POPUPBANNERColor of banner used at the top of a popup box.

The BACKGROUND command must be used after the COLORSCHEME command in order to over-ride its setting of one of these elements.

.COLORSCHEME = #7b9b5a = 5
.BACKGROUND = ROWHEADER = RED

In this example, the same green background is used with the COLORSCHEME command, but the heading row for questions in a MATRIX is changed to red (from the reddish color that COLORSCHEME would have selected).

Special color for MATRIX header

Modifying the Menu

The menu bar is used to let the respondent easily navigate around through your questionnaire pages, get a summary of all of his responses, find the contact person for the questionnaire if he has questions, and get feedback on how much progress he has made working through your questions. It lets the respondent view and review any page as often as he desires, just like he could if completing the same questionnaire on paper.

Menu

Menu

The Menu section of the menu lets the respondent view a list of all subtitles used all of your questionnaire pages by clicking on the "Display list of headings." phrase. The respondent may click on a heading in the list to open that page of your questionnaire. He can close the list by clicking on "Display list of headings." again.

Menu with headings displayed

The headings shown in this list are automatically created when you use the SUBTITLE and NEWPAGE commands to create headings and break pages in your questionnaire program.

MENU Syntax

.MENU [= ON* | OFF ]

The MENU command controls the display of the entire menu bar. It is ON by default. You may remove it by setting the MENU command to OFF.

.MENU = OFF

Removing the menu also increases the space on the web page for your questions.

Summary

The respondent may click on the "View and print a summary of your responses." link to create a report that lists all the questions in your questionnaire and his current answers. This report opens in a separate browser window and the respondent may choose to print the page he he desires. You may use various converter options when building your web site to modify the contents of the summary report.

SUMMARY Syntax

.SUMMARY [= ON* | OFF ]

The SUMMARY command controls the display Summary section in the menu bar. It is ON by default. You may remove it by setting the SUMMARY command to OFF.

Help

In this section you can put your contact information. Since the menu is always displayed with all of your questionnaire pages, this information is always available to the respondent if he needs help.

HELP Syntax

.HELP [= ON]
	Your help text goes here...
.HELP [= OFF]

You put your helpful information inside a HELP block. Like question text, you must escape special HTML characters and you may use QPL text format shortcut characters.

The Help section of the menu is always displayed if the Menu is displayed.

.HELP
If you have questions, please contact either:

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

\<a href\=\"mailto:Torres\&gao.gov\"\>Rosa Torres\</a\> at 312-220-0001.
.HELP

This shows how the above example was programmed.

This help information may also be changed after your project is deployed on a web server. The administrative page, Default Project Settings, will show your current help note and let you change it. The change will immediately be used on all your respondents web pages. This is convenient if your support information changes during the course of your survey.

The menu bar is included when you build your project by default. There are number of commands that you may use to modify what components are included in the menu bar and whether to include the menu at all. If you are building a short one-page questionnaire, then you would likely not need the navigation tools in the menu so then you would turn it off.

Progress

The progress bar is displayed on the menu if your questionnaire has more than one page. The progress bar grows from left to right as the respondent moves page-by-page through the questionnaire.

PROGRESS Syntax

.PROGRESS [= ON* | OFF ]

The PROGRESS command controls the display of the Progress section in the menu bar. It is ON by default. You may remove it by setting the PROGRESS command to OFF.

Navigation

The navigation buttons at the bottom of the menu let the respondent page forwards or backwards through the questionnaire one page at-a-time, or jump to the first or last page, or exit (log out) of the quesitonnaire. If your questionnaire only has one page, then only a "Submit" navigation button will be displayed.

NAVIGATION Syntax

.NAVIGATION [= ON* | OFF ]

The NAVIGATION command controls the display of the Navigation section in the menu bar. It is ON by default. You may remove it by setting the NAVIGATION command to OFF.

Menu Labels

In addition to being able to control whether various parts of the menu are displayed, you may also change the default labels that are used.

Menu Label Codes

CodeDefault Label
16Menu
31Display list of headings.
26Summary
27View and print a summary of your responses.
28Help
30Progress
32Navigate
33First section
34Previous section
209Exit
35Next section
36Last section
210Submit

Default Label Syntax

.# = "new label"

You may change a default label by setting its label code to a new label.

.31 = "Show Table of Contents."

In this example, the label for the link that toggles the display of the heading links, "Display list of headings.," is changed to "Show Table of Contents."

Changing default menu label

See Default Phrase Options for a complete list of all the phrases and labels that you can change.

Changing the Questionnaire Buttons

The navigation buttons used at the bottom of your questionnaire page are always displayed and let the respondent navigate forwards and backwards through your questionnaire, and log out of your questionnaire. Exactly what buttons are displayed depends on whether your questionnaire has only one page or multiple pages.

If you only have one page, then only the Submit button is displayed which, when clicked by the respondent, first saves all the answers he entered and then logs out.

If you have multiple pages, then the Next and Previous buttons are displayed. Here, the respondents answers are first saved before the next or previous page is retrieved. The Submit button is renamed as Exit since it saves the respondent's answers and logs him out of the quesitonnaire.

The Print button is optional and is displayed by default.

PRINTBUTTON Syntax

.PRINTBUTTON [= ON | OFF ]

Setting the PRINTBUTTON to OFF will omit the Print button on all of the pages in your questionnaire.

You may change the labels used on the buttons using the default label syntax.

Default Label Syntax

.# = "new label"

You may change a default label by setting its label code to a new label.

.202 = "< Go back"

In this example, the label for the link that toggles the display of the heading links, "< Previous page," is changed to "< Go back."

Code Phrase Can
use
escaped
HTML?
Comment
202< Previous section No Label used on questionnaire page button to move to the previous page.
102P No Access key for Previous section button. (On Windows' browsers, holding the Alt key down and pressing this key performs the same action as using the mouse to click on the button. On Mac browsers, the control key is used instead of the Alt key.)
203Next section > No Label used on questionnaire page button to move to the next page.
103N No Access key for Next section button.
204Print No Label used on questionnaire page button to move to print the current page.
104T No Access key for the Print button.
209Exit No Label used on questionnaire page button to move to properly log out of a multiple-page questionnaire.
109E No Access key for the Exit button.
210Submit No Label used on questionnaire page button to move to properly log out of a single-page questionnaire.
210S No Access key for the Submit button.
211Cancel No Label used on questionnaire page button to move to properly log out of a single-page questionnaire without updating you web server data base.
111C No Access key for the Cancel button.

See Default Phrase Options for a complete list of all the phrases and labels that you can change.