Formmail

The Formmail cgi function allows you to create custom input forms that will be
automatically emailed to a defined recipient. Any number of uniquely named fields
can be used. Selected fields can be required to contain data. There is no provision
at this time for the contents of a required field to be verified for content type
(make sure an email address looks like an email address).

Master Copy The master copy of the formmail.cgi file is located at
/usr/local/html/master_cgi_files/formmmail.cgi

Server Setup The process involved in setting up the cgi for use by a domain is:
1) Copy the file to the cgi-bin directory of the domain
2) Edit formmail so that the domain is included in the referrers list
3) Set the permissions to rwxrwxr_x

1) Copy the file to the cgi-bin directory of the domain
    At the server:
        Change directory to the source location
            cd / usr/local/html/main/master_cgi_files
        Copy the file to the destination domain
            cp formmail.cgi ../../domain.name/cgi-bin/
        Remote computer:
            The assumption here is that formmail.cgi resides on the local computer.
            Otherwise, use Telnet to perform the actions shown in the server section above.
            Modify formmail.cgi file before using FTP to upload (See step 2 below)
            Upload to /usr/local/html/domain.name/cgi-bin/

2) Edit formmail so that the domain is included in the referrers list
    Note: This function should be performed prior to FTP if formmail.cgi is being uploaded
    from remote computer.
Within the Define Variables section near the beginning of the file is a line that begins
     @referers= (
        Add the domain name within single quotes to the list.
        Use a comma to seperate from any other entries in the list.

3) Set the permissions to _rwxrwxr_x
Once the file is in the cgi-bin directory, change directory (use Telnet from remote)
cd /usr/local/html/domain.name/cgi-bin
Change permissions
chmod 775 formmail.cgi
The Formmail program has now been seup for use by the domain.

This section contains examples of the code used to setup the fields. Using the Form Mail routines in a web page.
see http://www.artsci.net/formmail.shtml for an example

1) Define the form, method, and Form Mail cgi to use:
    FORM METHOD="POST" ACTION="http://www.domain.name/cgi-bin/formmail.cgi"
2) Define the email address of the person receiveing the form information:
    INPUT TYPE=hidden name="recipient" VALUE="user@domain.name"
        TYPE= hidden: this option prevents visitor from seeing value of this field
3) Define the text to fill in the Subject field:
    INPUT TYPE=hidden name="subject" VALUE="Visitor Information"
4) Define any required fields (this sample requires email and realname fields to be filled in)
    - OPTIONAL
        INPUT TYPE=hidden name="required" VALUE="email,realname"
        Defines the fields email and realname must be contain data
5) Define any title to appear at the top of the email message
    - OPTIONAL
        INPUT TYPE=hidden name="title" VALUE="My E-mail Form"
6) INPUT TYPE=hidden name="print_config" VALUE="email,realname,address,city,state,zip"
7) Define the order for the fields to appear in the email (this sample uses the fields collected below)
    - OPTIONAL
        INPUT TYPE=hidden name="sort" VALUE="order:email,realname,address,city,state,zip"
    Other options includes
        VALUE="alphabetic"

Sample Code for Data Collection within a Form:

<table border=1>
<TR><TD></TD>
<TD><FONT SIZE=5>Your email address:</TD>
<TD><FONT SIZE=5><INPUT TYPE=text name="email"></TD></TR>
<TR><TD></TD>
<TD><FONT SIZE=5>Your name:</TD>
<TD><FONT SIZE=5><INPUT TYPE=text name="realname"></TD></TR>
<TR><TD></TD>
<TD><FONT SIZE=5>Street address:</TD>
<TD><FONT SIZE=5><INPUT TYPE=text name="address"></TD></TR>
<TR><TD></TD>
<TD><FONT SIZE=5>City:</TD>
<TD><FONT SIZE=5><INPUT TYPE=text name="city"></TD></TR>
<TR><TD></TD>
<TD><FONT SIZE=5>State:</TD>
<TD><FONT SIZE=5><INPUT TYPE=text name="state"></TD></TR>
<TR><TD></TD>
<TD><FONT SIZE=5>Zip Code:</TD>
<TD><FONT SIZE=5><INPUT TYPE=text name="zip"></TD></TR>
<TR><TD></TD>
<TD><FONT SIZE=5> <INPUT TYPE=hidden name="required" VALUE="email,realname"> </TD> </TR>
<TR><TD><FONT SIZE=5><CENTER><INPUT TYPE="submit" VALUE="Sign-In"></TD>
<TD></TD>
<TD><FONT SIZE=5><CENTER> <INPUT TYPE="reset" VALUE="Clear"> </TD>
</TR>
</TABLE>

