2009-09-23
QPL Reference Manual

In addition to just writing text for your questions, there are a lot of other things you can do to make presentation presentation effective, including tailoring it to a specific user.

Using Reserved HTML Characters

The characters, ", #, &, =, <, >, %, $, and @ have special meaning in HTML files. The QPL compiler will automatically convert these characters to codes, called "HTML entities," when used in question answer or text lines so that they will be displayed as intended and not used as HTML codes. All extended characters are also changed to HTML entities.

These codes begin with an ampersand (&) and end with a semi-colon. In between, either a number or a name is used to identify the character.

Characters Automatically Converted to HTML Entities

Character Entity Code Comment
" &quot; Quotation marks
# &#35; Pound sign
& &amp; Ampersand
< &lt; Less than
> &gt; Greater than
% &#37; Percent
$ &#36; Dollar sign
@ &#64; At sign

Extended ANSI characters (codes 127-255) are also converted to HTML entities. For example, "Ĭ" will be converted to the entity "&#300;."

For example, if you programmed

What is your <B>favorite</B> color?

the compiler will code this phrase into HTML as

What is your &lt;B&gt;favorite&lt;/B&gt; color?

and your browser will display it as

What is your <B>favorite</B> color?

In order to prevent the compiler from converting special HTML characters to entities (and thus pass through your HTML codes), you must "escape" each special character with a back slash (\). The back slash tells the compiler to not change the next character.

Continuing the previous example, to bold the word "favorite," you should write

What is your \<B\>favorite\</B\> color?

Then compiler will code this phrase into HTML as

What is your <B>favorite</B> color?

and your browser will display it as

What is your favorite color?

To create an HTML link that will launch the the respondent's email program when clicked, you would use...

If you need help send a message to 
\<a href\=\"mailto:myaddress\@mywebsite.com?subject\=Help\"\>me\</a\>.

This link will start the respondent's email program with the To: address set to "myaddress@mywebsite.com," and the Subject: line set to "Help" (Note: Not all email readers will use the subject line setting.)

If you are using QPL that has been installed inside the HomeSite HTML text editor, you may use the "Escape special HTML characters" button () to escape all of these characters in your current selection.

Format Shortcuts

Several keyboard characters have been specially defined in QPL to a short-cut way of entering several common HTML tags:

Shortcut Escaped HTML equivalent Result on web page
+bold+ \<B\>bold\</B\> bold
_underline_ \<U\>underline\</U> underline
~italic~ \<I\>italic\</I\> italic
`strong` \<STRONG\>strong\</STRONG\> strong
| \<BR\> Line break
= \&bull; Bullet character (•)

As you can see, using the shortcuts makes your text much easier to read in your program. You may also use combinations of these shortcuts to, for example apply bold and italic formatting to the same word. You should take care, however, to use these codes from the inside-out.

Every +~good~+ boy deserves favor.

This will generate properly formed HTML which you can expect to work in all browsers.

Every good boy deserves favor.

You can use the bullet shortcut (=) and the line break shortcut (|) to make a bulleted list.

= Red |
= Blue |
= Green

This will be displayed as

• Red
• Green
• Blue

You may escape one of these special QPL format characters with a backslash to use it as a normal character.

5 \+ 5 \= 10

This will be displayed as

5 + 5 = 10

Global Bolding

In addition to being able to bold words in the text of your question using the "+" shortcut, you may also use the BOLD command to bold all of the text of one question or all of the questions in your questionnaire.

BOLD Syntax

.BOLD [=ON | OFF*]

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

BOLD is set to OFF by default, so the text of your questions will be displayed normally when viewed by the respondent.

If you use this command inside a QUESTION block, then only the text of that question will be set to bold. If you use it outside a QUESTION block, then all of the following questions will use that new default setting (or until another BOLD command is used outside of a question block).

.BOLD = ON

.QUESTION = Q1, TYPE = STRING
This will be bold text.
.ANSWER = 10
.NEXT

