######################################################
# Form Mailer User and Programmer Guide
#
# Copyright 2000 Shawn Ewald <shawn@wilshire.net>
######################################################

What is Form Mailer?

Form Mailer is a perl module that allows the easy handling
of html mail forms. Form Mailer can also be used by programmers
who wish to provide mail form handling functionality in their own
custom programs.

Form Mailer Features:

* Can be used with any html mail form, even currently existing
  ones (with slight modification).
* Uses no external programs , communicates directly with your
  SMTP server.
* Generation of custom mail messages from a template file.
* Access logging capability.

======================================================
Form Mailer User's Guide

To use Form_Mailer as a e-mail handler for HTML forms,
you need to follow the following simple process.

1) Create your HTML form and name the form fields exactly
as you would like them to appear in your e-mail message.

Example:

You have a form field in which you would like
visitor to provide their full name and you want to
identify this field as "Full Name" in the generated
e-mail message. Simply, name the form field "Full Name"
like so:

<input type="text" NAME="Full Name">

The following is a sample form and an explanation of
some special tags that are used by Form_Mailer:

<form method="post" action="formmailer.pl">
   
   <!-- REQUIRED TAGS -->
   <input type="hidden" name="subject" value="This is a test.">
   <input type="hidden" name="to-email" value="someone@somewhere.org">
   <input type="hidden" name="next-url" value="http://www.somewhere.org">
   
   <!-- OPTIONAL TAGS -->
   <input type="hidden" name="logfile" value="mylog.txt">
   <input type="hidden" name="template" value="template.txt">
   
   <!-- YOUR FORM FIELDS -->
      <input type="text" name="Full Name">
      <input type="text" name="from-email">
      <input type="text" name="Website">

</form>

Tag: subject
Explanation: This tag defines the subject line of the e-mail
message.

Tag: to-email
Explanation:  This tag defines where the e-mail is to be sent
the to-email tag is required.

Tag: next-url
Explanation: This tag defines what page the browser will be
redirected to after the form has been submitted. This tag is
required.

Tag: logfile
Explanation: This tag defines a file which will store
information about people who have entered data into your
form. The logfile will store the following information:
1) date form was submitted, 2) IP address of form submitter,
3) e-mail address of form submitter (if you provided a
"from-email" form field where the user could enter their
e-mail). This field is optional.

Tag: template
Explanation: This field defines the name and location of
your e-mail template file.

Tag: from-email
Explanation: This field defines where the user can enter
their e-mail address. This tag is optional, but if you want
to be able to log a users e-mail address in your logfile and/or
you want the visitors addres to appear in the from field of
your message, you should use this tag.


2) Create an e-mail template for the HTML form (NOTE:
this step is optional, but highly recommended).

Example:

We'll make an e-mail template for the HTML form above:

Yet another test message!
-----------------------------

!Full Name

!!E-mail

!Website

*****************************

The resulting e-mail should look like this:

Yet another test message!
-----------------------------

Full Name:      Bob Dobbs

E-mail:         bob@dobbs.com

Website:        http://www.foo.org

*****************************

You'll notice in the template that there are exclamation
marks appearing before the field name that corresponds
to the HTML form.

You use one (1) exclamation mark to indicate where you
would like the data from the form to appear in the message,
and you use two (2) exclamation marks to indicate a form
field that is required. If the user does not fill out a
form field that is marked with two exclamation marks,
Form_Mailer will generate an error message that informs
the user that they must go back and fill out that form
field.

======================================================
Form Mailer Programmer's Guide

Currently Unfinished