Forms to E-Mail Using Tcl
by J.M. Ivler
This article discusses the process of using a CGI (Common Gateway Interface) program
in Tcl to send forms data to someone via e-mail. To start with, let's clarify some things.
Tcl was chosen because it is easy for someone else to extend, and this program was
written to be placed into the public domain. This doesn't mean that the program couldn't
have been written in C or in Perl. Tcl was chosen for a number of reasons; the accompanying article explains some of them.
The Tcl program does rely on a C program called un-cgi, written and maintained by
This program takes the "put" request and unbundles the input. It then creates Unix environment pairs between the value from the form (prefixed with WWW_ ) and the information associated to the value. Uncgi can be obtained from two separate FTP locations on the Internet, listed below.
Why use uncgi? Couldn't this all have been done in Tcl? Yes, uncgi has numerous powerful features that could have been duplicated in the Tcl programs, but why duplicate effort when someone has already done it? It isn't like uncgi was going to be expanded or enhanced in the duplication, so it is used as is.
This article is set up in sections. The first provides the problem scope of the requirements for both the V1.0 and the V2.0 code. The next section discusses some of the issues of form design, and how to utilize the utility. A section on installation of the software follows. The next section talks about the actual Tcl and break the code down at a level that will permit even the most novice Tcl programmer to modify it. Finally, the article will close with an example session with the sample form, and the e-mail reply.
What It Does
This process will take the variable fields from a form and use uncgi to create environment variables from them. These will then be processed by the email.tcl procedure. The email.tcl procedure will locate all the appropriate environment variables, extract them from the environment, and then e-mail them to you.
This process requires the following software:
- Tcl 7.3 (or 7.4) from Tcl Developer Xchange
- uncgi 1.4 (Since this article was written, uncgi has been updated to V1.5 or higher — the noted changes between V1.4 and V1.5 should not have any effect on email.tcl. V1.4 is still available from the above URL).
- email.tcl 2.0. In order to use this software, a form must be created that will be filled out and sent via the system's e-mail (a sample form is shown in the next section). When a user submits this form, the uncgi processor is started and all the values of the form are made into environment variables prefixed by WWW_ . The email.tcl process is then started and the variables are placed into a file to be sent to the e-mail recipient.
Although that sounds simple, there are other concerns that must be addressed when doing this. These concerns include "Do you allow e-mail internally only, or will you allow e-mail out to the Internet?"
Why would Internet e-mail be a concern? Because of the way the Web works. The e-mail sent would be done so from your http "user" name as established in the httpd.conf configuration file. As most sites use the value of "nobody" as the account name, this provides a very nice way to allow anonymous e-mail from within a Web-based environment.
If the form allowed the user to specify the e-mail address of the end user (in the examples, this appears as the hidden field "mailto" in the form), and had a text area entry box (like the one used in the example below for comments), anyone would be able to compose a message to any Internet e-mail address and send it out as user firstname.lastname@example.org. Consider someone using that form to e-mail the email@example.com. When the Secret Service comes knocking on your door, and takes away your computer equipment, then you will really understand why you might want to disallow this feature.
It cannot be stressed enough that you should consider what you are doing, and the consequences of that action, by setting this up to permit anonymous e-mail on the Internet. In order to ensure that you have the capability to control this feature, options have been provided that permit the Webmaster control over Internet e-mail access. Additionally, a number of options have been preset within the code (you can choose to turn them on if you wish), and other options are provided in comments to the code, with the Tcl code to insert also provided.
Certain additional variables are provided that can allow the e-mail to be "fine-tuned" to meet the needs of the recipient. The most powerful of these determines if the "form value" will be sent along with the response. This is discussed in detail in the next section.
This Tcl code was originally written to replace Thomas Boutell's C program. The C program (version 1) required that there be too much involvement by the Webmaster to ensure that all the files were in the right place, and that there were subdirectories and data files to support each instance of the use of the program. While that provided a great deal of security, it also created a nightmare for the Webmaster if there were a number of different users with different form needs. There has since been a new version of the code produced (available at the Web site listed earlier) that eliminates some of those concerns. The premise of this software was to develop a program that moved control back to the forms designer and away from the Webmaster (with some noted exceptions).
Designing The Form
This article won't discuss the art of forms design. It will provide a style guide for a clean form design, and will then provide samples that follow that style guide throughout the text. We'll help you understand how the e-mail program will process variables used in the forms, and special variables that you can use to have a finer granularity of control in the design of the form response.
The form being used in this section is simple. It asks for a name and then a radio button asks if your navigation at the site was easy or not, using a scale from 1 to 7. Most forms aren't that simple. In fact, most form design is complex, and poorly done. Before developing a form, try to think about the information that you want to obtain, and how you would feel answering it. If you have more than 5 to 10 questions, and these are not check box or radio button questions, then you have lost your audience. While I praise the Wall Street Journal for their active involvement on the Web and their electronic publication, the form that they use in registration is a bit winded. Not in the questions, but in the excessive text.
In developing a form, the following style is considered very clean.
comment block (text area)
Name/address and submit button
Here is the sample form that we will be using to describe the form and its elements [italic text embedded in the code is commentary about the forms properties and elements, and is not part of the form itself]:
<TITLE>Article Sample Form</TITLE>
<H1>Sample Form from the Article</H1>
Minimalist. Most browsers will accept the title as the minimum requirement for an HTML document.
Thanks for taking the time to respond to this simple questionnaire.
This information will be used to make the system better meet your needs.
Please respond to the questions in the next section. Once completed,
enter your name and then press the submit button. Thanks for helping out.
That ends the introduction to the form.
<FORM METHOD="POST" ACTION="http://www.site.com/cgi-bin/uncgi/email.tcl">
<input type=hidden name=mailto value=ivler>
<input type=hidden name=msub value="Article Response">
Here we establish uncgi/email.tcl as the form, and the subject and recipient of the completed form. This is going to be turned into an email to user "ivler" with the subject "Article Response".
Please answer the questions by checking the value under it using this scale.
<img src="/giflib/yellowball1.gif">1=strongly disagree <br>
<img src="/giflib/yellowball1.gif">4=neither agree or disagree<br>
<img src="/giflib/yellowball1.gif">7= strongly agree <br>
Directions for responding to the question(s). giflib, in this example, is the library where standard .GIF images are stored. In this case we are using the yellowball images as bullets, and have a gradated colored line as the break between the instructions and the questions that follow.
<li> Navigation at this site was easy.
1 <input name=m1 Type=radio value="1">
2 <input name=m1 Type=radio value="2">
3 <input name=m1 Type=radio value="3">
4 <input name=m1 Type=radio value="4">
5 <input name=m1 Type=radio value="5">
6 <input name=m1 Type=radio value="6">
7 <input name=m1 Type=radio value="7">
A single question. For ease of reading, each number was separated and placed on its own line. When this is displayed, the numbers and selection button will be running from left to right under the question. To run them down the page, end each line with a <br>.
<h2> Suggestions and Comments</h2>
<i>Go ahead, make our day!</i>
<TEXTAREA NAME="content" COLS=55 rows=10>
The comments block. While one may be driven to create an area 24 x 80, please don't. 10 rows at a time are more than enough, and 55 columns provides ample room to keep ideas together.
<input name="name"> Name<p>
To submit the answers, press this button:
<INPUT TYPE="submit" VALUE="Submit Feedback">.<br>
Use the back key to exit, and the reload option to clear and restart.
Did you remember to submit?
Name entry and submission button. I tend to try to make sure that the forms user is aware that they can use the back button on their browser to exit to the screen that they just came from. Others choose to place a "home" link or icon on the page. I also prefer to use the reload feature of the user's browser rather than a button to clear the entry. This ensures that the user won't clear the form in error.
<address>J. M. Ivler - email: firstname.lastname@example.org<br>
© Copyright 1995, Infobahn Xpress, Los Alamitos, CA.
All Rights Reserved.</address>
Author and copyright. Note that the form is very minimal. The fewer items you provide for people accessing the form to press, the greater possibility that they will press what you want. Place items of higher interest and specificity near the top, open areas near the bottom, and email and name info down at the submit button.
In some cases you may want to include legal information (again, I suggest you look at the Wall Street Journal Money and Investing Update -- Registration Page for an example). This information could have been included on a hyperlinked page (<a href="terms-cond">Terms and Conditions - Please Read!</a>) with the submit button saying:
VALUE="I have read and agree to the
terms and conditions">
That would have shortened the page, and made it a bit more comfortable for a reader.
Once the form has been developed consider the following questions. Do you want to put a special subject line on the mail message to allow an e-mail processor like procmail to pre-process the email? If so, you can use the msub value.