Web Authoring: Forms and Counters with Mailform

Introduction

This tutorial covers the use of forms in web pages to gather information from users, and the script- mailform- that is used at UNC to process those forms. In addition, this document provides instructions for installing and using a counter script to track visitors to a web page. All of these instructions are intended for users with a basic understanding of HTML tags and their attributes.

Creating Forms Using mailform

From time to time, we may want to ask a few questions of the people who are looking at our web pages and examine the answers that they return. This could be accomplish ed by simply including an email link, such as <a href="mailto:email@server">. In this case, however, we're going to look at how to use forms in our Web pages which allow people to submit information. The method that we will be looking at here uses a script called mailform . The mailform program is supported on the main campus Web server, www.unc.edu.

With mailform, you can collect data from a form and have it delivered to you as an email message and/or have it appended to a pre-existing data file. The program is designed such that usage is restricted to www.unc.edu . Let's look at an example of a form using mailform to examine its construction piece by piece.

The <form> Tag

The <form> tag declares the existence of a form.

<html> <head>
<title>Forms with mailform</title> </head>
<body> <form method="post" action="/cgi-bin/mailform/">

The initial tags used in this file are exactly the same tags that you would use to create any other Web page. The only unfamiliar bit of information that we see is the <form> tag. There are two attributes here of which we must be aware: the method attribute and the action attribute. The "method=" attribute tells the form to post the data that it receives in one of two ways. Use the "post" value here. The "action=" attribute specifies what program to use to process the data received in the form. In this case the action is specified as: action="/cgi-bin/mailform".

Input Types

Forms created using mailform can support a number of different types of input. We receive input in our forms by using the <input> tag. We'll look at each of these different types of input in the following sections.

Text Input Type

<h4>Text Input</h4>
First Name:<INPUT TYPE=text NAME="first" SIZE=15><br>
Last Name:<INPUT TYPE=text NAME="last" SIZE=15><br>

The first, and most important, attribute that we see added to the <input> tag is the type attribute. This attribute tells the browser what type of input we are expecting and instructs it how to construct the input box. The name attribute is a variable that will be used later when we decide how we want to receive the data. The size attribute tells the browser how many characters long you want the input box to be.

Checkbox Input Type

<h4>Checkbox</h4>
These are my favorite schools <br> 
<INPUT TYPE=checkbox NAME="favs" VALUE="UNC-CH" CHECKED>UNC-CH<br>
<INPUT TYPE=checkbox NAME="favs" VALUE="UCLA">UCLA<br>
<INPUT TYPE=checkbox NAME="favs" VALUE="Duke">Duke<br>
<INPUT TYPE=checkbox NAME="favs" VALUE="NCSU">NCSU<br>

With the checkbox input type, we have a list of items that will appear in our form with a small checkbox in front of the text. We can "check" as many of the boxes as we like. Notice the "name" variable that we assign to each of these input boxes is the same. We are using the same value here because our respondents can choose one or many of these choices. By giving them all the same "name" variable, we can see all that they checked when we receive the data. The "value" attribute tells the form what to list when we receive the data. Here we want to use names that uniquely identify each item. The "checked" attribute tells the browser which one to initially select (i.e., when the page loads, this item will already have a check in its box).

Radio Buttons

<h4>Radio Buttons</h4>
<INPUT TYPE=radio NAME="best" VALUE="UNC-CH" CHECKED>UNC-CH<br>
<INPUT TYPE=radio NAME="best" VALUE="UCLA">UCLA<br>
<INPUT TYPE=radio NAME="best" VALUE="Duke">Duke<br>
<INPUT TYPE=radio NAME="best" VALUE="NCSU">NCSU<br>

Radio buttons are similar to the checkbox type of input. With radio buttons, however, only one item can be selected at a time. Otherwise, the attributes are the same as the checkbox example.

Drop-Down Box

