FormHandler Manual


Table of Contents:



Required Configuration Fields

Optional Configuration Fields

Appendix A




The key to making your Web site truly interactive is the use of HTML forms which allow you to get input from your visitors. Unfortunately, while a form makes it easy to get input, there is no default mechanism for doing anything with that input. Without a supporting CGI program you can’t check to see if all the required fields were filled in, you can’t store the form data in a database file, you can’t email the data (in a meaningful format) to anyone, and you can’t even tell the visitor that the form data has been submitted. FormHandler takes care of all of these basic tasks while offering some advanced features that allow you to easily use forms to send requested files to a visitor via email create Web-based email interfaces, administer simple mailing lists (send a message to a group of people via email), and much more.


There are already dozens of CGI programs available that are dedicated to processing form input. Therefore, we designed FormHandler to offer a rich variety of features that aren’t available in other programs. So while the program will handle your basic form needs quite well, it will also give you the ability to turn your forms into interactive powerhouses. To give you a more comprehensive overview, a summary of FormHandler’s major features and options are listed below:


Completely Customizable
Before we get into any of the other features, we should point out the FormHandler has been designed to be completely customizable, meaning that you can set it up to use only the features and options you need in precisely the way you want. You also have full control over the look, layout, and content of the information it presents to either you or the visitor.
Ability to Specify Required Fields
FormHandler allows you to specify which fields on your forms must be filled in and will display a message listing the missing fields if a visitor attempts to submit a form without filling in all of the required fields first. This allows you to make sure you’re getting all the information you need.
Confirmation Page Option
After a visitor has successfully submitted a form, FormHandler gives you the option of either redirecting them to an existing URL or displaying a custom confirmation page that is built from a template file.
Administrator Email Notification Option
After a visitor has successfully submitted a form, FormHandler gives you the option of sending an email message to one or more addresses summarizing the contents of the form. This allows you to be notified automatically each time a form is submitted.
Visitor Email Response Option
FormHandler also gives you the option of sending a customized response message to the visitor via email after they have successfully submitted a form. You have full control of the contents of this message; it could contain a summary of their form input or could simply be a note of thanks for filling in the form. Form fields can be embedded into the message wherever you like, allowing you, for example, to refer to the visitor by name within the message.
Visitor Email Attachment Option
You can use FormHandler to set up a Web-based autoresponder that will allow visitors to request that additional information or files be sent to them via email. This information will be attached to the email response message using standard email protocols.
Log File Option
If you would like to keep a database of form submissions instead of or in addition to receiving email notifications, FormHandler includes the ability to create a text-based log file. The contents and format of this log file can be defined using either a template file or a list of form fields to include along with the delimiter to use to separate fields within a record. The program also includes the ability to attach a unique user ID to each record.
Mailing List Capability
FormHandler includes a unique mailing list capability that allows you to combine its email and log file features to manage a mailing list. With this capability you can allow visitors to add themselves to the mailing list and also send messages to the mailing list, all done automatically through a Web-based form interface. An example of how to do this is included later in the chapter, so be sure to check it out.
Ability to Specify Field Sort Order
The order in which form fields are received by a CGI program is relatively unpredictable, so FormHandler allows you to specify an order for use in the missing fields page and the various default field summary pages and messages that FormHandler generates.
Ability to Use Descriptive Field Names
HTML places limitations on what a field name can look like. FormHandler removes this limitation wherever the program needs to display field names (e.g., the missing fields page) by allowing you to associate each field name with a more descriptive name.
Multiple Form Support
FormHandler has been designed in such a way that you can use a single copy of the program to support multiple forms. (This is especially useful if you don’t have easy access to your ISP’s cgi-bin directory.)
Security Options
FormHandler includes several security features that allow you to place limits on which files can be attached to an email message and on who can link their forms to your program.


Configuration Fields:

Required Configuration Fields:
This form field allows you to specify to whom you wish for your form results to be mailed. Most likely you will want to configure this option as a hidden form field with a value equal to that of your e-mail address. To send the form results to multiple users, set recipient equal to those email addresses separated by commas. For Example:

Mailing to yourself if your e-mail address is, would look something like:

<input type=hidden name="recipient" value="">

