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 cant check to see if all the required fields were filled in, you cant store the form data in a database file, you cant email the data (in a meaningful format) to anyone, and you cant 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 arent 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 FormHandlers major features and options are listed below:
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 youre 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 dont have easy access to your ISPs cgi-bin directory.)
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.
|Required Configuration Fields:|
Available Configuration Fields:
|E-mail related configuration fields:|
|Modifying generic E-mail and HTML responses without templates:|
|Requiring Form Fields:|
|Modifying generic E-mail and HTML responses with
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:
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.
|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):
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"
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">
<!-- 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/domain.com/logs/log_template">
<!-- 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
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">
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="email@example.com,firstname.lastname@example.org,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:
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.|
|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.