BigNoseBird.Com's 
                        - - - - -
                 All Purpose Form Handler
                        - - - - -

This program, bnbform.cgi is designed to allow you to 
quickly implement your HTML based forms. The program
is configured by information you provide in the form
itself, so you can get the script to handle your data
in a variety of ways without changing your scripts.
Without writing one line of perl code, you can do
the following (in any combination!):

  1.) Submit E-mail to a specified person.
  2.) Send the data to a file for easy import into a 
      database program.
  3.) Automatically send a resonse to the submitter,
      with a text file to contain your message.
  4.) Define the order the data is printed.
  5.) Enforce completion of specified fields.
  6.) Define a page for a "Thank you" or an "Oops!" 
      message after the form is submitted.


I.   GETTING READ TO INSTALL
----------------------------
Included in this zip or tar file you will find the 
following files:

FILE NAME      DESCRIPTION
---------      -----------
README.TXT     The file you are reading!
bnbform.cgi    The script
bnbform.html   A sample form
mymessage.txt  A sample autoreponse message
oops.html      A sample HTML page for incomplete data
thanks.html    A sample HTML page for saying thanks!

NOTE: PLEASE READ THE Q&A BELOW, IT CONTAINS SOME
USEFUL SETUP INFORMATION!

In order to install the script, you should only have
to find out the answers to the following questions:

   Q: Where is perl on my server?
   A: On most systems it is /usr/local/bin/perl but it
      may be in /usr/bin/perl or /usr/sbin/perl. The very
      first line of the script says,
      #!/usr/local/bin/perl
      This MUST be the first line of the script with nothing
      including blank lines above it. If your "perl" is not
      there, edit this line so that it is correct for your
      system.

   Q: Where is the sendmail program on my server?
   A: You will see a line in the script that says,
      $mail_program="/usr/lib/sendmail -t";
      On 99% of the systems I have worked with, 
      that should be fine. If your sendmail is
      elsewhere, just correct that line in the 
      script.

   Q: Where is my cgi-bin directory?
   A: This varies. Please check with your system 
      administrator or system FAQ if you do not know
      this.

   Q: How do I call a cgi-bin script from a form?
   A: On my system, this does the trick:
      <FORM METHOD="POST" ACTION="/cgi-bin/bnbform.cgi">
      Again, this can vary from server to server so 
      please consult your server FAQ or your system
      administrator.

   Q: How do I set file permissions?
   A: Once the files are installed, using FTP, you want
      to set the permissions on bnbform.cgi so that
      they are the equivalent of 755. This means that
      the owner can read-write-execute, group can 
      read-execute, and others can read-execute. If you
      can login using telnet, you can issue the command:
           chmod 755 bnbform.cgi
      You must "cd" to the directory containing the 
      script before doing this.
      For specific instructions on setting permissions
      using FTP, please see the "HELP" for your FTP 
      program.

II.  INSTALLING THE FILES ON YOUR SERVER
----------------------------------------

Edit the bnbform.cgi to make sure the path to perl is 
correct, i.e.,

#!/usr/local/bin/perl

Edit the bnbform.html to make sure you are calling the
script properly, i.e.,

      <FORM METHOD="POST" ACTION="/cgi-bin/bnbform.cgi">
Also, change the e-mail address of the "submit_to" and
the http://domain.com/oops.html and http:domain.com/thanks.html
so that they are correct for your domain. You may delete the
lines containing the ok_URL and not_ok_URL if you want.

Using FTP, transfer the following files using ASCII mode.
NEVER USE BINARY TO TRANSFER TEXT FILES FROM A PC TO A 
UNIX SERVER!!!!!

FILE           LOCATION
bnbform.cgi    cgi-bin directory
mymessage.txt  cgi-bin directory
bnbform.html   your webpage directory
oops.html      your webpage directory
thanks.html    your webpage directory

Set the permissions on bnbform.cgi to 755 which
means the owner can read-write-execute, group can
read-execute, and others can read-execute. (This
was one of the questions above!)

Guess what? That's it! Installation is complete
and you can test the script using the bnbform.html
that is included- after you edit it as described 
above.

III. CONFIGURING THE FORM FOR YOUR NEEDS
----------------------------------------
The bnbform.cgi script is very simple, and very flexible. 
How it works, is that it looks at the form's data for the 
existence and content of some special fields, most of 
which are HIDDEN so the reader doesn't see them. Here are
a list of the magic fields:


IMPORTANT NOTE: ALL FIELD NAMES AND VALUES ARE CASE SENSITIVE!
                To keep things simple- just use lower case. 