Mailing to yourself and two friends if their e-mail addresses are and would appear in the HTML form source as:

<input type=hidden name="recipient" value=",,">

You can also check out the cc, bcc and mail_list options located in the Sending E-Mail to Multiple Users section.

Creating a mailing program where people can type in the recipient of the message is also easy. To accomplish this, use a text field similar to:

<input type=text name="recipient" size=30>

Should you wish to simply mail only those people listed in your cc, bcc or mail_list form fields, then you may set recipient to none, like:

<input type=hidden name="recipient" value="none">


Optional Configuration Fields:

Available Configuration Fields:



E-mail related configuration fields:
The subject field will allow you to specify the subject that appears in the e-mail message sent after the form has been filled out. If you do not have this field defined, the script will default to a message subject: WWW Form Submission. For example, to set the message subject to Survey Response, you would include a field in your form similar to:

<input type=hidden name="subject" value="Survey Response">

The same hidden input type should be used on any form you wish to have a standard message subject when it is submitted.

If you are using a form for the purpose of comments or something similar, you may wish to allow the user to input their own subject, much like they would if they were to send you e-mail. To achieve this, place code similar to the following into your HTML source:

Subject: <input type=text name="subject" size=30>

This will appear in your HTML document as:


This form field will allow the user to specify their return e-mail address. If you plan on using any of the auto-reply features of FormHandler, you must include this in your form. The text the user types in will be included in the From: field of the message you receive. Because current HTML and HTTP standards do not require the passing of usernames in non-protected areas, you will have to allow the user to fill this field in themselves and trust that they put in the correct username. The script does minimal checking before sending out the auto-replies, but not all bad addresses can be caught. Most of the time users can be trusted, especially if they want the information they are writing for. To implement this feature into your form, use the following code in the source of your form wherever it fits the layout best:

E-Mail: <input type=text name="email" size=30>

This will appear in your HTML document as:


The realname form field allows the user to input their full name. Although it is not required for any special activities, it is often useful for identification purposes and familiarity when communicating with your users. To implement this on your page, use the following HTML code:

Name: <input type=text name="realname" size=30>

That will turn into:


The fields first_name and last_name can also be used instead of the realname field. Useful if wanting to make your auto-replies more personal.

The first_name field allows a user to input his or her first name for use by the script or so that you can gain a more personal knowledge of who is sending you a message, rather than just their e-mail address. The first_name field can then be later used with the reply_message_template and substituted where appropriate. Examples of this can be found in the reply_message_template. If you wish to implement the first_name field into your form, use HTML code similar to:

First Name: <input type=text name="first_name" size=30>

That will turn into:

First Name:

You can also use the realname field and bypass the use of the first_name and last_name fields.

The last_name field can be used similar to the first_name field and used to complete the username if you choose to use the first_name field. If the realname is used then there is no need to use the first_name and last_name fields. To implement this field into your form, use HTML code similar to the following:

Last Name: <input type=text name="last_name" size=30>

That will turn into:

Last Name:

You can also use the realname field and bypass the use of the first_name and last_name fields.


Modifying generic E-mail and HTML responses without templates:


The field_names form field allows you to specify normal names for your form fields to correspond to those you use inside the form. For instance, many people would rather shorten the form fields inside the form, however when they are returned in the e-mail message, and shown on the screen, they would rather this field name be expanded. If you have form fields for Phone Number, Credit Card, Street Address, City, State and Zip code, but you use form field names such as phone, crc, street, city, st and zip you may not wish for the required form response to return information to the user using these field names, since crc may not be obvious to them that this means Credit Card. Instead, you can use the field_names hidden variable, which would look something like this if you were using the example above:

<input type=hidden name="field_names" value="phone=Phone Number&crc=Credit Card&street=Street Address&city=City&st=State&zip=Zip">

The fields you specify field names for will need to be specified in the value of the field_names form field, in a special way. All name-value pairs must be separated by a & sign and the name and value within each pair must be separated by a =.


