More advanced HTML features:

Form Handler

We have created a way for users at Lehigh to use their own forms (The Intermediate Web Authoring seminar includes detailed instructions on creating web based forms). Forms are HTML documents which allow you to obtain information from users browsing through your home pages. The comment form and guestbook documents available to Lehigh home page owners are two examples of how forms can be used. We also make available a script to handle processing of 'generic' forms, so that users can write their own forms and have the input emailed to them.

This documentation explains the forms handler:

Technical Details: for those who already know how to create a form, this gives the technical specs for creating a form to use the form handler
How to do it: for those who are creating their first form, this gives instructions in more detail.
What happens: what the output of the form will be.
Example Form: An example of the whole form.

Detailed documentation by the author of the form processing script is also available.

Technical Details

When an HTML form document is used, there is an ACTION specified that tells Lehigh's server what to do with the information provided in a form, and there is also a METHOD specified which controls how the information is sent to Lehigh's server. Ordinarily, the ACTION specifies that some program be run on the server that processes the data received. These programs are called CGI scripts. Users can't write CGI scripts for Lehigh's server, so we have written a generic script which will process form data.

This CGI script accepts form input from most HTML forms. Certain restrictions apply: the method must be POST, INPUT/FILE fields are not supported, and certain fields (FORMNAME, RECIPIENT, and SENDER--the names are case-sensitive) are required. Another special field (CO-RECIPIENT) is optional. RECIPIENT, CO-RECIPIENT, and SENDER are electronic mail addresses. RECIPIENT, CO-RECIPIENT, and FORMNAME are usually specified as "hidden" fields. SENDER is usually a field of type INPUT/TEXT for an address supplied by the person filling out the form. The contents of the form are sent to the address specified as RECIPIENT as an e-mail message. The message appears as if it were from the SENDER.

METHOD="POST"
ACTION="http://www.lehigh.edu/cgi-bin/pquery"
<INPUT TYPE="hidden" NAME="FORMNAME" VALUE="Name of Form">

(The VALUE will be the subject line of the email containing the form contents)

<INPUT TYPE="hidden" NAME="RECIPIENT" VALUE="Your Email Address">

(The VALUE of this field must be the full email address to which the form contents should be sent.)

<INPUT TYPE="text" NAME="SENDER">

(The VALUE entered into this field must be a full, valid email address. This should be the person completing the form; the email of the form contents appears to come from this address)

A single additional recipient can be added by adding a field for CO-RECIPIENT:

Email Address

The forms handler includes support for author-defined required fields. Any field (for example, a field named "x") can be immediately preceeded by a field named "x-REQUIRED" (caps mandatory) which indicates that the following field is "required" (i.e., must not be blank). If a required field is left blank, the form is rejected. The "x-REQUIRED" field is normally specified as a "hidden" field. Any value given to this "x-REQUIRED" field is ignored.

NAMEs of fields should not have spaces, etc. in them; names with spaces will be truncated at the first space.

Note: the current form handler, pquery, replaces an older form handler script, process_query. process_query can cause submission errors and is no longer supported. Most forms can be converted to pquery without a problem, but you should verify that the old form has RECIPIENT, FORMNAME, and SENDER fields and that RECIPIENT and SENDER addresses are full email addresses.

Instructions: Creating a Form to use the Form Handler

The data processed by Lehigh's generic form handler will be sent as an e-mail message to the form owner. The following instructions describe how to use the form handler to process data entered into a form that you create.

There are 3 steps you need to perform in creating a form ...

Create a form with the correct ACTION and METHOD specified
Add mandatory fields (make sure the field names are upper case)
Upload the form to the web and link to it from an existing HTML document

Step 1: Create a form

This section includes some basic information about creating fields in forms. You may want to consult the Advanced web authoring forms documentation. In addition, most guides to web page creation include information on creating forms; you will probably want to read up on them before beginning.

The Barebones Guide to HTML has a section on forms elements.
WebCom has a forms tutorial on the web
WDVL has a Forms Quick Reference page
NCSA wrote documentation on creating form documents
HTML Goodies has a nice Forms Tutorial

You will need to create an HTML document, putting the form elements inside it. (Note: Netscape Composer does not support forms creation. Handcoding HTML, or using HTML tools such as Dreamweaver and VisualPage is suggested for creating HTML forms. Frontpage is not recommended for form creation at this time.)

Begin the form by putting in the following FORM tag:

 
<FORM METHOD="POST" ACTION="http://www.lehigh.edu/cgi-bin/pquery">

Be sure to end the form element with the following tag:

  </FORM>

Form Field Elements

INPUT, TEXTAREA, SELECT, etc. elements should be added within the form element (between the two tags) along with appropriate text, to create the form you want. Each input field element must has a NAME and a VALUE is either defined for the element or entered into it.

