CGI for Processing Web Page Forms

Getting stuff from my form…

Once you have written your form, you need to get the information to yourself in some manner. The GenericEMailForm will process information gathered on your form and send it to your e-mail account, or write it to a file in your accout. It supports secure transactions if you have a PGP or GPG key pair.

You must already understand forms (or have someone else create the form for you) in order to use the GenericEMailForm CGI. See all our form pages for more info about forms and html.

For our purposes we will be using the following HTML syntax:

<form method="post" action="http://www.sandiego.edu/cgi-bin/GenericEMailForm.cgi">

This line tells the browser that when the submit button is hit to send the data from the various fields to the GenericEMailForm script inorder to be processed. The script will then take the input field data and transfer it to the specified email address.

The Mandatories

When using the GenericEMailForm script there are two variables that must be included in the form and are mandatory for the GenericEMailForm script to work correctly. These required form values are the subject of the email and and the recipient(s) of the email message.

To insert these values you must have the following HTML somewhere in bewteen the form markers:

The Subject of the Message:

<input type="hidden" name="x_subject" value="Insert the subject you want here">

Or you can let the reader determine the subject by instead using the following:

<input type="text" name="x_subject" value="Insert the subject you want to appear in the box">

The Recipient of the Message:

This is the e-mail address that the message will go to.

<input type="hidden" name="x_recipient" value="Insert your e-mail address here">

You may specify as many x_recipients as you wish. If you need the additional recipients to also appear in the form data, give the fields a name and then add “x_recipient_” to the front of the name.

<input type="text" name="x_recipient_Advisor Address">

The Optionals

The following form values can be added but are optional:

Order

Order of returning data (optional); order can be alphabetic, or be a comma-delimited list of field names. If the latter, any omitted field names are ignored, and case is sensitive.

<input type="hidden" name="x_order" value="alphabetic">
<input type="hidden" name="x_order" value="fieldname1, fieldname2, fieldname3">

Required

Fields that are required (optional) field names, case sensitive, listed in comma-delimited. When the specified fields are not filled out the script will send the user to the error message.

<input type="hidden" name="x_required" value="fieldname1, fieldname2, fieldname3">

Numeric Fields

You can specify that a field should not contain letters using the ‘x_numbers’ field. The CGI will verify that the field does not contain any letters. It will allow numbers and non-alphanumeric characters. For example, ‘296-6868’ will be a valid number, as will ‘$48.99’. But ‘296-8686 x8773’ will not, nor will ‘48 dollars’.

<input type="hidden" name="x_numbers" value="fieldname1, fieldname2, fieldname3">

Return Page

You can specify a page to return to, and the text to link to that page. By default, there is a link to the page containing the form.

<input type="hidden" name="x_return_url" value="/~mysite/next.html"> <input type="hidden" name="x_return_text" value="Continue to Next Page">

Gracias

The thank you title. This title will be displayed on the page that the reader sees after filling out the form.

<input type="hidden" name="x_gracias" value="Thank you for your information!">

Error

The error title. This title will be displayed if an error occurs. For example, the reader didn't fill out one of your required fields.

<input type="hidden" name="x_error" value="Sorry, a problem occurred!">

Pre-Verifying Form Data

The CGI will inform users if they do not fill out required fields or if the e-mail addresses or numbers they enter are invalid. If you wish to have the form warn them before they are allowed to submit the form, you can do so with Javascript. Add the following to the top of your web page:

<script language="Javascript" src="/includes/forms.js"></script>

Then, in the <form> tag, add “onsubmit="return verifyForm(this);"”:

<form method="post" action="/cgi-bin/GenericEMailForm.cgi" onsubmit="return verifyForm(this);">

Remember that you cannot rely on Javascript working. It is a client-side feature and may be turned off by any users who wish to avoid it. Also, future versions of Javascript may ignore some of your fields. (To hopefully avoid this, you will probably want to capitalize the first letter of each of your non ‘x_’ fields.)

Secure Data Transfer

The general-use USD webserver (www) has a secure mode. Any Web page on www can be viewed with ‘https’ instead of ‘http’ to view it securely.

If security is important to your data, the GenericEMailForm can help you out. You need to have a PGP or GPG key pair. You need to upload your public key to your account. And you need to add your public key to your on-line public keyring.

If you don’t know what a PGP or GPG key pair is, you’ll need to learn that first. Go to http://www.pgpi.org/ to download a copy of PGP for your computer. You will need to create a “key pair”, which will include both a private and a public key. It is your public key that you will put on the server. Never put your private key on the server.

Once you have a key pair, save your public key as an “ascii” or “text” version, and upload this file to your Unix account using FTP. Then, use ‘telnet’ to get to your Unix command line, and type:

