***************************************************************************
*****                           FORMMAIL.PL                           *****
***************************************************************************

Originally coded by Matt Wright from Matt's Script Archives.  Highly 
modified by Speedsoft.com for additional storage and sending options.

The formmail.pl CGI is used to take a web-form submission and process it in
one of two ways:

1) Have the form contents emailed to a recipient (you).
2) Have the form contents stored to a database file or files.

You can opt to have one or both of these methods used with no problem. In
other words you can have the form submission mailed to you and saved to 
a database.  There are two options for saving the data to a database, only
one of them may be used.

No modification is required to the formmail.pl script.  All options are set
in the actual HTML form fields, some user entered, others in hidden form
fields. (e.g. <input type=hidden name="name" value="widget">)
One formmail.pl script can be used for multiple formmail HTML pages since
all options are set in the actuall HTML page.  Please note that all form
field names must not have any spaces in them (i.e. <input name="Customer Address">
is wrong, it should be <input name="Customer_Address">).  If you have a
space in the name of the field, it will not be parsed correctly.

Depending upon which way you want the data sent or stored, you must define
certain form fields to specify your options.  Many of these fields are
provided in the included "formmail.html" file which shows an example of how
to create your formmail page.

All form fields must be contained between your <form> tags in the HTML page
like so:
<form method=POST action="/cgi-bin/formmail.pl">
... form tags as explained below ...
<input type=submit value="Submit Form">
</form>

******************************************************************************
*** 1. Email Form Submission to a Recipient
******************************************************************************

	For this to happen you need to define two form fields and a text file
	which defines how you want the data sent.

REQUIRED
   1. "recipient" - email address to which the form's contents 
	are to be mailed (most likely you).
	i.e. <input type=hidden name="recipient" value="bob@widget.com">
   2. "textform" - text file containing the format for the mail.
	See the included "example.txt" file, also see the section below
	explaining the "textform" file format!  Be sure to include the entire
	path to the file along with the file name.
	i.e. <input type=hidden name="textform"
		value="/usr/local/etc/httpd/vhosts/bob/form.txt">

HIGHLY SUGGESTED
   3. "email" - it is highly suggested that you require the sender to 
	provide a return email address in this form field. If this field
	is not provided a return email address of the "recipient" will be
	specified to keep bounced emails from bouncing to postmaster.
	i.e. <input type=text name="email" size=40 maxlength=100>
	(see section 4.1 to see how to "require" a form field)

******************************************************************************
*** 2. Save Form Contents to a Single Database File
******************************************************************************

	Note: all carriage returns will be replaced with spaces, the data
	file is stored in single line entries.

REQUIRED
   1. "datafile" - the file to store the data to including full path name.
	i.e. <input type=hidden name="datafile"
	value="/usr/local/etc/httpd/vhosts/bob/datafile.dat">
   2. "dataorder" - a list of the data you want saved to the datafile.
	It will be saved in the same order you have listed here.
	i.e. <input type=hidden name="dataorder"
	value="name,address,city,state,zip,age,color,comments">

OPTIONAL
   3. "separator" - the character used to seperate the fields within the
	database file.  If you want a tab-delimited file, use "\t". 
	(default separator: "|")
	i.e. <input type=hidden name="separator" value=",">

******************************************************************************
*** 3. Save Form Contents to Multiple Files in a Subdirectory
******************************************************************************

	With this setup, you can manage (view and delete) the files with
	the accompanying "backroom.pl" script. Details of this are included
	in the backroom.nfo file

REQUIRED
   1. "file_dir" - name of directory to contain the form submission files.
	Full pathname required.
	i.e. <input type=hidden name="file_dir"
	value="/usr/local/etc/httpd/vhosts/bob/formdata">