submit_by:   The e-mail address of the person completing the
             form. You should make this required if you are
             using autorespond.

required:    A list seperated by commas "," listing ALL fields
             you wish to enforce data completion on. As an
             example:
             <INPUT TYPE="HIDDEN" NAME="required" 
              VALUE="name,country,submit_by">

data_order:  In order for your information to show up in a file
             or in your e-mail, you MUST list each field you want
             to see in this comma "," separated list. This also
             specifies the order the data will be printed to mail
             and to file. Here is an example:
             <INPUT TYPE="HIDDEN" NAME="data_order" 
                VALUE="name,country,submit_by,mailing_list,how_found,
                       grape,banana,apple">

submit_to:   The person to receive the e-mail. Example
             <INPUT TYPE="HIDDEN" NAME="submit_to" 
                VALUE="yourname@domain.com">
             You do not have to indicate a "submit_to"
             if you are sending the information to a file,
             and don't need e-mail notification.

autorespond: If this field is included and set to = "yes",
             then a confirmation e-mail will be sent to
             the value in "submit_by". Example:
             <INPUT TYPE="HIDDEN" NAME="autorespond" VALUE="yes">

automessage: A textfile containing a message to go out as the
             body of an autorespond e-mail. Example,
             <INPUT TYPE="HIDDEN" NAME="automessage" 
                VALUE="mymessage.txt">
             ***You can also specify the actual path to the file
                if you will be running this outside of the main
                cgi-bin directory- or if you want the data elsewhere.

outputfile:  This tells the system you want to log information,
             and what to name the file. The script will create
             the file with proper permissions for you.
             <INPUT TYPE="HIDDEN" NAME="outputfile" 
               VALUE="form.log">
             ***You can also specify the actual path to the file
                if you will be running this outside of the main
                cgi-bin directory- or if you want the data elsewhere.

form_id:     Optional. Forms part of the subject in to
             the e-mail to the person receiving the data.
             This helps them know which form it came from.
             <INPUT TYPE="HIDDEN" NAME="form_id" 
                VALUE="My Test Form">

ok_url:      A URL to jump to after successfully completing
             the form. If this is not on the form, a default
             "Thank you" message appears.
             <INPUT TYPE="HIDDEN" NAME="ok_url" 
                 VALUE="http://domain.com/test/thanks.html">
             You MUST specify the full URL as shown above!
             OPTIONAL!

not_ok_url:  A URL to jump to after not filling in all the
             required fields on the form. If this is not 
             on the form, a default "Oops" message appears.
             <INPUT TYPE="HIDDEN" NAME="not_ok_url" 
                VALUE="http://domain.com/test/oops.html">
             You MUST specify the full URL as shown above!
             OPTIONAL!


IV.  VARIOUS CONFIGURATION SCENARIOS
------------------------------------
              
Field Name   Datafile   E-Mail   Auto-Respond   A-R with Message
----------   --------   ------   ------------   ----------------
submit_to                 X
----------------------------------------------------------------
submit_by                             X                X
----------------------------------------------------------------
autorespond                           X                X
----------------------------------------------------------------
outputfile      X
----------------------------------------------------------------
automessage                                            X
----------------------------------------------------------------

For datafile and autorespond:
  submit_by
  autorespond
  outputfile

For datafile and autorespond with custom message:
  submit_by
  autorespond
  outputfile
  automessage

For e-mail notify and autorespond:
  submit_to
  submit_by
  autorespond

For e-mail notify and autorespond with custom message:
  submit_to
  submit_by
  autorespond
  automessage

For the whole enchilada!!!!!!
  submit_to
  submit_by
  autorespond
  outputfile
  automessage


V.   THINGS YOU NEED TO KNOW....
--------------------------------

About CHECKBOX fields... Eventhough you can have multiple 
CHECKBOX fields with different values- DON'T DO IT! This
script only picks up the last checked item. 

Since information might be going to a datafile, it would
be nearly impossible for you to get uneven columns of data
straightened out. Use different names for each field.


VI.  COOL TRICKS
----------------

Let's say you have more than one person you may need to send
the mail to depending on the form. What you can do is place 
the submit_to in a set of radio buttons, i.e.,

  <INPUT TYPE="RADIO" NAME="submit_to" VALUE="support@x.com" CHECKED>Support
  <INPUT TYPE="RADIO" NAME="submit_to" VALUE="sales@x.com">Sales
  <INPUT TYPE="RADIO" NAME="submit_to" VALUE="billing@x.com">Billing
  <INPUT TYPE="RADIO" NAME="submit_to" VALUE="pres@x.com">President

  Note that I have indicated CHECKED next to support. This way there
  is a default value.