Finding Your Way
How Do I ... Process Web Forms with E-mail
This service is available to UWO information providers who use one of the corporate webserver at UWO:
Cgiemail is a tool that enables you to send an e-mail message based on a web form in a manner that gives you more control over the format of the message than using a simple mailto: . Cgiemail can handle many applications of web forms which means that custom CGI programs will not have to be written. The resulting message can be processed manually or used as input for your database.
Summary of the files involved
You need to create the files listed below. The rest of this How Do I... document will tell you exactly how you do this.
|something.html||This is the web form that people will fill out.|
|something.txt||This is the template that determines what the e-mail message will look like.|
|something-success.html||This is the optional file that the user will see after submitting the form.|
All these files must be stored in your web area on corporate web .uwo.ca with their protection set so that they are readable by all .
Note: Here and elsewhere we will use the word server to indicate one of either www , instruct or publish .
This document will help you write a web form that sends an e-mail message to you. The following are the steps involved:
- Create an e-mail template ( something.txt )
- Upload the template to the server
- Create the HTML form ( something.html )
- Make sure the ACTION is correct
- Try out your form with cgiecho
- Go live with cgiemail
- Add text to the success page (optional)
- Make some inputs required (optional)
- Specify formatting for some inputs (optional)
Before you start receiving e-mail messages through the web, you should decide what these messages should look like. Create an ASCII file, called an e-mail template , that looks something like this:
From: firstname.lastname@example.org (valid uwo id or mailing list) HEADER LINES To: email@example.com
Subject: questions three blank line Your e-mail address (required): [required-email]
What is your name? [yourname]
What is your quest? [quest] BODY What is your favourite colour? [colour]
You would store this template in a file, e.g. questions3.txt .
The template will be used by the cgiemail program, so before you upload the file to your web server, be careful to follow these guidelines:
- Wherever you want the user of your form to supply information, use a single word inside square brackets with no spaces, e.g. Your name: [yourname] . Not [Put your name here] . The names you put between the square brackets will establish where the fields in the web form will be put in the e-mail message.
- Make sure the address in the To: field is a vaild uwo id or mailing list. Do not use any email addresses from the form.
- If there are blank lines among the header lines, remove them.
- If there are blank lines before the header lines, remove them.
- Make sure all your header lines are valid. The first character on the line must be a letter. Most information should go in the message body; don't make up your own headers.
- Make sure there is a blank line between the header lines and the body.
- Make sure you save it as ASCII text. For example, if you are using Microsoft Word, use "Save As" and choose "Text Only with Line Breaks."
- If you created the file on a Mac, be sure to upload it as text, i.e. CR's translated. (Unix computers have different codes denoting the end of a line than Mac's do, so your file might look like one long line to the Unix computer.)
Within these guidelines there is a lot of flexibility. However, we suggest you confine yourself to the following header lines:
Subject: an appropriate subject
Cc: firstname.lastname@example.org Do not use any email addresses from the form.
The Cc: is optional. It will send a copy of the message to other people in addition to the primary addressee. If you have more than one address to put there, use commas to separate them. Make sure that all addresses in the To: and Cc: lines are correct, otherwise the message will bounce. Bounced messages go to the webmaster!
We strongly suggest that you always include a required field containing the e-mail address of the person who filled out the form. In the example, this is the field required-email . As explained in the section Make some inputs required , any field whose name starts with required- has to be filled out, otherwise the submission of the form will be rejected.
You should upload this file (as ASCII) to the web server in the usual way. For example, if the name of the file is questions3.txt and you are in department somedept on the university's central web server www.uwo.ca , the file will end up as questions3.txt in the departmental directory somedept . The exact file specification would be /web/www/somedept/questions3.txt .
If you are using the instruct server, you would put the file somewhere in /web/instruct .
If you use the publish server, you would put the file in your public_html area.
Next you have to create a form that will use the template. Here is an example:
Your e-mail address (required):
This is the HTML source ( questions3.html ):
The example assumes you are using the www server. See the section Make sure the ACTION is correct, below, for details on how to specify the action for the form.
This is a very simple example. To learn to create more complicated forms, read NCSA's guide or your favorite book on HTML. All types of inputs (radio buttons etc.) work the same way.
For now, simply note that the NAME of each INPUT corresponds to what you previously put in the e-mail template. In this example they are required-email, yourname, quest , and colour . Remember that a name that starts with required- indicates that that field has to be filled out in the form, otherwise the form will not be submitted.
The trickiest part of the HTML form is getting the ACTION set correctly. The following paragraphs show how to do this on the various central UWO servers.
NOTE: You must use https
In general, please note that the way in which you indicate where your .txt file resides is as if you were specifying a URL: you do not specify the full file path. In other words, on www you leave out /web/www , on instruct you leave out /web/instruct and on publish you use ~loginname/file.txt without mention of public_html .
On www.uwo.ca the ACTION should be set as follows:
\ / \ /
`------- Part 1 ------' ` ----- Part 2 -----'
Part 1 must be https, part 2 indicates where your e-mail template is stored. The XXXXXXXX , in the middle, is the program that will convert the form to an e-mail message. XXXXXXXX is of course not the real name of the program, you have to substitute either cgiecho or cgiemail . As shown in the next section, for testing purposes, it is best to first try out the form using cgiecho , and when you like the results switch to cgiemail .
On instruct.uwo.ca the ACTION should be set as follows:
\ / \ /
`--------- Part 1 ---------' ` ------------ Part 2 ------------'
Here /somecourse/somenumber indicates the web area assigned to the course in question. Otherwise the same applies as under www , above.
On publish.uwo.ca the ACTION should be set as follows:
\ / \ /
`-------- Part 1 ---------' ` ------- Part 2 ------'
Here loginname is the first portion of your Western email address. Otherwise the same applies as under www , above.
We recommend putting your forms in a restricted folder to minimize spamming. See http://www.uwo.ca/its/doc/hdi/web/restricted-site-form.html
To test your form, put in an ACTION with cgiecho , for example:
https://www.uwo.ca/cgi-bin/ cgiecho /somedept/questions3.txt
Then view your form in your favorite web browser, fill in the inputs, and submit it. You should see what the processed form looks like. If instead you see an error with a number near 500, your ACTION is probably set wrong. Go back to the previous step .
If some of your inputs don't seem to be showing up in the processed form, make sure that the inputs have the exact same names in the HTML form as in the ASCII template. E.g. NAME="yourname" in the HTML form and [yourname] in the e-mail template.
Now change cgiecho to cgiemail in the ACTION of your HTML form:
https://www.uwo.ca/cgi-bin/ cgiemail /somedept/questions3.txt
Try it out. You should receive an e-mail message with the processed form (provided the To: address in the e-mail template is yours!). If not, go back and make sure you correctly followed the instructions in step 1 .
If it works, congratulations!
When mail is sent, a page titled ``Success'' appears with the text of the e-mail message. You may use a hidden variable called ``addendum'' to add your own text. Here is a simple example:
If you are willing to assume that readers of your form are using recent browser software, then you may put HTML markup into this variable using the appropriate character entities . For example, if you wanted to add
then the HTML markup would be
meaning you would need the following in your form:
Note that besides being difficult to write, this feature won't work for people using older browser software.
Use an alternate success page
If you don't like the default page that comes up when e-mail is successfully sent, you can specify an alternate URL using a hidden variable called ``success'' in your HTML form, e.g.
There is no way to make this alternate success page contain information about the user who submitted in the form.
The example assumes you use the www server. If you use instruct or publish , you should specify the URL of the alternate success page in the appropriate way:
If you would like to automatically reject forms with certain inputs left blank, add the prefix required- to the name of the input in both your HTML form and your e-mail template. Here is an example:
In the HTML form:
Your e-mail address (required)
In the e-mail template
Your e-mail address: [required-email]
If, in your e-mail template, the text inside square brackets begins with %, cgiemail will use the printf() function in C on the field name after the comma. If you're not familiar with this function, look in a book on C. If you are familiar with it, please note these two differences:
- The first character in the format string must be %.
- Characters like \n and \t must be literal. If you want a newline, you have to put a newline just before the comma, even though this looks strange. For example, if Godzilla's Pizza wanted toppings listed one per line, they would put the following in their e-mail template:
This program was developed by Bruce Lewis from MIT. For further information see http://web.mit.edu/wwwdev/cgiemail/ .