mailto.cgi v2.0 - README - 1998 04 19

Copyright 1997 by Scott Wimer
http://www.cgibuilder.com/

-blurb-
This is an Perl script for mailing the contents of Web Forms. It includes
HTML callable input checking routines that allow the web author to require the
submitted data meet certain requirements - all through hidden form elements.


-about-
mailto.cgi is a Perl script for parsing web based forms.  All configuration
for the script is taken from the form input.  This makes it highly portable
and extremely useful for applications that would otherwise require multiple
scripts.  The fundamental power of mailto.cgi is that it lets each form
specify error-checking routine calls from within the HTML and each form can
completely control the format of the email message from directives in the HTML.
This approach both reduces the total time required to create web based forms, 
but also reduces the likely hood of programming errors (instead of having to 
make several CGI scripts run perfectly, only one has to be made bug free).
This translates directly into a savings of time and money (not to mention that
the script it self is free).


-installation-
Installation of mailto.cgi requires copying 'mailto.cgi', 'Var_Sub.pm', and
'checks.pl' into your CGI directory.  You will then need to set the
executable bit on 'mailto.cgi'.  The only change you may have to make is 
changing the path to Perl in the first line of 'mailto.cgi'.  Standard settings
for the permissions can be achieved with the following command:  
 'chmod 755 mailto.cgi'.


-configuration / use-
mailto.cgi has 5 types of configuration options.  They are: mailer directives,
info directives, email-formating directives, error-checking directives, and
confirmation message directives.
NOTE:  All directives are CASE SENSITIVE.  That means that "SUBJECT" and
"Subject" are NOT the same.  Once you have added the necessary configuration
directives (between the opening <FORM> tag and the closing </FORM> tag) 
build your web form just as you normally would.

The format and a basic description for each type is displayed below:


MAILER DIRECTIVES:
The following directives control the mailer:(RECIPIENT, THANKURL, SUBJECT,
FROMADDRESS).  Only RECIPIENT is required.  All others SHOULD be used, since 
otherwise the code uses internal defaults that may not be what you desire.
The format for these directives is below:
        <input type=hidden name=RECIPIENT value="...">
        <input type=hidden name=THANKURL value="...">
        <input type=hidden name=SUBJECT value="...">
        <input type=hidden name=FROMADDRESS value="...">

The FROMADDRESS directive will be processed specially if it contains a 
dollar sign('$').  You can refer to the contents of another field by setting
the value of FROMADDRESS to be a dollar sign followed by the name of another
field.  Caveats on the format of the field names are discussed below in the
section on email formatting directives.

The following chart shows the type of data that must be used for each directive:
        DIRECTIVE               DATA TYPE
        ------------            --------------
        RECIPIENT               email address
        THANKURL                URL
        SUBJECT                 Text
        FROMADDRESS             email address or $field_name



INFO DIRECTIVES:
The following directive controls whether or not to send additional information 
regarding the browser used when the form was submitted:(BROWSER_INFO).
The format for this directive is below:
        <input type=hidden name="BROWSER_INFO" value="optional variable list">

This directive behaves like an advanced on/off switch.  If the directive is
not present, then the information about the visitors browser and IP address
information (basically, the environment variables available to the mailto.cgi
script) will not be sent.  If you simply specify the BROWSER_INFO directive
without any variable names, then all the information about the visitors 
browser will be sent.  You can choose which values you wish to get in the
email by specifying them as a comma separated list in the value portion of
the BROWSER_INFO directive.  The example below will only report the name
of the remote host, and the official browser type they are using:
	<input type=hidden name="BROWSER_INFO" 
	 value="REMOTE_HOST,HTTP_USER_AGENT">



EMAIL-FORMATTING DIRECTIVES:
The following directives control the formating of the email message generated:
(SEPARATOR, ALPHA_SORT, SUPPRESS_EMPTY, FORMAT).
The SEPARATOR directive is used to define the Text which separates the Field 
Name from the Field Value in the generated email message.
The format for this directive is below:
        <input type=hidden name=SEPARATOR value="...">
Where the value is a Text string to use as the new separator.
If this directive is not defined in the form, then the script defaults to ": "
as the delimiter.  Output using the default would appear as:
        Field_Name: Data from form

The ALPHA_SORT directive controls the order of the Fields in the generated
email message.  The format for this directive is below:
        <input type=hidden name=ALPHA_SORT value "">
If this directive is not used, the Fields will be in the order in which
they appear in the HTML of the Form.  If this directive is used, the sorting
will be done alpha-numerically.