The sort field allows you to choose the order in which you wish for your variables to appear in the E-mail that FormHandler generates. You can choose to have the fields sorted alphabetically or specify a set order in which you want the fields to appear in your mail message. By leaving this field out, the order will simply default to the order in which the browsers sends the information to the script (which isn't always the exact same order they appeared in the form.) When sorting by a set order of fields, you should include the phrase "order:" as the first part of your value for the sort field, and then follow that with the field names you want to be listed in the e-mail message, separated by commas. For example, if you have a form with the fields phone, company, address1, address2, state, city, and zip and you want these returned to you in the e-mail in that specific order, you would use the following field in the source of your HTML document:

<input type=hidden name="sort" value="order:phone,company,address1,address2,state,city,zip">

If you would rather have these fields sorted alphabetically in your E-Mail message that FormHandler generate, you can specify the following form field in the source of your HTML document:

<input type=hidden name="sort" value="alphabetic">

You can also allow the form results to simply come back to you mail in the order your browser submits them. This is usually the order in which they appear in your HTML source, however with larger forms, browsers sometimes submit the fields in different orders. In these situations, it may be best to use the order: command in the sort field.


The print_config form field allows you to specify which of the configuration variables you would like to have printed in your e-mail message. By default, no configuration fields are printed to your e-mail. This is because the important configuration fields, like email, subject, etc... are included in the header of the message. However some users have asked for this option so they can have these fields printed in the body of the message. The configuration fields that you wish to have printed should be in the value attribute of your input tag separated by commas. For example, if you wanted to print the email and realname fields in your form into your E-Mail message, you would place the following code into the source of your HTML form document:

<input type=hidden name="print_config" value="email,realname">


The env_report field allows you to have specified environment variables included in the e-mail message you receive after a user has filled out your form. Useful if you wish to know what browser they were using, what domain they were coming from or any other attributes associated with environment variables. The following is a short list of valid environment variables that might be useful:
REMOTE_HOST - Sends the hostname making a request.
REMOTE_ADDR - Sends the IP address of the remote host making the request.
REMOTE_USER - If server supports authentication and script is protected, this is the username they have authenticated as. *This is not usually set.*
HTTP_USER_AGENT - The browser the client is using to submit the form. General format for the HTTP_USER_AGENT is software/version library/version

These are a few of the most useful environment variables, however a complete list can be found at: NCSA: CGI Environment Variables.


The redirect field is used to send users to a pre-made web page if the form they submitted passed all of the required fields and everything worked properly. This bypasses the generic response that will be sent out to your users and allows you to give them a customized response. If the page you wanted to send users to after they had submitted your form was located at, you would place the following text into your HTML source:

<input type=hidden name="redirect" value="">

NOTE: Use of the redirect field above, means that you will not have to define any of the other Returned HTML Form Results Page Configuration Variables. Otherwise, use the variables below to continue to tailor the output of the generic form response file.


The title form field allows you to specify the title and heading of the resulting generic form response. Otherwise, you can specify the title of your resulting form response by copying the code below into your HTML form source (replacing My Title Here with the title you wish to use):

<input type=hidden name="title" value="My Title Here">


Requiring Form Fields:
The required form fields specified the fields of a form that you wish to force users to fill in. If a user does not fill in a required form field, an error page will be generated and send to users. It will explain what fields need to be filled in and present them with a link back to the form. To use this form field, you will need to place the names of the required form fields into the value of this form field. The names must be separated by commas. For instance, if you wanted to require a user to fill in the fields: realname email, phone, city and state so that you would have a means of contacting them after they send a message, you place the following hidden field somewhere in your form HTML source:

<input type=hidden name="required" value="realname,email,phone,city,zip">

If any of these form fields were not filled in, an error page would be generated, letting the user know what went wrong.



Modifying generic E-mail and HTML responses with templates:

FormHandler comes with powerful template parsing capability. This allows you to create static pages, with special "keys" for the script to recognize and replace with values. You can create a template for several purposes, including: The way your e-mail looks, the look of success and error HTML pages sent to the user filling out the form, and the look of reply messages.

To do this, simply create the template file and whenever you want FormHandler to replace this message with a value from the form, simply put the name of the field inside "<<" and ">>". For instance, if you want to start off your reply message with "Hello User!," where User is the first name defined in the first_name field of the form, you would put the following on the first line in your reply_message_template file:

	Hello <<first_name>>!,

Then, when FormHandler parses this template, it will replace <<first_name>> with what the user filled in in the first_name. Other fields, for specific purposes are automatically created by the script.

Templates can be used for Error Messages sent to the user in HTML if they forget to fill in a required field, Success Messages sent to the user after they have submitted the form with no errors and FormHandler has sent you a message and them a message, E-Mail sent to you after the user has filled out the form and for Auto-Reply E-Mail sent to the user after they have successfully filled out the form.

If you want to use any Environment variables in any of the templates, simple include them like a normal form field: <<REMOTE_HOST>>. env_report is only needed if you don't use templates. With templates, you can use all form fields, configuration fields and environment variables in the parsing of the template.

Because you may have many lines in your template, which you only want to have printed should one of the form fields in the line have been filled in, FormHandler has a way for lines not to be posted if nothing is changed. If you have a line such as:

     Quantity of Cherries Ordered: <<quantity_cherries>>

in your template and you only want that to be printed if they ordered cherries, you would write the line into your template as:

     0:Quantity of Cherries Ordered: <<quantity_cherries>>

FormHandler will then not print any line that begins with 0: (a zero followed by a colon) if no substitution for a form value was done to that line. This saves you from having to look at a lot of blank form fields if the user did not submit any values for them.

The error_html_template is a template you can create to send to users if they have not filled out their form. The field error_fields will automatically be created by the script. This is so you can specify in the HTML a spot for the error_fields to be seen and explain to a user what they need to go back and fill in. If you have created a file called error_template.html and wish to call it as your default template for missing required field errors, simply put the following line in your form source:

<input type=hidden name="error_html_template" value="/path/to/error_template.html">

Keep in mind that the location of your error_html_template HTML file, MUST be specified with a system path. A URL notation in the value of this field WILL NOT WORK.

Here is an example of what a sample error_template.html might look like:

   <title>FormHandler Error</title>
 <body bgcolor=#FFFFFF text=#000000>
   <h1>FormHandler Error</h1>
You forgot to fill in the following fields correctly:<p>
Please return to the form and continue to fill it out.  Thanks.
The success_html_template form field contains the path to the template that will be returned to the user should they correctly fill out the form and it has been submitted. It will be parsed just like error_html_template, except there will be no error_fields form field.


Although the email_template will be parsed just like the other templates, keep in mind that no headers are needed. The email template will be used as the body of your message, and the headers will be created through the other configuration fields such as subject and recipient.


FormHandler Auto-Reply:

This template behaves very similarly to the email_template. More information on using this template can be found in the Using Templates section. The reply_message_template will then be used as the boy of the message and will accompany any reply_message_attachments you specify.


The reply_message_attach form field specifies the system location of the file you wish to be attached. At the beginning of the value of this field, you will also have to specify whether you want it to be appended as plain text, uuencoded or a Base64 MIME attached file. So if you have a binary file, you will need to specify the uuencode type or MIME type and if it is a plain text file you can choose to send it either of the three ways.
If you wish to attach multiple files, simply string the filenames and the encoding separated by commas. For instance, if you wanted to the text file /dnshome/, your HTML might look like:

<input type=hidden name="reply_message_attach" value="text:/dnshome/">

For security purposes, FormHandler will not allow you to attach files in the /etc directory of your server. This is where the passwd file and other important files are located. If you wished however, to allow the user to choose what files they wished to have sent to them in a series of checkboxes or radio buttons, you could write sample code like:

<input type=checkbox name="reply_message_attach" value="text:/dnshome/domain.comf/htdocs/README"> README File For Binary Program
<input type=checkbox name="reply_message_attach" value="uuencode:/dnshome/domain.comf/htdocs/"> Binary Program as Uuencoded File. <input type=checkbox name="reply_message_attach" value="mime:/dnshome/domain.comf/htdocs/image.gif"> An Image attached with MIME and base64.

If the user checks multiple entries, the strings will be put together by a comma in the FormHandler program and multiple requested files will be sent.


The reply_message_subject form field specifies the subject of the reply message. By default it will be set to 'FormHandler Auto Reply', but this can be changed with a simple hidden field such as:

<input type=hidden name="reply_message_subject" value="New Subject Here">


This specifies the e-mail address and name of who is sending the auto-reply, should you wish for it to appear different than the default value (what is supplied in recipient). Make sure you supply it as a valid email address, such as:

Your Name <> (Your Name)

The bottom two are recommended in the HTML, as the top one can mess up the HTML coding with the <'s and >'s.


Logging FormHandler Results:

Version 2.0 of FormHandler now includes a logging procedure to create a text database. All form responses can be logged to a text database file, and FormHandler allows you to specify which fields to record (or which records not to record if that is easier), the delimiter you want to use, the filename of the log file and an optional user id for special purposes. If you plan on using the logging feature of FormHandler, the log_filename MUST be set as well as either log_template or log_fields.


The log_filename form field is a required field if you wish to use the database logging procedure built into FormHandler. This specifies the server path to the filename you wish to have FormHandler log the information to. This field should not be represented as a URL, but rather a system path. To determine the system path, switch to the directory that contains your log file (for example we will name it FormHandler.log, however you can choose any name you wish) and type pwd, like in the example below (The typewriter font specifies what you type in, whereas the italic font shows what is returned to your screen):

% pwd

This tells you the system path to your log file, and all you have to do now is tack on the FormHandler.log filename. So the field you would include in your HTML source would look similar to:

<input type=hidden name="log_filename" value="/dnshome/">

The log_template form field allows you to specify a file from which one line will be read. This line will then be used as the template in constructing the entry for your log file. You can use any of the configuration fields in the log including environment variables without having to set them in env_report. For a complete use of the fields you can use in your form, refer to Appendix A: Configuration Fields to see those that are automatically designated by the script or that you can specify to be included in the configuration array. For more information on templates in general, check out the Using Templates section of this README file. Below is an example that could be used in real life.

Let's say you wish to have a form, where if the user clicks a button, it creates an entry in your log file showing when the user visited your page, their host, and a one line comment they can leave about your page. The form you would set up should look something like:

<form method=POST action="/cgi-sys/FormHandler.cgi">
Comments: <input type=text name="comments" size=50 maxlength=50>

<!-- If you wish to use the templates and create a special log design, use following line of code. -->

<input type=hidden name="log_template" value="/dnshome/">

<!-- Otherwise, if you wish to use generic form logging, use: -->

<input type=hidden name="log_fields" value="REMOTE_HOST,log_date,comments">

<input type=submit value="Sign Log"> <input type=reset>

The log_fields form field allows you to specify those field names which you wish to log. For instance, you may not wish to log all of the form fields that appear in your document, since the only ones you want to have in the log are email, realname, and phone so that you have ways of contacting all of the users who have sent you messages using FormHandler. You would specify the names of these form fields in the value attribute to the log_fields form field by separating the names of the form fields by a comma. The HTML source you would use to specify these three fields to be logged is:

<input type=hidden name="log_fields" value="email,realname,phone">

NOTE: This form field is required because should any of these fields be left blank, the FormHandler program will still insert the field (with no value) into the database. This is so other database accessing programs can access your database more easily. Even if you want all of the fields logged, you are still going to have to input each one into this field value, because not all browsers will return the fields to the FormHandler program in the same order. When working with databases, an unorganized database with fields in different locations is more or less useless, which is why this form field is enforced. No logging will take place if it is not filled in.

When importing the database file into many external database programs, such as Excel, Lotus 123, etc. users must have a database with the records all separated by a common delimiter. For most standard databases, this delimiter is a colon (:). However, when using the internet and dealing with URLS and such, colons often become ineffective because people use them in their writing and URLS. So if you are having a custom database program made for this database or using it for the sole purpose of logging stuff so you can go back and see it, you can leave this form field out. The delimiter will default to two pipes and each field in your database will be separated with ||. This is useful because most often users will not find the need to type two |'s in a row. If however you are dealing with a database program that requires a special delimiter, you can supply one in this form field. As I said, the colon is the most commonly used one, and therefore, to specify a colon delimited text database, you would use the following form field in the source of your web page:

<input type=hidden name="log_delimiter" value=":">

If this field is left out, a tab will be used as default. Most likely you will just want to use a tab delimited file as most database programs can read a tab delimited file.

The log_uid special field will create a unique user ID for each user filling out the form. This will take the form of a number that is incremented every time a new entry is added to the log file. This unique user ID can be used for things such as database programs, contest numbers, etc... For this field to be recognized, however, the value of it must be "yes".

To incorporate this into your form, you would put the following in the source of your HTML form:

<input type=hidden name="log_uid" value="yes">


Sending Messages to Multiple Recipients:

The cc form field will send a carbon copy of the message sent to recipient to the specified users. The users can be specified in the actual form field or a reference to an external file can be made and the FormHandler script will fetch the file, extract the e-mail addresses and send carbon copies to those users. The addresses in the external file should be one per line or several on a line separated by commas. If you choose to include the e-mail addresses of those you are sending carbon copies to in your FormHandler source, simply separate the addresses with commas if there is more than one.
To specify a list of addresses in the source of FormHandler, use a form field such as:

<input type=hidden name="cc" value=",,etc">

To specify a file for FormHandler to get the user's names form (recommended if copying message to over 5 or 10 users), use a command such as:

<input type=hidden name="cc" value="file:/path/to/cc_file">
The bcc form field on FormHandler will do almost the exact same thing as cc however it will send blind carbon copies to each user, meaning that the users can not see who else has been sent this message. You can specify the users in the same way you would for regular carbon copies, however don't forget to change the field name to bcc instead of cc.
Although this function of FormHandler requires that your mail program be called once for each user, causing it to sometimes burden down the server, it is useful if you wish to send a separate copy of the message sent to recipient to multiple persons. Once again, the addresses of these users who will be receiving the copies of the message can be specified in the same way as they are for cc. Don't forget to change the field name to mail_list instead of cc though. When using the mail list addresses in a template to specify who the message should be sent to, the mail_list_user will be defined and should be used, rather than the mail_list field. So in the email_template, the first line should look like:

To: <<mail_list_user>>


Appendix A:

The following is a table of defined values of %CONFIG, which can be used in the template files and the conditions under which they are set.



Conditions Under which Set

recipient This field specifies the user to whom the results of the form should be sent. recipient form field contains a valid e-mail address.
email The email field specifies the address of the user filling out the form. If the email form field contains a valid e-mail address.
realname Contains remote user's full name. If realname has been filled in.
first_name Meant to contain remote user's first name. Exists if the first_name form field has been filled out in the form.
last_name Meant to contain remote user's last name. Exists if the last_name form field has been filled out.
subject Contains the subject of the message. Exists if subject form field is filled in.
You can specify for any environment variables you think might be filled to be available for use in templates. These will be automatically available to you with templates.
log_uid This will be available to the log_template so you can give each user a unique id. The filename you give this field in your form will be replaced with the number. You can tell FormHandler you wish to use this field by giving the path to a log_uid file in the log_uid form field.
cc Contains the list of users you wish to send your carbon copies to. Just place this template field at the top of your email_template as defined in the cc description. Defined if you have specified a file of cc users or given a list of them in your form.
bcc Similar to cc except contains list of users to whom you are planning to send a blind carbon copy. Defined if you have specified a file of cc users or given a list of them in your form.
mail_list_user This contains the email address of the current mail_list user. Used in the header of the email_template a separate message will be sent to each mail_list_user. Defined if you have specified a file of mail_list users or given a list of them in your form.
date Contains a lengthy date in the form of Day_Name, Month Day_Number, Year at Hour:Minutes:Seconds Defined automatically
log_date A shorter date format for use in logs. Looks like: HH:MM:SS DD/MM/YY (Hour:Minute:Second Day/Month/Year) Defined automatically
All Non-Config All other fields which are not configuration fields are defined for use. So if you have a field named phone, that is defined and just use <<phone>> in your template and FormHandler will print the value of the phone field. Defined automatically



This script is part of the CGI/Perl Cookbook by Craig Patchett and Matthew Wright. The script is only available to users who have bought the book. Esosoft Corporation has bought this book, however you are not able to copy the FormHandler script from our cgi system directory to your file area or take it to another web hosting provider. You are only allowed to use the script if you are a customer of Esosoft!

Last Updated: 13 May 2001
Copyright by Esosoft Corporation 1996-2001
All Rights Reserved.