Forms

Follow these steps to run forms from the University of Texas Web server. You will need to consult the system administrator at your home institution if you want to house forms on your own server. This particular type of form will accept input from a remote user and e-mail the information to an address that you specify. Due to the relative complexity of the subject matter, I've never put these materials on-line before. If anything (or everything) is confusing, please let me know.

If you are serving forms from U.T., you will need two files:

comments.html -- the html document that actually produces the form page
mgate.forms -- a text file that acts as the form's "traffic cop". This file instructs the server where to send the information collected in the form, what information to require from a form, and what feedback the remote user will get once the form is submitted.

It is best to place these files in a directory called FORMS just below your publishing directory.

You may also wish to construct an optional third file that contains a "canned" response for remote users. This will be a regular html file named response.html, or something along those lines.

Part 1: comments.html -- the script that creates the form.

<HTML> 


<TITLE>  Comments Form</TITLE> 
<BODY> 
<H1> Comments Form</H1> 
<B> Note:</B>   You must complete all field below before this form will be processed.<P> 

<FORM ACTION = "http://uts.cc.utexas.edu/cgi-bin/mgate/~path_to_your_file/forms/
mgate.forms?comments" METHOD = POST> 
<HR> 
subject: <SELECT NAME = "subject"> 
<OPTION SELECTED>  Please select a topic from this list
<OPTION> Question about the research project
<OPTION> Comments
<OPTION> Request for information
</SELECT> 
Your e-mail address: <INPUT NAME = "from" TYPE = "text" SIZE = 45> 
Your question or comment: <TEXTAREA NAME = "body" ROWS=5 COLS=45> 
</TEXTAREA> 
<INPUT TYPE="submit" VALUE="Send this Form"> 
<INPUT TYPE="reset" VALUE="Clear this Form"> 
</FORM> 

<hr> 
</BODY> 
</HTML>

The script above produces a form that looks like this:

Notice in the script that every field has a NAME. You may name fields anything you want, but the name of each field should be unique. These names will be used by the mgate.forms file to indicate to the server which fields to require from the remote user and which fields to send to you.

The line that drives the form, that is to say makes it interactive, is

<FORM ACTION = "http://www.utexas.edu/cgi-bin/mgate/depts/grg/virtdept/workshops/1997/test/yourdirectory/forms/mgate.forms?comments" METHOD=POST>

This line routes the information entered by a remote user through a cgi script that is written and maintained by the UT Academic Computing staff. The particular script that handles this type of form resides on a machine named UTS in a directory called cgi-bin/mgate. You must copy this line exactly. The question mark (?) following mgate.forms must be included. The only items you may change are the path to your directory and the name of the comments file. The name of the html file that generates your comments form must follow the question mark, but should not include a file extension. For example, if your form file is called comments.html, your FORM ACTION line will end with:

. . . mgate.forms?comments" METHOD=POST>

But, if your form file is called homework.html, your FORM ACTION line will end with:

. . . mgate.forms?homework" METHOD=POST>

Oh, and if you're curious, there are two METHODs for passing data through a cgi on the Web. One is POST, the other is GET. Use POST. It's better, trust me. If you're really curious about the difference, keep reading. Otherwise, skip down to the next section.

In fact, GET is the default method, so it will be used if no method is specified. GET instructs a server to retrieve data referenced by a URL if the URL specifies a CGI application. The main uses for the GET method are performing searches and addressing queries to a server. POST, on the other hand, requests a server to accept an entity (data) enclosed within an HTTP request as a new object enclosed in the MIME body of a request. POST is better for FORMS because it passes form data as a chunk, rather than a string of http'd information which, in some cases, is acted upon rather strangely by the server.

Creating the FORM input fields

The example above includes three types of input fields:

SELECT (scrollable menu of options)
INPUT (one-line text input)
TEXTAREA (multiple-line text input)

If you use a SELECT field, you must supply the options that will be displayed in the pull-down bar. Refer to the sample script above.

Keep in mind that INPUT fields do not have to be closed, but SELECT and TEXTAREAs do, so:

You may also use checkboxes and radio buttons in your forms. The syntax for setting those up is slightly different from the textfields.

When you use checkboxes and radio buttons, you are allowing the user to select one or more options from a list of many defined by you. You must not only give the buttons a NAME, but a VALUE. Unlike the textareas discussed above, all the radio buttons in a series will have the same NAME but different VALUEs. Checkboxes should have unique names. Hopefully this will become clear as you study the following examples:

1.  Lines of longitude are called:<P> 
 
<INPUT TYPE="radio" NAME="question1" VALUE="a"> a.  meridians<BR> 

<INPUT TYPE="radio" NAME="question1" VALUE="b"> b.  parallels<BR> 

<INPUT TYPE="radio" NAME="question1" VALUE="c"> c.  axes<BR> 
<INPUT TYPE="radio" NAME="question1" VALUE="d"> d.  graticules<BR> 
<INPUT TYPE="radio" NAME="question1" VALUE="e"> e.  none of the above<BR>