1. mkdir ~/.gnupg
2. /usr/local/scripts/bin/gpg --import filename
3. pwd

Press return or enter after each line, and replace “filename” with the name of the public key file that you uploaded. Remember what you saw when you typed ‘pwd’. To double-check that your public key was imported correctly, type “/usr/local/scripts/bin/gpg --list-keys” and press return.

Now that you have your public key in your on-line keyring, you can have the CGI encrypt your form data by adding the following hidden fields:

<input type="hidden" name="x_gpgkeyname" value="keyname"> <input type="hidden" name="x_gpgkeyfile" value="publickeyfile">

“Keyname” will be the name given to that key, probably your Unet username or your first name. “Publickeyfile” will be the full path to the public key file, which will be what you saw when you typed ‘pwd’ and then “/.gnupg/pubring.gpg”. For example, “/sites/ac/.gnupg/pubring.gpg” or “/homes/barney/.gnupg/pubring.gpg”.

Mail Template File

By default, GenericEMailForm takes the form fields and returns them to you, one field per line. If you use the “x_order” directive, you can specify the order that they’re listed, but that’s it. If you would rather be able to further customize what you get, you can create a special “mail template” file. The file should be exactly what you want to receive. Tell GenericEMailForm where to put the field values by using the field name, surrounded by “percent” signs:

%Name% would like to audit %Course%.

Besides your own form fields, there are some built-in fields that you can use:

• _Referer: The Web page that they came from (most likely your form page).
• _UserAgent: The name that the reader’s Web browser uses to identify itself. Usually, this will tell you both the browser’s name and the computer or operating system it is running under.
• _Address: The IP address of the reader’s computer.
• _Time: The date and time that the form was filled out.

And, inside your form, you would add the following field code: <input type="hidden" name="x_mail" value="/u9/users/john/templates/classes">. This assumes that you have stored your template as “classes” inside a folder called “templates” in your home directory, and your home directory is “/u9/users/john”. You can find out what your home directory is by typing pwd.

In order to use this option, you must also grant GenericEMailForm permission to display all files in the directory where you are storing the template. Do this by creating a file called “x_mail” in the same directory as your x_mail template file.

Within the x_mail file, you can specify that some things are not e-mailed and that some things are not filed (see ‘x_file’, below). You might do this, for example, to display some HTML code without e-mailing that code to yourself. Surround things you don’t want e-mailed with <nomail>…</nomail> and things that you do not want filed with <nofile>…</nofile>.

If the “x_mail” option is confusing, don’t worry about it! You can leave it blank (not use it) and you’ll still get your form data.

Saving Data to a File

Normally, it is easiest to have form information sent to you via e-mail. If you are familiar with Unix, however, you can also have this information saved to a file. You use the “x_file” option to tell the CGI where this file is. All data filled out in the form will get appended to that file. If you specify an ‘x_file’ you are not required to specify an ‘x_recipient’. If you specify both an x_file and an x_recipient, the data will be both written to the file and e-mailed to the recipient.

The directory that contains the file you are appending to must contain the file “x_mail”. This tells the CGI that it is okay to append to any file in this directory. Also, your file must be writable to the webserver. Use the “chmod” command to do that. “chmod ugo+w” and then the filename should do it for you. You will want to store your data files in a special directory separate from the rest of your Unix files. The file itself must already exist. The CGI will not create files. Use the ‘touch’ command on Unix to create an empty file.

If you are not familiar with Unix, we strongly recommend not making use of this option.

The folowing is the complete syntax for a sample form using the GenericEMailForm. You can cut and paste this form into your HTML document or use it as a model to understand how all this works.

<form method="post" action="http://www.sandiego.edu/cgi-bin/GenericEMailForm.cgi">
<input type="hidden" name="x_recipient" value="nil@cerebus.sandiego.edu">
<input type="hidden" name="x_required" value="name">
<input type="hidden" name="x_order" value="name,message">
<input type="hidden" name="x_gracias" value="That was easy, wasn't it?">
<input type="hidden" name="x_error" value="Hey, what're you trying to pull?">
<strong>Enter Your Name: </strong><br>
<input type="text" size="35" name="Name" value=""><br><br>
<strong>Enter Your Reason for writing us: </strong><br>
<input type="text" size="35" name="x_subject" value="Gnarly!"><br><br>
<strong>Enter Your Message: </strong><br> <Textarea Cols="50" Rows="5" Wrap="yes" Name="Message"></Textarea><br><br> <Input Type="submit" Value="Post Now"> </form>

Notice that all of the items used by GenericEMailForm begin with ‘x_’, and all of the items that you want are just in English.