|
Formhandler
CGI Program
Table of Contents:
1. What does
the Formhandler program do?
2. Understanding
and Creating Templates
3. Including Fields
in Your Form
4. Examples
5. Troubleshooting
1.
What does the Formhandler program do?
The Formhandler program helps you manage
forms on the web. Forms are an excellent way to get
input from the users of your website and this program has
the ability to process their input in a variety of ways. Here
are the major features this program offers:
Customizable: You
are free to use any or all of its functions and can control
the presentation
and content of the webpages, emails and files.
Email notification: Once the form is
submitted, you can have a summary of the information sent
to one or more email addresses.
Email response: You have the option of
sending an automatic email message to visitors, which can
either thank them for filling out your form, or give them
a summary of what they posted.
Confirmation message: After submitting
the form, the visitor can either be sent to another URL
or receive a customized confirmation message that the form
has been sent.
Required fields: You can specify
which fields must be filled in on the form, and an error
message listing all of the missing fields will be displayed
if the visitor has not filled out the form properly.
Descriptive fields names: Allows
you to assign more descriptive names for each field name.
Log file: The visitor's
information can also be transferred into a text file
for uploading to a
word processor, spreadsheet or database. The format
of this text file is customizable and unique IDs can be
assigned to each record.
The Formhandler program is quite flexible:
you can use any combination of the above features in your
form. Another
advantage is that you don't have to edit the program code
or have a cgi-bin in order to use it. Yet it's important
to note that this program will only work if it is
being posted from an ag.arizona.edu URL. (See
information below about obtaining this program for another
server.)
The following instructions for this program
will assume that you have a general knowledge of HTML and
know how to
create forms. If you are not that familiar with creating
forms or need a better understanding of the basics, you should
begin by looking at WebCom's
Forms Tutorial site for more information or read about
forms in various HTML books.
[TOP]
2.
Understanding and Creating Templates:
This program uses templates to format
the email messages, HTML documents and log files that are
required with the form. For example, when you want
the information the visitor has entered into the form to
be sent to you, you must create a template file to control
the look and contents of that message. Creating these
files is fairly simple: the text will appear just as
you have typed it, except when field information is used. When
you want the value of that field to appear instead, you simply
enclose the field name in double arrow brackets.
For example, let's say you want to refer
to a person's email address as they have entered it in a
field called "email" within the form. You
can use <<email>> and this will be replaced with
their actual email address. If you are confused, I
have provided the following sample templates:
HTML templates: these files should be written
and saved as HTML files.
Text templates: these are text files
and can be saved as .txt.
- email_template: this
file controls the content of the email message that is
sent to the form owner.
- reply_message_template: this
file controls the content of a reply message that may be
sent to the visitor who filled out the form.
- log_template: this
is the format of the logfile that stores the information
from the form into a text file for later use.
I will show you later how to refer to these files within
your form, but it's important to refer
to the location of these files using the absolute directory
on the server, not the URL!
[TOP]
3. Including
Fields in Your Form: (The
template references are highlighted and linked)
Posting your form: You must include the
line below in your form in order for the program to work
properly:
<FORM ACTION="/cgi-bin/formhandler/formhandler.cgi" METHOD="POST">
Email Notification Fields: Use these fields
when you want a summary of the information sent to you through
email:
Field Description: |
How to Reference
in Form: |
| recipient:
This field is required! It tells the program where to email
the results. If you do not refer to an email_template
file, then you will get a blank email message. |
<INPUT TYPE="hidden" NAME="recipient" VALUE="you@somewhere.com">
Note: If, for some reason, you
don't want to receive an email, you can set VALUE="none" |
| cc: results can be sent
to more than one person. |
<INPUT TYPE="hidden" NAME="cc" VALUE="someone@somewhere.com,somebody@somewhere.com"> |
| bcc: same as cc, except
there is no indication in the message that it was sent
to multiple people. |
<INPUT TYPE="hidden" NAME="bcc" VALUE="someone@somewhere.com,somebody@somewhere.com"> |
| subject: puts the subject
in the email message. |
<INPUT TYPE="hidden" NAME="subject" VALUE="Sample
Form"> |
| email_template: the
location of a text file that contains a template for
the email being sent to the owner. |
<INPUT TYPE="hidden" NAME="email_template" VALUE="/your/absolute/path/email.txt"> |
Email Response Fields: Use
these fields when you want to send an automatic message
to the
person who filled out your form:
Field Description: |
How to Reference
in Form: |
| reply_message_template: the
location of a text file that contains a template for
the email being sent to the visitor. |
<INPUT TYPE="hidden" NAME="reply_message_template" VALUE="/your/absolute/path/reply.txt"> |
| reply_message_from: contains
the email address of the person who sent the reply message.
(usually same email as recipient) |
<INPUT TYPE="hidden" NAME="reply_message_from" VALUE="Sample
Form (you@somewhere.com)"> |
General Fields: These
are optional fields that are recommended for customizing
your form:
Field Description: |
How to Reference
in Form: |
| success_html_template:
the html page that appears when the visitor has successfully
sent the form. |
<INPUT TYPE="hidden" NAME="success_html_template" VALUE="/your/absolute/path/success.html">
Note: If you want to redirect the
visitor to an already existing webpage (eg. your
homepage), put that information into the VALUE field
instead of the template information. For example,
VALUE="/your/absolute/path/index.html". |
| required: contains the
field names that the visitor must fill in to send the
information on the form successfully, otherwise an error_html_template
will appear. |
<INPUT TYPE="hidden" NAME="required" VALUE="your
field names (ex: name,email,feedback)"> |
| error_html_template:
the html page that appears when the visitor does not
fill in all of the required fields. |
<INPUT TYPE="hidden" NAME="error_html_template" VALUE="/your/absolute/path/error.html"> |
| field_names: this is a
way to substitute descriptive names, instead of the actual
field names on documents like the error_html_template. |
<INPUT TYPE="hidden" NAME="field_names" VALUE="first_name=First
Name&dept=Department"> |
Logfile Fields: These
fields are only necessary if you want to put the form information
into
a log file.
Field Description: |
How to Reference
in Form: |
| *log_filename:
the location of the logfile where information from the
form will be added. Initially, it will be blank. |
<INPUT TYPE="hidden" NAME="log_filename" VALUE="/your/server/directory/logfile.txt"> |
| log_template:
the location of the template file that will control the
format of the logfile. |
<INPUT TYPE="hidden" NAME="log_template" VALUE="/your/absolute/path/logtemplate.txt"> |
| *log_uid:
create this blank file if you wish to put a unique number
next to each entry in the logfile. |
<INPUT TYPE="hidden" NAME="log_uid" VALUE="/your/server/directory/uid.txt"> |
*Note: These
two log-related files should be created as blank files. Also, these
files should have write permissions for the world, in order
for the program to update them. To do this, type the
following in the directory where the files are located: 'chmod
777 logfile.txt' and 'chmod 777 uid.txt'.
[TOP]
4.
Examples:
Choose one of the following for a detailed example of how
to create the form:
- Feedback: A
simple form that requests feedback from a visitor. The
results are emailed to the owner and the visitor is sent
an automatic email message as thanks for filling out
the form.
- Logfile: This
example requests personal information from the visitor
(like name, phone number, etc.). The results are
emailed to the owner and also added to a comma-delimited
ASCII file that will later be uploaded to a database.
[TOP]
5. Troubleshooting:
If you are
receiving error messages or the form is not working properly,
check the following common problems and solutions listed
below:
Error
Messages:
a. Can't
open /your/file/here/ (No such file or directory).
This error occurs when you have not referenced
the file properly. You must use the absolute path of your
file, as it exists on the server. The most common
mistake is for people to refer to the template documents
with a URL.
b. Can't open /your/file/here/ (Permission
denied).
This error will appear if you do not have
the permissions set properly on your file. All of the template files
should be readable by the world. You can type in
'chmod 755 yourfile.txt' to take care of this problem. If
you are getting this error for the log_filename or log_uid
files, the permissions need to be world writeable as well. To
do this use 'chmod 777 file.txt'.
c. recipient (invalid address
format)
If your error_html_template page appears
with the above line listed as an error, the program is
referring to the
recipient field, which contains the email address of the
person who will receive the form results. Unfortunately,
this field cannot be left out so you must include the recipient
field in your form. If you do not refer to an email_template
file, then you will receive only a blank email message
when a form is sent.
Other Problems:
a. I am getting a blank email message.
The field that controls the email message
is email_template. If
you did not refer to this file properly or did not put
this field in your form, then you will receive a blank
message. The most common cause of this problem is
the reference to the email_template file, and it should
look like the following: <INPUT TYPE="hidden" NAME="email_template" VALUE="/your/absolute/path/email.txt">. In
the value reference, you must use the absolute path of
this page on the server, not any form of a URL.
b. I am using the logfile option of the form,
but I don't know how to get the file onto my computer.
In order to retrieve a copy
of the log_filename file onto your computer, you must
download the file through
FTP. Once you download this file, you can erase the
old file and create a new blank one. If you don't
remove the old file, then the new records will continue
to be added to the end of the file, but this may result
in redundant records the next time it is downloaded.
If you encounter other errors or problems
not mentioned in the Troubleshooting section, feel free
to send your questions
to lab@cals.arizona.edu.
[TOP]
For more information
about this program:
The source and instructions for this program
were included in the following book:
CGI/Perl Cookbook
Authors: Craig Patchett and Matthew Wright
Wiley Computer Publishing
October, 1997
http://www.cgi-perl.com/
|
Quick
Links