<h4>Select</h4>
On Saturdays, I usually play: <SELECT NAME="sat">
<OPTION SELECTED>soccer <OPTION>basketball
<OPTION>football <OPTION>ultimate frisbee 
<OPTION>the cello </SELECT><br>

The <select> tag creates a drop-down box, which is similar to the "radio" type of input in that we are offered a number of items from which we can choose only one. The display of these items, however, is significantly different. The <option> tag allows us to enter list items which will appear as a single input box with a drop-down list of items from which the user can choose only one. The <option> tag with the selected attribute will appear first in the text box when the page is loaded in the browser window. Again, the name attribute will be used later when we receive our data.

Text Area Input

<h4>Text Area</h4>
This is what I did yesterday: 
<TEXTAREA NAME="yesterday" ROWS=12 COLS=50></TEXTAREA>

The <textarea> tag is used to create a text box in which users can type free text. The rows attribute determines how many rows high the text area will be, and the cols attribute determines how many characters wide the text area will be.

Form Submission

Displaying and Receiving Results

This section shows how we will receive our data. The input type should be set to "hidden" for fields which the person filling in the form will not see. The "NAME=" values address, file and reply are mailform reserved variables. The spelling of these values must be exact in order to run the mailform program.

AS EMAIL:

<INPUT TYPE="hidden" NAME="address" VALUE="onyen@server">

We can receive this data in an email message as above where "onyen@server" is replaced by a valid email address. Please see "Address" in the Reserved Variables section below for details.

TO A FILE:

We can also have the data appended to an existing text file. For example:

<INPUT TYPE="hidden" NAME="file" 
VALUE="/afs/isis.unc.edu/home/o/n/onyen/subdirectory/file_name">

where o is the first letter of your Onyen, n is the second letter, and onyen is your Onyen.

The file listed in the attribute above must be a preexisting file (the form will not create it for you) and must have world-writable permissions.