The SUPPRESS_EMPTY directive causes Advanced Form Mailer to omit any empty
Fields from the generated email message. The format for this directive is
below:
        <input type=hidden name=SUPPRESS_EMPTY>
It also behaves as a switch.  If you wish to receive all Fields including empty
ones, do not use this directive.

The FORMAT directive allows you to completely control the email.  Using the
FORMAT directive requires you to name your fields with only letters, numbers,
and underscores in the name.  Also, the first character in the field name 
must be a letter or an underscore.  If your fields are named properly then
you can use the FORMAT directive.  The value for the FORMAT directive is the
entire body of the email message you wish to send.  The data from each of 
the fields in your form is available in the FORMAT as '$<fieldname>'.  For
example: if you have a field named 'first_name', to use the data from the
'first_name' field in the email, use '$first_name' in the FORMAT.  Below is
a sample FORMAT for a form that has 3 fields, 'your_name', 'your_addr', 
'comments'.
	<input type=hidden name=FORMAT value=
	"$your_name, at $your_addr wrote us some comments.  Their comments
	are: $comments.

	We need to make sure that we take care of this for them.">

The references to '$your_name', '$your_addr', and '$comments' will be replaced
in the email sent by the values entered by the visitor into the fields,
'your_name', 'your_addr', and 'comments', respectively.



ERROR-CHECKING DIRECTIVES:
The following directives control the error-checking activities of mailto.cgi:
(EMAIL,PHONE,ZIP,SELECT,NONUM,NOLETTER,NUMONLY,LETTERONLY,NOTBLANK).
Additionally, the "ERROR_URL" directive allows you to specify a web page to
redirect the visitor to when they make a mistake on the form.  When this 
directive is omitted, a page describing their input mistakes is presented to
them.

The general format for all but the SELECT directive is:
        <input type=hidden name="CHECK:DIRECTIVE:FIELD_NAME">
Where 'DIRECTIVE' is one of the directives listed above (with the exception of
the SELECT directive).

The format for the SELECT directive is:
        <input type=hidden name="CHECK:SELECT:FIELD_NAME" value="...">

Where the contents of the value field is the select option you do not wish to
allow.

Examples of error-checking directives:

        <input type=hidden name="CHECK:NOTBLANK:name">
        <input type=hidden name="CHECK:EMAIL:email_address">
        <input type=hidden name="CHECK:NUMONLY:age">
        <input type=hidden name="CHECK:NONUM:color">
        <input type=hidden name="CHECK:NOTBLANK:color">
        <input type=hidden name="CHECK:LETTERONLY:state">
        <input type=hidden name="CHECK:NOTBLANK:state">
        <input type=hidden name="CHECK:ZIP:zipcode">
        <input type=hidden name="CHECK:NOTBLANK:zipcode">
        <input type=hidden name="CHECK:SELECT:types_avail" value="Chose one">

Where "name","email_address","age","color","state","zipcode","types_avail", are 
fields that you wish to have the user fill out.

Fields can have multiple error-checking directives applied to them, as the above
example illustrates.  One excellent example is the "age" field referenced.
In the directives above, we won't require that the user tell us their age, but
we will require them to give us their age in numbers only if they choose to tell
us.


CONFIRMATION MESSAGE DIRECTIVES:
The following directives control whether or not a confirmation message is to
be set automatically to the visitor who filled out the form: 
(CONFIRM_RECIPIENT, CONFIRM_MESSAGE, CONFIRM_FROMADDRESS, CONFIRM_SUBJECT).
These directives behave much like their MAILER directive counterparts, with
a few notable exceptions.  Each of the CONFIRMATION directives is parsed to
check for references to other field names (see the section on the FORMAT
directive).  This allows you to have an automatically generated response go 
straight to the email address submitted by the visitor.  The CONFIRM_RECIPIENT
directive defines the address that will receive the confirmation email.  The
CONFIRM_FROMADDRESS directive defines the address the confirmation email will
come from (the From: <address> in the recipients email client).  The 
CONFIRM_SUBJECT directive  defines the subject of the confirmation email.
And, the CONFIRM_MESSAGE directive is the message which will be sent as a
confirmation.  The value of CONFIRM_MESSAGE is processed in exactly the
same way that the FORMAT directive's value is.

This example sends a brief "your order was received" type reply to the
visitor of a mythical form.
	<input type=hidden name=CONFIRM_RECIPIENT value="$email_address">
	<input type=hidden name=CONFIRM_SUBJECT value="Your order received">
	<input type=hidden name=CONFIRM_FROMADDRESS value="bob@what.org">
	<input type=hidden name=CONFIRM_MESSAGE 
	value="$name, thank you for your order, of $quantity gadgets.
        We value your business.">