.QUESTION = Q2, TYPE = STRING
.BOLD = OFF
This will be normal text.
.ANSWER = 10
.NEXT

.QUESTION = Q3, TYPE = STRING
This will be bold text.
.ANSWER = 10
.NEXT

.BOLD = OFF

.QUESTION = Q4, TYPE = STRING
This will be normal text.
.ANSWER = 10
.NEXT

In this example, BOLD commands are used to change the default setting and to change individual questions.

This will be bold text.

This will be normal text.

This will be bold text.

This will be normal text.

In this example, the BOLD command is used before any questions to change the default to ON.

A BOLD command is used inside question Q2 to turn it off in only that question, so question Q3 will still be bold.

Then another BOLD command is used outside of a QUESTION to change the default so now question Q4 will be normal.

The BOLD setting is not copied with other questionn attributes when using the ANSWER=question command.

If no option is used, then BOLD will be set to OFF.

Aligning Text

By default, your question text will be left-justified when the respondent views your questionnaire page. You may use the ALIGN command to also center or right-justify your question text.

ALIGN Syntax

.ALIGN [= LEFT* | CENTER | RIGHT]

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

If you use the ALIGN command inside a QUESTION/NEXT block, then only the alignment of that question text is affected.

If you use it outside a QUESTION/NEXT block, then default alignment is changed for all of the following questions or until you use another ALIGN command to change the setting again.

.QUESTION = Q1, TYPE = STRING
.ALIGN = RIGHT
The text of this question will be right-justified.
.ANSWER = 10
.NEXT

Here, the ALIGN command was used inside a QUESTION, so only the text of this question will be right-justified.

The text of this question will be right-justified.

Next, we'll use it outside of a question change the default alignment for the following questions.

.ALIGN = RIGHT

.QUESTION = Q1, TYPE = STRING
The text of this question will be right-justified.
.ANSWER = 10
.NEXT

.QUESTION = Q2, TYPE = STRING
.ALIGN = CENTER
The text of this question will be centered.
.ANSWER = 10
.NEXT

.QUESTION = Q3, TYPE = STRING
The text of this question will be right-justified.
.ANSWER = 10
.NEXT

.ALIGN = LEFT

.QUESTION = Q4, TYPE = STRING
The text of this question will be left-justified.
.ANSWER = 10
.NEXT

Here, the default alignment is set to RIGHT since the ALIGN command was before any questions. Thus, question Q1 will be right-aligned.

Question Q2 will be centered since an ALIGN command was used inside this QUESTION block, but question Q3 will still be right-aligned since this does not change the default.

