2009-08-03
QPL Reference Manual

Warning! This page is in the process of being rewritten for QPL Version 6. It may still have references to QPL Version 5.

The characteristics of emailed questionnaires differs from web site-based questionnaires. In particular, email questionnaires

Emailing questionnaires is best suited for very short questionnaires that can be easily answered in one sitting.

At your option, respondents may either submit your questionnaire directly from their email readers or, if their email reader does not support HTML-formatted messages, may use their browser to go to your questionnaire web site and submit their responses there.

Other than these limitations, there is nothing special you need to do when writing your QPL program.

Steps

Setting up an email questionnaire involves a number of steps, most of which do not differ much from the normal QPL web site development process.

  1. Write Your Questionnaire
  2. Select Data Entry Option
  3. Select Log In and Confirmation Options
  4. Deploy Your Web Site
  5. Build an Email Version of Your Questionnaire
  6. Create a New Email Message Template With Your Questionnaire

1. Write Your Questionnaire

As mentioned above, the questionnaire should be short and limited to one page. You should include instructions on

Normally, contact information is put on the home page and linked to the question mark button on the navigation bar at the bottom of the questionnaire web site. Since neither of these are sent with the emailed questionnaire, you should include this information in the questionnaire itself.

Respondents must click the "Submit" button at the bottom of the email message to send their responses to your questionnaire web site. A Notice message will be displayed in the respondents browsers that says that their responses were stored successfully.

Replying to the emailed questionnaire does not send the data to the web site. It just returns a message to the person you named in the Reply-To field on the Edit Message page.

2. Select Data Entry Option

By default, responses may be submitted only once. If a respondent clicks on the "Submit" button again, a Notice message will be displayed in his browser that says that he already submitted his responses.

You can change this behavior by changing the "Data entry" option on Default Project Settings page from

With this setting, a new questionnaire record will be added to your web site data base each time the respondent clicks on the "Submit" button.

Since a respondent's current responses are not sent in the email message, there is no option that lets a respondent update their responses. If a respondent wants to change his answers, you may let him log into the site normally by sending him the URL and his user name and password.

3. Select Log In and Confirmation Options

By default, respondents must have user accounts in order to submit responses from an email questionnaire. This is usually the case since you need to create user accounts with email addresses to send the email messages anyway. A respondent's user name for your project is automatically embedded in a hidden field when you build the email-version of your questionnaire.

There are two other log in options you may select on the Default Project Settings page: "No account required." and "User may create an account." The "No account required" setting lets a respondent submit responses any number of times. Each submission is added to the questionnaire data base as a new record under the "anonymous" account, which will not tell you who submitted the case or how many cases were submitted by one respondent.

The remaining option, "User may create an account," is used only in customized applications where the mailing web site and questionnaire web site are not the same. Here, the mailing web site embeds the user account in each message. When a respondent submits the message, the data is redirected (by hand-modifying the generated questionnaire) to the second site which has no account information. With this Log in option, an account will be created when the data is received. Both Data Entry options affect this option as described above.

When a respondent sends his data to the web site by clicking on the Submit button in the email message, the server will respond by displaying a page to the respondent in a new browser window that confirms that the responses were received (or that the data has already been received).

You also may let the web server send this same information to the respondent as an email message by setting the Author field on the administrative Default Project Settings page to the email address you want to use as the sender (i.e., the From: address in the message). If the respondent's email address is set on the Email address field of the Edit user account page then a message will be sent when the respondent clicks on the submit button. Also, the information you put in the Assistance note for error pages field on the Default Project Settings page will be put at the bottom of the automatic confirmation email notice.

4. Deploy Your Web Site

Build your questionnaire web site, load your use accounts, and set your options on the Default Project Settings page. See Deployment for more information.

You should consider setting up your web site without the menu or navigation bars since this is how the questionnaire will appear to respondents who can open it in their email reader. See Changing the Default Page Layout for more information.

5. Build an Email Version of Your Questionnaire

Normally, you would build the web site version of your questionnaire using the PHP button () on the QPL toolbar in HomeSite (or using the /php option with qpl_convert if using the Console Edition). Here, you still need to build the PHP files to deploy your questionnaire web site. But, you also need to make an email-able version of your questionnaire using the HTML button () on the QPL toolbar (or using the /html option in the Console edition) by adding the "/e" convert option. (See also Converter Command Line Options.)

HomeSite Example

** CONVERT Options: /d /f /l /e

In HomeSite, add the /e option on the CONVERT Options line at the top of your source questionnaire program file (ex. job.pg6), then click on the HTML button () on the QPL toolbar to build the job.htm file (i.e., where "job" is the name of your program file.)

Console Example

C:\myjob> qpl_compile job.pg6
C:\myjob> qpl_convert job.qpl  /d /f /l /e /htm

In the Console edition, enter the /e option before the /htm option.

6. Create a New Email Message Template With Your Questionnaire

Follow the usual steps to create your message template. (See Email.)

On the Edit Message page, paste the entire job.htm file you just created into the HTML Message text box. Respondents who can view HTML messages in their email readers will see this version of your message.

Respondents who can not view HTML messages will see the message you enter in the Text Message box. Since the web site can be logged into normally, you should enter a message here that tells a respondent about your questionnaire and provides the URL to the web site, his user name, and his password. Then respondents may submit their answers either using the questionnaire in the email message or by going to your web site.