Fields/buttons in the form are defined with form input elements:

Text input fields, like this:

<INPUT TYPE="text" NAME="textinput" VALUE="default">

Text areas/text boxes, like this: Default text

<TEXTAREA NAME="essay" ROWS=4 COLS=20>Default text </TEXTAREA>

Drop-down menus

<select NAME="color"><OPTION>Green <OPTION>Yellow <OPTION>Red </select>
For each option, the value returned is the text after it.
Checkboxes: Married? Yes No

Married? <input TYPE="checkbox" NAME="Married" Value="Yes"><input TYPE="checkbox" NAME="Married" Value="No">
You must specify a value for the check boxes, and all the boxes for the same field should have the same name.
Radio Buttons:FemaleMale

<input TYPE="radio" NAME="Gender" VALUE="Female">Female <input TYPE="radio" Name="Gender" Value="Male"> Male
Only one radio button can be selected at a time. You must specify a value for each button, and all the buttons for the same field should have the same name.
Hidden Fields:

<input TYPE="hidden" NAME="Reminder" VALUE="Yes, Boss, you did ask for a form to do this">
The user will not see this field, but the contents will be included in the form output.

All forms must have a Submit button in them:
<input type="submit">
The user needs to click on the submit button in order to submit the form.
The NAMEs cannot have spaces or question marks in them; but the VALUEs can have spaces and any other special characters you like. It's important to use meaningful names for your fields, because when the results of the form are emailed, the field names are how you will identify which answer goes with which question.

Making fields required
The forms handler lets you specify specific fields as required, so that the user must fill them in or select an answer for the field. If a required field is left blank when the form is submitted, the user will get an error message and be asked to go back and complete the form.
To make any field required, you insert a hidden field in the form, immediately before the field, whose NAME is name-REQUIRED-- where name is the name of the field that should be required.
So, to make the field YourName required, you would use the following code for the field:
<INPUT TYPE="hidden" NAME="YourName-REQUIRED">

<INPUT TYPE="text" NAME="YourName">
If you don't set the field up with any required fields, the only fields that are required are: FORMNAME, RECIPIENT, and SENDER .
You can have fields whose names are of the form x-REQUIRED, as long as the next field is not named x.

Step 2: Add mandatory fields
Somewhere in the form definition, the following 3 mandatory fields must be added:
<INPUT TYPE="hidden" NAME="FORMNAME" VALUE="Title of Form"> <INPUT TYPE="hidden" NAME="RECIPIENT" VALUE="Your Email Address"> <INPUT TYPE="text" NAME="SENDER">
A copy of form contents can also be sent to the CO-RECIPIENT, if one is specified. To specify a co-recipient, add a field:
<INPUT TYPE="hidden" NAME="CO-RECIPIENT" VALUE="Co-Recipient's Email Address">
These fields don't have to be of the type specified, but their names must remain the same, and their names must be in UPPER CASE. The values of the fields must be set up correctly, in order for the form handler to execute without error.

In FORMNAME, Title of Form should be set to the title you choose for the form. The title will appear in the subject of the email message containing the form contents.

In RECIPIENT must be the full e-mail address of the person to receive the contents of the form.

CO-RECIPIENT must also be a full email address.

SENDER must be a full email address.

RECIPIENT, CO-RECIPIENT, and FORMNAME are usually specified as "hidden" fields, whose values are preset by the author of the form . SENDER should be supplied by the person filling out the form, and so is usually a field of type INPUT/TEXT.
Step 3: Upload the HTML form and link to it from an existing HTML document
Form documents are HTML documents, and are linked the same way HTML documents are linked. Use FTP or Netscape Composer's Publish function to get the page up into your space on the Lehigh Web site. Then edit one of your existing pages to link to the form page so that people will get to your form, and/or let people know

What happens when the form is filled out
Once the form is on the web, users can fill it out and submit it by pressing the submit button.
If the form is constructed correctly and they have filled out the form with all the required fields, their web browser will display a results page. This page tells them where the results of the form have been sent, and gives a table with each field in the form, followed by the user's response. It also includes a link back to the form, created using the 'referrer' property from the server. (If the form is not on a web server, and under certain other conditions, this link will be invalid.)
In addition, a email containing of the field names and their contents will be sent to the email address specified in RECIPIENT, and a copy sent to the CO-RECIPIENT if one was specified.
If the form was not constructed correctly, the user will get a page with an error message on it, explaining why the form was not processed. If required fields were not filled in, the error message will say which fields were missing or blank. The page includes a link back to the form, so they can try again.

Example Form
This is an example of a simple form. You can copy the code for this form, but you will need to change the formname and the recipient address.
Your Name:
Your Email Address:
Lehigh Affiliation:StudentFaculty/StaffAlumOther
Comments:

Last updated January 9, 2002, by JAH.