After question Q3, the default alignment is changed again to LEFT, so question Q4 (and later questions will all be left-justified.

The text of this question will be right-justified.
The text of this question will be centered.
The text of this question will be right-justified.
The text of this question will be left-justified.

The ALIGN setting is not copied with other questionn attributes when using the ANSWER=quesiton command.

If no option is used, then ALIGN will be set to LEFT.

Heading and Question Text Font and Size

Debate continues on the most readable style of text font between serif and sans serif fonts. By default, the questionnaire web form QPL creates uses a serif font for the question text and a sans serif font for the headings.

Donec feugiat ligula ut tellus scelerisque volutpat. (SERIF)

Donec feugiat ligula ut tellus scelerisque volutpat. (SANSSERIF)

Donec feugiat ligula ut tellus scelerisque volutpat. (MONOSPACE)

The font family may be set separately for the question text (and related instructions such as skip instructions) and for the headings.

FONT and HFONT Syntax

.FONT = SERIF* | SANSSERIF | MONOSPACE [= XXS | XS | S | M* | L | XL | XXL | SMLR | LRGR ]
.HFONT = SERIF | SANSSERIF* | MONOSPACE [= XXS | XS | S | M* | L | XL | XXL | SMLR | LRGR ]

The FONT command is used to set the font family for the question text. By default, it is set to use a serif font, which will map to Times New Roman on most Windows computers. If that font is not available, the respondent's browser will automatically select a similar serif font.

The HFONT command is used to set the font family for the TITLE and SUBTITLE headings. By default, it is set to use a sansserif font, which will map to Arial on most Windows computers. If that font is not available, the respondent's browser will automatically select a similar sansserif font.

You may also modify the relative size of font using the size options. The default relative size is M (medium). Going up or down a size increases or decreases the relative size of the displayed font by 15%. The SMLR (smaller) option reduces the size by 20% and the LRGR (larger) option increases it by 20%.

.FONT = SERIF = XS
Donec feugiat ligula ut tellus scelerisque volutpat.

.FONT = SERIF = S
Donec feugiat ligula ut tellus scelerisque volutpat.

.FONT = SERIF = M
Donec feugiat ligula ut tellus scelerisque volutpat.

.FONT = SERIF = L
Donec feugiat ligula ut tellus scelerisque volutpat.

.FONT = SERIF = XL
Donec feugiat ligula ut tellus scelerisque volutpat.

The FONT and HFONT commands may only be used once in your program and define the font settings for the web site home page and questionnaire form.

References to Other Answers

Question text lines can be programmed to display the current answers from other questions. For example, if your first question asked for a respondent's name, a subsequent question can display his or her name in the text of the question.

Q: What is your name?
A: John
Q: Hello John, ...

References to the current answers to questions are made by using the variable name of a question, delimited by brackets, in the text of a question. The web server version of your questionnaire will automatically replace the variable name will be replaced with the respondent's current answer when it builds a page for a respondent. (Since the local test version is not supported by a database, it will just display "______.")

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

.NEWPAGE

.QUESTION = HELLO, TYPE = question type
Hello [NAME], ...
.ANSWER
   ...
   ...
   ...
.NEXT

In the second question, "[NAME]," will be replaced with whatever has been typed in for an answer to the NAME question. You can refer to the answer of any type of question, and you can refer to more than one answer in a single question.

You cannot, however, put a reference to the answer of another question in an answer text line.

No spaces can be included between the brackets and the variable name, and brackets cannot be used for anything else in the question text.

A question that contains a reference to the answer of another question should not be put on the same page as the other question. In this example, the value of [NAME] will be whatever was in the data base when the page was created on the web server and sent to the respondent's browser. So, if the question HELLO is on the same page as NAME, the text used in HELLO's question will not be updated until this page is submitted and reopened. Here, the NEWPAGE command was used to tell the QPL compiler to start the HELLO question on the next page, which will be sent to the user's browser after the answer to NAME was stored in the database.

Typically, however, this is not a problem. Generally, you will have pre-loaded data into hidden questions and then use this capability to display the contents of that question. Or, you will have asked a question on one page and then display the data on another page. Since moving from one page to another causes the data base on the server to be updated with new information, the updated response during the session will be available to a question on another page.

Pop-Up Text Boxes

You can provide a respondent a way to see additional information about a question, such as definitions of terms or other explanations, by inserting a link to a small browser window with this information. First you must use the POPUP command in your program to create the content of the small browser window and then refer to this window in the text of a question.

POPUP Syntax

.POPUP [= ON | name]
[.TITLE = "Popup title" ]
[.CLOSEBUTTON [= ON* | OFF] ]
[.PRINTBUTTON [= ON* | OFF] ]
[.WIDTH [= #] ]
[.HEIGHT[= #] ]
	 Content of pop-up window goes here..
	 ...
.POPUP [= OFF]

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

The POPUP command must be used to start and end the creation of one pop-up box. You may use the ON and OFF options to make it clearer in your program where it starts and ends. You may also use the starting POPUP command to give the pop-up box a name. The name must start with a letter and may be up to 16 characters long. You will use this name later when creating a link in the text of a question to this pop-up box. If you do not use a name, the pop-up will be automatically named POPUP1, POPUP2, etc.

To insert a link to this pop-up within the text of question, you must enter the name of the pop-up delimited by caret (^) characters.

See my ^POPUP1^ information.

There are several additional commands that you may use to modify the appearance of the pop-up box: TITLE, CLOSEBUTTON, PRINTBUTTON, WIDTH, and HEIGHT. These commands must be used inside the POPUP block. The settings for the CLOSEBUTTON, PRINTBUTTON, WIDTH, and HEIGHT options will be automatically copied to following POPUP blocks. That is, you just need to set the options you prefer in the first POPUP block. Your settings will be used in all later POPUP blocks, unless you use one of these options to change it again.

You should create a TITLE for the pop-up. This title is used to label then link that is inserted into your question text. If you do not use a TITLE, the name of the question will be displayed in the link. (Note: The TITLE of your project will be used to name the title of the project window.

By default, the pop-up window will include buttons to close the window and print the window contents. You may use the CLOSEBUTTON and PRINTBUTTON commands to omit them.

The pop-up window will be set to be 300 pixels wide and and 300 pixels high. You may use the WIDTH and HEIGHT commands to change the size. If you use one of these commands without a size number, the default setting of 300 pixels will be used.

.TITLE ="Sample Project"

.POPUP = MYBACKGROUND
.TITLE = "background information"
.HEIGHT = 200
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. Question Q1 will be displayed to the respondent as...

Welcome to our survey.

If you would like more information about our survey please see the background information.

If you click on the link above to "background information," you will see the pop-box that was created. The title used on the pop-up window title is "Sample Project," which is the title of the project.

The links to the pop-up windows will work in the local HTML preview of your web site. This lets you view and test the links and the content before installing your project on a web server.

SQL Query Result

Embedding the results of an SQL query is an advanced feature requiring knowledge of SQL programming and how this or other databases on your web server are structured. But, if you have this knowledge, you can easily harvest any information that is in any of the databases you may access and present individualized information to a respondent.

You will need to install your project on a web server before you can test your queries with your questionnaire. Typically, you will develop your queries separately with your database (perhaps using the MySQL command line on the server) and then paste the tested queries into your QPL program. The QPL compiler does not check the syntax of your SQL query. When you view the local HTML version of your questionnaire, the location where you are inserting your SQL query will be shown as "_____."

QUERY Syntax

.QUERY [= ON | name]
[.FORMAT [=] SOQ [=] "formatting before query output" ]
[.FORMAT [=] SOL [=] "formatting at start of output record" ]
[.FORMAT [=] EOL [=] "formatting at end of record" ]
[.FORMAT [=] EOQ [=] "formatting after end of query output" ]
[.FORMAT [=] NONE [=] "label to display if query returned no results"]
[.HTMLSPECIALCHARS = ON* | OFF ]

SELECT [something AS 'SOL',] something AS 'LABEL' [, something AS 'EOL'] FROM mytable WHERE criteria;

.QUERY [= OFF]

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

The QUERY command must be used to start and end the creation of one query. You may use the ON and OFF options to make it clearer in your program where it starts and ends. You may also use the starting QUERY command to give the query a name. The name must start with a letter and may be up to 16 characters long. You will use this name later when inserting the results of this query in the text of a question. If you do not use a name, the query will be automatically named QUERY1, QUERY2, etc.

To insert the results of a query into the text of the question, enter the name of the query delimited by curly braces ({}) where you want the results to appear.

Currently, {QUERY1} people have accounts on this websurvey.

The SQL query statement must start with "SELECT."

The results you wish to display in the question text must aliased to the "LABEL" column. You may use the CONCAT() and other SQL functions to combine or reformat the data in your database tables. You may also include a sub-SELECT if supported by your version of MySQL.

The "SOL" (start-of-line) and "EOL" (end-of-line) columns are used to wrap out put rows with HTML format tags and are not required.

You may use only these column name aliases and they must use uppercase letters. Any additional columns generated by the query will be ignored.

The simplist query will return only one row which you can embed, perhaps, in the middle of a sentance.

.QUERY
SELECT COUNT(*) as 'LABEL' FROM user WHERE q_user_status=1;
.QUERY

.QUESTION = Q1, TYPE = VOID
Currently, {QUERY1} people have accounts on this web survey.
.ANSWER
.NEXT

In this example, the query counts the number of Normal user accounts (q_user_status=1 in table 'user') on this project, and returns the total. Since the query was not explicitly named, the automatically-generated name, QUERY1, was used to insert the query results into question Q1. If this query returned 100 users, question Q1 will be displayed to a respondent as...

Currently, 100 people have accounts on this web survey.

If you expect that your query will return more than one row, the simplist way to make a list is to wrap the SQL output within <PRE></PRE> tags.

.QUERY = ON
SELECT q_uname AS 'LABEL' 
FROM data 
WHERE finish=1
ORDER BY q_uname;
.QUERY = OFF

.QUESTION = Q1, TYPE = VOID
The following people have finished this survey:

\<PRE\>{QUERY1}\</PRE\>
.ANSWER
.NEXT

In this example, the query will list all the users by user name that have finished the questionnaire (finish = 1 in data table). Since no FORMAT EOL or SQL EOL has been used, a carriage return (\n) will be added automatically to the end of the line which will create a line break if put within <PRE></PRE> tags.

The following people have finished this survey:

able
baker
charlie

You can jazz up the output further using more HTML tags by using the FORMAT options.

.QUERY = MYCOMPLETED
.FORMAT = SOQ = "<OL TYPE=1>"
.FORMAT = SOL = "<LI>"
.FORMAT = EOL = "</LI>"
.FORMAT = EOQ = "</OL>"
.HTMLSPECIALCHARS = OFF
SELECT q_uname AS 'LABEL' 
FROM data 
WHERE finish=1
ORDER BY q_uname;
.QUERY = OFF

.QUESTION = Q1, TYPE = VOID
The following people have finished this survey:

{MYCOMPLETED}
.ANSWER
.NEXT

Here the FORMAT commands are used to put the results of the query into an numbered list, starting with number 1.

The HTMLSPECIALCHARS must be used to prevent special HTML characters from being converted into entities. This command defaults to on.

The following people have finished this survey:

1. able
2. baker
3. charlie

And through clever uses of the SQL CONCAT() function, you could even create a table with any number of columns.

.QUERY = ON
.FORMAT = SOQ = "<TABLE>"
.FORMAT = SOL = "<TR><TD>"
.FORMAT = EOL = "</TD></TR>"
.FORMAT = EOQ = "</TABLE>"
SELECT CONCAT(q_id, '</TD><TD>', q_uname) AS 'LABEL' 
FROM data 
WHERE finish=1
ORDER BY q_uname;
.QUERY = OFF

.QUESTION = Q1, TYPE = VOID
The following people have finished this survey:

{QUERY1}
.ANSWER
.NEXT

Here the FORMAT tags are used to put the results of the query into a table and the CONCAT() function is used to merge two columns, putting the ending </TD> and starting <TD> tags between the columns. The query lists the QPL internal case id number (q_id) and the respondent's user name (q_uname) for cases that are finished (finish = 1, where finish is the name a question that you programmed the questionnaire.)

The following people have finished this survey:
3able
1baker
5charlie

You also may write queries that are specific to the current respondent or the current respondent's questionnaire record (one respondent can have more than one record) by using the internal $q_uname variable to get the respondent's name or the $q_id variable to get the internal case id.

.QUERY = ON
SELECT q_uname AS 'LABEL' 
FROM data 
WHERE q_uname='$q_uname';
.QUERY = OFF

.QUERY = ON
SELECT q_id AS 'LABEL' 
FROM data 
WHERE q_id=$q_id;
.QUERY = OFF

.QUESTION = Q1, TYPE = VOID
Your user name is: {QUERY1}

Your case id is: {QUERY2}
.ANSWER
.NEXT

The $q_uname must be used inside quotes in the query. When this web page is being built for a particular respondent, this will be replaced with the respondent's user name which is a string, and then the query will be run on the database with that string. The $q_id does not need to be put in quotes since it is a number.

If the current user is test1 and their internal case id number is 1, then question Q1 will display...

Your user name is: test1

Your case id is: 1

when the respondent views this page.

You can build upon this last example it to do more useful things. If, for example, you gave your respondents user names that are the same as you have in another database, you could use it to write queries that get respondent-specific information from the other database.

.QUERY = GETPHONE
SELECT phone AS 'LABEL' 
FROM gaolocator.data
WHERE username = '$q_uname';
.QUERY

.QUESTION = Q1, TYPE = VOID
Your phone number is: {GETPHONE}
.ANSWER
.NEXT

Here, the respondent's user name for this questionnaire, $q_uname, is also used in the 'username' field of the 'data' table in my 'gaolocator' database. So then it is simple query to look up this respondent's gaolocator record and get the respondent's phone number.

Your phone number is: 202-512-0000

Cascading Style Sheet Formatting

The QPL system uses CSS to format almost all of the HTML objects a respondent sees on the web page. If you create new HTML object, such as a list generated by inserting an SQL statement, you can separately put the styling information into your QPL program using the STYLE command and link it to that list using an HTML element ID or style CLASS. Styles added in your program will be applied after the standard QPL stylesheet and so also can be used to override standard QPL styles. You can view the effect of your new styles on the local HTML version of your questionnaire.

STYLE Syntax

.STYLE [= ON]
Your CSS statements go here...
.STYLE [= OFF]

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

You must put all of your CSS style statements inside a STYLE block. The QPL compiler will add your styles to the standard style sheet. It will not, however, perform any syntax checking of your CSS statements.

You may use the ON and OFF options to make it clearer in your program where your STYLE block starts and stops.

If you create your own HTML elements you should also assign an ID or CLASS to that element so that your definition only affects that particular HTML element and not all of those elements on the web page. So, for example, if you wanted to change the color of the type and font size of a word in a question, you would create a style for a SPAN tag and then use the SPAN tag in your question text. (Note: The SPAN tag is a generic in-line HTML element that has no inherent styling, which is commonly used to change objects like text that are used inside of another HTML element like a paragraph or table cell.)

.STYLE = ON
SPAN.lookhere {
	color: red;
	font-size: large;
}
.STYLE = OFF

.QUESTION = Q1, TYPE = STRING
What is your \<SPAN CLASS\=\"lookhere\"\>name\</SPAN\>?
.ANSWER = 1O
.NEXT

Here, a CLASS is defined for the SPAN tag called "lookhere" inside a STYLE block. Then the SPAN tag is used in question Q1 with the class "lookhere." This will be displayed to the respondent as...

What is your name?

Similarly, you can use the generic DIV block HTML element to put some of the text in your question into a box in order to highlight information to your respondent.

.STYLE
DIV.shout {
	background-color: lightyellow;
	border: 2px solid orange;
	padding: 4px;
	margin: 5px 0px 5px 0px;
}
.STYLE

.QUESTION = Q1, TYPE = VOID
Welcome to our survey on these issues.

\<DIV CLASS\=\"shout\"\>
This survey is being conducted 
as part of our effort to study these
issues. We will report your responses
to Congress.
\</DIV\>
.ANSWER
.NEXT

In this example, a CLASS called "shout" was created in a STYLE block that creates a light yellow box with an orange border. Then the DIV was applied to the second paragraph in question Q1. This will be displayed to the respondent as...

Welcome to our survey on these issues.

This survey is being conducted as part of our effort to study these issues. We will report your responses to Congress.

JavaScript Automation

The QPL web questionnaire pages depend heavily on JavaScript for many things, such as modifying the default behavior of <INPUT> elements, for example, to only allow the respondent to type numbers into a field that was created as NUMBER type of question.

You can further extend this automation by adding your own JavaScript functions and tie them to QPL-generated <INPUT> elements and elements you add (though you should not create your own <INPUT> elements, those would cause problems with QPL JavaScript functions).

SCRIPT Syntax

.SCRIPT [= ON]

function MyFunc()
{
...
}

function...

.SCRIPT [= OFF]

Your JavaScript functions must be written inside a SCRIPT block. You may use the ON and OFF options to make it clear in your program where the block starts and stops. You may include any number of JavaScript functions inside the block. The QPL compiler does not check the syntax of your JavaScript functions. It will just add them to the end of its library of JavaScript functions when it builds your web site files.

Since JavaScript runs inside your browser, you can test and debug your JavaScript functions with the local HTML version of your project.

Writing JavaScript, like SQL, is an advanced feature which, like SQL, can be easily added to your QPL program if you are familiar with JavaScript programming. This programming is beyond the scope of this manual, but the example below is typical of the sorts of things people like to do: adding up numbers.

.QUESTION = Q21, TYPE = NUMBER = "##"
Please enter a number.
.ANSWER
.NEXT

.QUESTION = Q22, TYPE = NUMBER = "##"
Please enter a number.
.ANSWER
.NEXT

.QUESTION = Q23, TYPE = NUMBER = "##"
Please enter a number.
.ANSWER
.NEXT

.QUESTION = Q24, TYPE = VOID
\<A HREF\=\"javascript:AddUpQ21toQ23();\"\>Click here for total\</A\>: 
\<SPAN ID\=\"Q24TOTAL\"\>0\</SPAN\>
.ANSWER
.NEXT

.SCRIPT = ON
function AddUpQ21toQ23()
{
	var Total = 0;
	
	with(document.QPL)
	{
		if (!isNaN(parseInt(Q21.value)))
			Total += parseInt(Q21.value);
			
		if (!isNaN(parseInt(Q22.value)))
			Total += parseInt(Q22.value);

		if (!isNaN(parseInt(Q23.value)))
			Total += parseInt(Q23.value);
	}
	document.getElementById("Q24TOTAL").innerHTML = Total;
}
.SCRIPT = OFF

In this example, three NUMBER questions are created: Q21, Q22, and Q23.

The text of question Q24 is used to hold

  • an <A> anchor tag that, when clicked, launches the JavaScript function, AddUpQ21toQ23(), and
  • a <SPAN> tag that will hold the sum of the three numbers that is calculated by the JavaScript function.

The <SPAN> is also given a unique ID value, Q24TOTAL, to make it easier tell JavaScript where to put the result.

When this page is first displayed the browser, question Q24 will be displayed...

Click here for total: 0

If the respondent enter the numbers entered the number 10 in each of the three fields and then clicked on the link in question Q24, the sum will be displayed...

Click here for total: 30

Each time the respondent clicks on the link, the AddUpQ21toQ23() will run again and update the contents of the Q24TOTAL <SPAN> tag.

The JavaScript function, AddUpQ21toQ23(), is defined in the SCRIPT block. This function, if you are not familiar with JavaScript, may be a little more complicated than you were expecting but this is indeed how it is done.

JavaScript is an object-oriented language so you need to tell JavaScript how to find the data you want to process. On QPL web questionnaire pages, the question fields are objects that are always inside the document.QPL object. They are named with your question name, always in uppercase letters. And since the question object has more than one property, you must always use the "value" property to retrieve the current value in the field.

document.QPL.Q21.value

Since the respondent may leave a field blank, you must test for this situation before attempting to add the contents (while the QPL JavaScript functions only let a respondent enter numbers into a NUMBER question field, they do allow the field to be left blank which is treated as a missing value later when using statistical programs to analyze the results of the survey). The JavaScript parseInt() function returns the first integer it finds in the string or a NaN (not-a-number) value if it does not find one. The isNaN() checks the result of the parseInt() function and, if it is not a NaN, proceeds to add the integer to the running total. Thus, a blank response is treated as zero in this example, which may or may not be the behaviour you may need in your application.

Finally, getElementById() function is used to find <SPAN> tag where using its unique ID, Q24TOTAL, where it replaces the existing contents of the tag ('0' when the page is first opened in the browser) with the sum (which is converted back to a string automatically).