You must follow the instructions in the reference above. Do not set world-writable permissions while you are in your public_html directory or anyone will be able to write to your files. Note, too, that any other files that you put in this directory will be world-writeable. For more information on AFS permissions, see the documents [ http://help.unc.edu/?id=215 ] Introduction to AFS .

RESPONDING TO INPUT:

<INPUT TYPE="hidden" NAME="reply" VALUE="http://www.unc.edu/~onyen/reply_filename">

The VALUE attribute for NAME="reply" can specify the location of another HTML file that acknowledges the receipt of the form information and thanks the user for his or her participation. If there is no reply field the default reply will be sent verifying the values entered for each field.

Submit or Restart

<INPUT TYPE=submit VALUE="Submit"> <INPUT TYPE=reset VALUE="Startover"> </form>

These two input types will create buttons that give people the opportunity to submit their answers or to clear the form and start over again. The type attribute tells the browser which button will be used to submit the form and which will be used to reset it. The text value specified in each of the value attributes will appear as the name of each button. We can use any value that seems appropriate to us. Finally, we are ready to close the form using the </form> tag, end the the file with </body> and </html> , and move on to the display of our data.

A Sample of HTML File

The following html code is a sample using mailform to deliver the form content both as an email message and to a file.

<html>
<head>
<title>Forms with mailform</title>
</head>
<body>
<form method=post action="/cgi-bin/mailform">
<p>Your name: <input type="text" name="username">
<p>Your e-mail address: <input type="text" name="usermail">
<p>How do you like the mailform?</p>
<p><textarea name="message" rows=5 cols=40></textarea></p>
<input type="hidden" name="require" value="username,message">
<input type="hidden" name="address" value="onyen@server">
<input type="hidden" name="subject" value="My first mailform">
<input type="hidden" name="file" 
value="/afs/isis.unc.edu/home/o/n/onyon/subdirectory/file_name">
<input type="hidden" name="reply" value="http://www.unc.edu/~onyen/reply_filename">
<p><input type="submit">
</form>
</body>
</html>

Note

The above sample creates default output message only. We will explain the "Design Your Own Output" later.

Reserved Variables

There are eleven variables you should be aware of when using mailform. Nine (address, subject, require, reply, file, path, header,delim and delimvar) are hidden variables which the person filling in the form will not see. However, you MUST use "address" or "file" or both depending on how you want your message transported.

Table 1. Reserved Variables

Variable	Description
username	This field is to contain the sender's name.
usermail	This field is to contain the sender's email address.
address	The email address that the data will be sent to. This is usually your email address. This field is restricted to UNC email address, which means the address should contain "unc.edu". Separate them with "," if you have more then one email address.
subject	The subject of the form. The subject will be shown as "Comments on WWW pages" if you don't use it.
require	User can require that certain fields be filled in before the form can be successfully submitted. Simply create a name called "require" and associate a "values" statement with the name. The "value" statement should consist of a list of names of your mandatory fields seperated by commas. No space is needed between each value. For example: <input type="hidden" name="require" value="username,usermail">
reply	After the user has submitted the form, the form creator has the option of specifying a URL to send back a personal message. This is done by using the "reply" field. For example: <input type="hidden" name="reply" value="http://www.unc.edu/~onyen/thanks.html"> If there is no reply field the default reply will be sent verifying the values entered for each field.
file	The full path to the file where the data will be stored. It only allows a-z A-Z 0-9 . _ in the file name. For security reason, you should keep public_html readable only. The best way do this is to create a directory outside of public_html and make it writable so data can be written to the text files in this particular directory. To make it writable, you should go into the directory and issue the following commands: fs setacl -dir . -acl atn:webhosts rlw fs setacl -dir . -acl system:anyuser none The file that you are to write your data to must already exist. You may create an empty file using the following command: touch your_filename
path	If you want to design your own output format, you MUST give a full path of the form file so the mailform knows where to get the designed output format. For example: <input type="hidden" name="path" value="/afs/isis.unc.edu/home/o/n/onyen/public_html/subdirectory/filename">
header	By default the mailform program prints a mail header (date, From:, To: and Subject:) with your data to a file. You may add the following statement in your html file if you don't want the header created as part of your output file: <input type="hidden" name="header" value="n">
delim	The delim variable is always used in conjunction with the delimvar variable. It specifies the delimiter that seperates values of a selected set of variables that you may import into your database or spreadsheet. As an example, if you want to seperate values by semicolons (;) you would use the following: <input type="hidden" name="delim" value=";">
delimvar	This variable is always used in conjunction with delim and determines the list of variables and the order in which they will appear in your output file. The following example could be used to insert the variables street, city and state from your form in the specified order. The fields in the value statement should be seperated by commas. No space is needed between fields. <input type="hidden" name="delimvar" value="street,city,state">

Design Your Own Output

Syntax of mailform Commands

The mailform script will generate an output message for you. This message can be sent to an email address and/or saved to a pre-existing file. If you wish to customize the output message, these instructions will show you how to accomplish this.

First, the syntax you must follow can be summarized as:

<!--mailform "text $input{'variable'} text " -->

This statement can be broken up into different sections:

Each statement begins with  .
The output design is defined between double quotes. And, a space must precede the final double quote in each <!--mailform line.
In the above syntax, text will be a static message you define to identify a particular ouput variable.
The variable always belongs between $input{' and '} . No spaces are allowed in this section.

Sample Output Format

The following is a sample of the output format. We strongly suggest you put them right before the <body> tag:

<!--mailform "\n----------------------------------------\n "-->
<!--mailform "Name: $input{'username'}\n "-->
<!--mailform "Email: $input{'usermail'}\n "-->
<!--mailform "Following is the message:\n "-->
<!--mailform "$input{'message'}\n "-->
<!--mailform "\n----------------------------------------\n "-->
<!--end mailform-->

Note

mailform is very picky about the format of the <!--mailform lines. The < must be the first character on the line; it cannot be indented. There must not be a space between the "<!--" and the word "mailform".
The designed output should be wrapped in the double quotes.
A space must precede the final double quote in each <!--mailform line.
The variable names should be placed in between $input{' and '} and there is no space allowed.
Put  at the end of your designed output.

Special Characters

You can also use the following special characters to perform formatting functions:

\n new line
\t tab
\f form feed
\r return

"path" That Shows Where The Designed Output Is Located

Now that you have defined your own output format, you will need to define where the output format is located by defining the full path of your form file. You must put following line in your html file so the mailform knows where to get the designed output format.

<input type="hidden" name="path" 
value="/afs/isis.unc.edu/home/o/n/onyen/public_html/subdirectory/form_filename">

Delimited Output File

There are times when you may want to create a file having a certain delimiter seperating values. This is helpful when you wish to import your data in to various databases or spreadsheets. Mailform allows you to create a file consisting of an ordered set of variables coming from your form. The variables and their order are derived from the delimvar variable. The delimiter is specified by the delim variable. Use of this option restricts you to gathering your output to a file only. Output through email is not available when using this option.

About onyen and /o/n/onyen

Table 2. Definitions

Onyen	The onyen is what used to be called the UserID. "onyen" stands for the "Only Name You'll Ever Need". The onyen id and password will give you access to disk space, Internet access, Web pages, and an email.unc.edu email address.
onyen@server	Where "onyen@server" should be replaced by a valid email address. This is usually your email address.
/o/n/onyen	Where o is the first letter of your Onyen, n is the second letter, and onyen is your Onyen.

Getting the Path

Here are some tips to show you how to get the path. Before we go any futher, familiarize yourself with the following UNIX commands:

Table 3. UNIX commands

cd	change directory
ls	list files and sub directories
pwd	display your current working directory
/bin/pwd	display absolute path of your current working directory

You may already be using ssh to log on to the campus email server, or to log on to other hosts that provide public access. Issue ssh isis.unc.edu at the command line if you are on a Unix or Linux machine other than isis. Please review how to use ssh by reading [ http://help.unc.edu/?id=6160 ] Connecting to isis.unc.edu and your H-drive using SSH/SFTP Secure Shell in Windows . Remember that you should ssh to isis.unc.edu.
Enter your onyen and password.
Choose "6. Exit Menu (go back to a shell prompt)" if you get a login menu. This will bring you to a dollar sign($) which is the UNIX prompt.
Use the command pwd to display your current directory. You are at your home directory if it shows /afs/isis.unc.edu/home/o/n/onyen .
You should issue cd public_html to go to the public_html if your current working directory is not /afs/isis.unc.edu/home/o/n/onyen/public_html .
Issuing the command ls will list the files and sub directories.
If your form file is not under public_html, please use the cd command to go to the directory of the form file.
Now, by issuing /bin/pwd the prompt will display the proper path.

Controlling Automated Spam

We provide a script which will generate a random number when a user clicks the submit button for a form. The number will be displayed and the user is asked to enter the number. The data will only be submitted if a matched number is entered. The idea is to prevent spam from the automatic submission of form data by computer programs or scripts. This script assures that a form is actually being submitted by a real person at a keyboard.

To run this script, your should go to your html file and do following:

put following statement in between <head> and </head>:

<script LANGUAGE="JavaScript" src="http://www.unc.edu/js/secret.js"></script>

add following at the end of the "<form" statement:
```
onSubmit="return secret()"
```

mailform Troubleshooting Tips and Reminders

If you're having trouble getting your forms to work properly, just remember that mailform can be a bit tricky. Have patience and carefully check your code for inconsistencies. The following list of tips should put you on the fast track to success:

The mailform statements must be written literally. Do not put any spaces where you don't see them.
Make sure that the variable names that you use in your mailform statements appear exactly like they do in the name tag of your form parts.
The mailform statements must be flush with the left side of the screen. There can't be spaces or tabs before these statements.
The mailform program will give you the default output message if you don't define the "path" even if you customize the output message in your form files.
A space must precede the final double quote in each <!--mailform line.
Your output file must exist. The mailform program will not create the file for you. You can create a new file by issuing touch your_output_filename at the command line. This will create a new blank file for the mailform program to write to.
You can only have one output file.

Adding a Counter to Your Page

A counter tells people how many times the page has been hit (visited). If you are using isis.unc.edu as your Web server, go to the page [ http://www.unc.edu/campus/aboutweb/howto/cgi/counter.html ] http://www.unc.edu/campus/aboutweb/howto/cgi/counter.html to set up the data file for your counter. This file stores the number of hits. It will be deleted if there are not hits within a 180 day period. After you fill out the form, you will be given an HTML tag to put in your document where you want the counter. For example:

<IMG SRC="/cgi-bin/Count.cgi?ft=0|frgb=69;139;50| 
tr=0|trgb=0;0;0|wxh=15;20|md=6|dd=C|st=5|sh=1| df=hitcounttxt.dat" align=absmiddle>

This tag looks pretty confusing, but each of the arguments is explained below:

Table 4. Arguments and Descriptions

Argument	Name	Description
ft	Frame Width	Specifies the width of the frame, from 0 (none) to 9 (very thick).
frgb	Frame Color	Indicates the color of the frame in RGB format; the red, green, and blue codes are separated by a semi-colon.
tr	Transparency	Turns transparency on (1) or off (0).
trgb	Transparency Color	Indicates what color, in RGB format, should be made transparent.
wxh	Width & Height of the digits	Allows you to specify, in pixels, how high and wide you want the digits to be.
md	Maximum Digits	Specifies how many digits should be shown (5-10).
dd	Digit Type	Specifies the style of the digits. Styles are A-D.
df	Data File	Refers to the data file you set up on the web page given above.

Changing the Counter Color

The color of the counter number itself will be green as a default. To change this color, you need to add two arguments: these arguments will specify a color within the counter image to be changed and then indicate what color the first color should be changed to. First, you need to add srgb=00ff00 ; this argument indicates that you are targeting green (00ff00) to be changed to a different color. Then you need to add prgb= ###### , where ###### is the color that you want the counter number to be. ###### can be a hexidecimal color number or one of the accepted color words. For example:

<IMG SRC="/cgi-bin/Count.cgi?ft=0|frgb=69;139;50|tr=0| 
trgb=0;0;0|wxh=15;20|md=6|dd=C|st=5|sh=1|srgb=00ff00| prgb=ff00aa|df=hitcounttxt.dat" 
align=absmiddle>

Note

You will have trouble if you want to make the number black because the trgb=0;0;0 makes black, the default background color of the counter, transparent. If you try to make the counter number black, it too will be transparent. So if you're looking for a neutral color, you might have to settle for a nice gray.)

For more information on counter attributes see [ http://muquit.com/muquit/software/Count/Count.html#opti ] http://muquit.com/muquit/software/Count/Count.html#opti.

Web Authoring: Forms and Counters with Mailform

Web Authoring: Forms and Counters with Mailform

Introduction

Creating Forms Using mailform

The <form> Tag

Input Types

Text Input Type

Checkbox Input Type

Radio Buttons

Drop-Down Box

Text Area Input

Form Submission

Displaying and Receiving Results

AS EMAIL:

TO A FILE:

RESPONDING TO INPUT:

Submit or Restart

A Sample of HTML File

Note

Reserved Variables

Design Your Own Output

Syntax of mailform Commands

Sample Output Format

Note

Special Characters

"path" That Shows Where The Designed Output Is Located

Delimited Output File

About onyen and /o/n/onyen

Getting the Path

Controlling Automated Spam

mailform Troubleshooting Tips and Reminders

Adding a Counter to Your Page

Changing the Counter Color

Note

Post a Comment

Training