This script produces the following:

1.  Lines of longitude are called:
 
a. meridians
b. parallels
c. axes
d. graticules
e. none of the above

The VALUE is what will be returned to you in an e-mail message.

Here's another example, followed by the script that generates it.

2.    Immigration is most clearly an example of:

 a.  stimulus diffusion
 b.  hierarchical diffusion
 c.  relocation diffusion
 d.  contagious diffusion
 e.  none of the above

Here's the code:

2. Immigration is most clearly an example of: <INPUT TYPE="radio" NAME="question2" VALUE="a" > a. stimulus diffusion
<INPUT TYPE="radio" NAME="question2" VALUE="b" > b. hierarchical diffusion
<INPUT TYPE="radio" NAME="question2" VALUE="c" > c. relocation diffusion
<INPUT TYPE="radio" NAME="question2" VALUE="d" > d. contagious diffusion
<INPUT TYPE="radio" NAME="question2" VALUE="e"> e. none of the above

Checkbox syntax:

3. South America is the largest continent in the world.

<INPUT TYPE="checkbox" NAME="T/F" VALUE="true"> True
<INPUT TYPE="checkbox" NAME="T/F" VALUE="false"> False

This is what the script produces:

You'll notice that the main difference between checkboxes and radioboxes is that checkboxes allow multiple selections to be made, while radio boxes allow only one correct answer. Also, you may include inlined images with radio boxes, but not with checkboxes.

Part 2: mgate.forms -- the traffic cop

The mgate.forms file is a simple text file that tells the server's cgi script what data to collect and where to send it. A typical mgate.forms file will look like this:

form comments address shannon@texas.grg.utexas.edu
form comments require from,subject,body
form comments forward formfields body
form comments response http://www.utexas.edu/depts/grg/virtdept/workshops/1997/test/yourdirectory/forms/response.html

That's it.

If you compare this file to the sample form script above, you will notice that the NAMEs (from, subject, body) appear in both places. If you had named those fields happy, dopey, and sleepy, those are the NAMEs that should appear in both files. You can add fields to the comments.html file, but remember to add them to the FORWARD line (line 3) of mgate.forms, or you will not receive the information contained in them.

You might also have notice that the REQUIRE line has the fieldNAMEs from, subject, and body, but the FORWARD line only has body. This is because the cgi-script that drives this whole thing automatically uses the from and subject fields in the e-mail message that gets sent to you (but only as long as the fields are NAMEd from and subject). If those field names are included in the FORWARD line, the information will be duplicated: it will appear in the e-mail header and in the body of your e-mail message.

Technically, you don't have to REQUIRE anything, but it's good practice to REQUIRE a from field. This script will not verify an e-mail address, but the remote-user doesn't necessarily know that, and such a requirement acts as a (very) primitive security measure against your e-mail being flooded with unwanted comments.

While I'm on the subject, you may also want to establish a separate e-mail account just for handling comment forms.

Okay. Here are some things you should remember about mgate.forms:

The file MUST contain the first three lines, in that order.
The file MUST be called mgate.forms
The file MUST NOT have spaces between field names in either the require or forward lines.

In the example above, comments refers to the comments.html file. If your form file is called homework.html, your mgate.forms file will look like:

form homework address shannon@texas.grg.utexas.edu
form homework require from,subject,body
form homework forward formfields body
form homework response http://www.utexas.edu/depts/grg/virtdept/workshops/1997/test/yourdirectory/forms/response.html

If you do not have a response file, DO NOT include line 4. If you do have a response file, but it is not called response.html, be sure to make to appropriate modifications to the path name in line four.

If you want the form data to be sent to more than one person, simply place a comma and the additional e-mail address at the end of the first line. DO NOT put a space after the comma:

form comments address shannon@texas.grg.utexas.edu,k.foote@mail.utexas.edu

You can ONLY HAVE ONE mgate.forms file. If you want more than one form (one for general comments and one for homework, for instance), simply expand your mgate.forms file:

form homework address shannon@texas.grg.utexas.edu
form homework require from,subject,body
form homework forward formfields body
form homework response http://uts.cc.utexas.edu/~your_directory/forms/hwresponse.html

form comments address shannon@texas.grg.utexas.edu
form comments require from,subject,body
form comments forward formfields body
form comments response http://uts.cc.utexas.edu/~your_directory/forms/cmtresponse.html

Part 3: Response.html

It's polite to send a response when someone takes the time to fill out and submit one of your forms. A response also answers the nagging question "did my comment get there?"

A response file is a simple html document. It might look something like:

<html>
<title> response < /title >
<hr>
Your question or comment has been sent to your name here and will
 be handled as soon as possible.

Thanks for taking the time to comment on our web pages.
</HTML>

Well, that's it for forms. Back to the main graphics notes.

Created by Shannon Crum.