******************************************************************************
*** 4. Optional (Helpful) Form Fields
******************************************************************************

   1. Your own list of required fields
	List any other fields you want to be required in your HTML form
	separated by a comma in a field called "required".
	i.e. <input type=hidden name="required" value="subject,message,age">

   2. "redirect" - a URL for an optional return response page.
	(must be a full URL! with http:// , etc.)
	i.e. <input type=hidden name="redirect"
		value="http://www.widget.com/returnpage.html">

* this is cool! ->
   3. "parsed_redirect" - a URL for an optional return response page
	which is parsed for variable names just like the text email form.
	(see the section below on creating the textform file).
	This file must exist in your account and must contain the full
	path along with the filename.
	i.e. <input type=hidden name="parsed_redirect"
		value="/usr/local/etc/httpd/vhosts/bob/returnpage.html">

   4. "subject" - the subject line of the email if sending contents via email.
	(default: "WWW Form Submission")
	i.e. <input type=hidden name="subject"
		value="Widget.com Sales Form Submission">

   5. "title" - title for the response HTML page if not using a redirect.
	(default: "Thank You for Your Submission")
	i.e. <input type=hidden name="subject"
		value="Thanks for Submitting Information to Widget.com!">

   6. "return_link_url" - for a "Back to this Page" link on the response page.

   7. "return_link_title" - title for the return_link_url link.

   8. "realname" - Sender's real name for the email response

   9. "test" - Include this field as a checkbox and you can test
      the form without actually mailing it off or saving the 
      data to file.
      (e.g. <input type=checkbox name=test>)

******************************************************************************
*** 5. Error and response page attributes
******************************************************************************
	You can customize the automated response pages (if not using a 
	redirect) with these <BODY> color and background attributes.
	i.e. <input type=hidden name="bgcolor" value="black">

   1. bgcolor - color name or HEX value (i.e. #0066ff)
   2. background - full URL! (i.e. http://www.widget.com/images/bg.gif)
   3. text_color - color name or HEX value (i.e. #0066ff)
   4. link_color - color name or HEX value (i.e. #0066ff)
   5. alink_color - color name or HEX value (i.e. #0066ff)
   6. vlink_color - color name or HEX value (i.e. #0066ff)

******************************************************************************
*** 6. Text Form Configuration
******************************************************************************

You will have to create a text file which is layed out exactly like you want
the mail to be sent to you or if you are using the "Save Form to Multiple
Files" option.  The text file is specified in a hidden form field named
"textform" (i.e. <input type=hidden name="textform"
value="/usr/local/etc/httpd/vhosts/bob/myform.txt">)
Any text located between square brackets ([]) will be replaced with the
corresponding field from your form.  Be careful to note that this IS case
sensitive, meaning "Name" is not the same as "name".

Cool new feature! ->
If you have a text located between square brackets AND exclamation points,
it will be deemed "sensitive" information, meaning it will not be included in
an email but WILL be included in the database files.  Like so:
[!CreditCardNumber!]

This would be helpful to receive an email notification of a submission, but
yet keep the sensitive information just on the server for later retrieval
securely.

Here is an example (this is included with the files and named example.txt):
---------------------------------
Name: [name]
Address: 
[address]
[city], [state] [zip]

Favorite Color: [color]
Age: [age]

Credit Card Number: [!CCNumber!]
Credit Card Exp. Date: [!CCExpDate!]
---------------------------------
Here is the HTML form page which might go with this:

<html><head><title>User Info Page</title></head>
<body bgcolor="white" text="black">
Please fill out the following information:<P>
<form action="/cgi-bin/formmail.pl" method=post>
<input type=hidden name="required" value="name,address,city,state,zip">
<input type=hidden name="recipient" value="yourname@yourdomain.com">
<input type=hidden name="textform"
value="/usr/local/etc/httpd/vhosts/yourdirectoryname/example.txt">
Your Email Address: <input type=text name="email"><BR>
Your Name: <input type=text name="email"><BR>
Age: <input type=text name="age"><BR>
Address: <input type=text name="address"><BR>
City: <input type=text name="city"><BR>
State: <input type=text name="state"><BR>
Zip Code: <input type=text name="zip"><BR>
What is your favorite color?
<select name="color">
<option value="red">red
<option value="blue">blue
<option value="green">green
</select><p>
Credit Card Number: <input type=text size=40 name="CCNumber"><BR>
Credit Card Exp. Date: <input type=text size=40 name="CCExpDate"><P>
Enter any other comments here:<BR>
<textarea name="comments" cols=50 rows=4></textarea><p>
<input type=checkbox name="test"> Check here to test this without
sending it off.<P>
<input type=submit value="Send the Mail">
<input type=reset value="Clear the Fields">
</form>
</body></html>

******************************************************************************
*** 7. Optional Environment variables in Text Form
******************************************************************************
This allows you to have Environment variables included in the textform file.
This is useful if you wish to know what browser the submitter was using, what
domain they were coming from or any other attributes associated with
environment variables.  Here are a few examples.  For a complete listing,
see http://www.speedsoft.com/cgi-bin/envhtml.pl

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.*
REMOTE_IDENT	- If HTTP server supports RFC 931 identification, then 
		  this variable will be set to the remote user name 
		  retrieved from the server. *This is not usually set.*
HTTP_USER_AGENT	- The browser the client is using to send the request.  
		  General format: software/version library/version
DATESTAMP       - A date including day of the week, date, and time of the submission

Syntax:

If you wanted to find the remote host and browser sending the request, 
you would put the following into your text form file:
------------------------------------------------
Remote Host Was: [REMOTE_HOST]
They were using the browser: [HTTP_USER_AGENT]
------------------------------------------------