Optional Form Fields:

Field: subject
Description: The subject field will allow you to specify the subject that you wish to
appear in the e-mail that is sent to you after this form has been filled out. If you do
not have this option turned on, then the script will default to a message
subject: WWW Form Submission
Syntax:     <input type=hidden name="subject" value="Your Subject">
    To allow the user to choose a subject:
                <input type=text name="subject">

Field: email
Description: This form field will allow the user to specify their return e-mail address.
This will be put into the FROM field of the message you receive.
Syntax: <input type=text name="email">

Field: realname
Description: The realname form field will allow the user to input their real name.
This field is useful for identification purposes and will also be put into the FROM
line of your message header.
Syntax: <input type=text name="realname">

Field: redirect
Description: If you wish to redirect the user to a different URL, rather than having
them see the default response to the fill-out form, you can use this hidden variable
to send them to a pre-made HTML page.
Syntax:
    To choose the URL they will end up at:
        <input type=hidden name="redirect" value="http://your.address/to/file.html">
    To allow them to specify a URL to go to:
        <input type=text name="redirect">

Field: required
Description: Place all fields that must contain data into this field. If the required
fields are not filled in, the user will be notified of what they need to fill in, and a
link back to the form they just submitted will be provided.
Syntax: <input type=hidden name="required" value=email,phone">
This example requires the email and phone fields to contain data
for the form to be submitted.

Field: env_report
Description: Allows you to have Environment variable included in the e-mail
message you receive after a user has filled out your form. Useful if you wish
to know what browser they were using, what domain they were coming from
or any other attributes associated with environment variables.
These variables include:
    REMOTE_HOST - the hostmane making a request
    REMOTE_ADDR - Sends the IP address of the remote host
    REMOTE_USER - If server supports authentication and script is protected,
                                 this is the username they are autenticated as.
                                 * 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.
                                   * not usually set.
    HTTP_USER_AGENT - The browser the client is using to send the request.
                                          General format: software/version library/version
Syntax:
    <input type=hidden name="env_report" value="REMOTE_HOST,REMOTE_ADDR">

Field: sort
Description: This field allows you to choose the order in which you wish for your variables to appear in the e-mail that FormMail generates. You can shoose to thave the field sorted alphabetically or specify a set order in which you want the fields to appear in your mail message. By leaving this filed out, the order will simply default fo te order in which the browsers sends the information to the script (not necessarily the same as the form) When sorting by a set order of fields, you should include the phrase "order:" as the first part of your value for the sort field, and then follow that with the field names you want to be listed separated by commas.
Syntax:
<input type=hidden name="sort" value="alphabetic">
<input type=hidden name="sort" value="order:name1,name2,name3,etc...">

Field: print_config
Description: print_config allows you to specify which of the config variables you would like to have printed in your e-mail message. By default, no config fields are printed to your e-mail. This is because the important form fields, like email, subject, etc... are included in the header of the message. So the usual header fields can be printed in the body of the email.
Syntax: <input type=hidden name="print_config" value="email,subject">
The email and subject fields will print in the body of the message

Field: title
Description: This form field allows you to specify the title and header that will appear on the resulting page if you do not specity a redirect URL.
Syntax: <input type=hidden name="title" value="Feedback Form Results">