webformmail_readme.txt Readme file for the WebFormMail script
Last edit by Julie Skokna 4-7-00

############################################################################
#             WEBFORMMAIL                                                  #
# Form_processor.cgi alias WebResponder with changes to the email routines #
# Modifications made to this script by Julie Skokna WebBox Design & CGI    #
#  DEC. 9, 1999 to fix compatibility with qmail                            #
# AGoodWeb.com     admin\@agoodweb.com
# Original script from Extropia.com (see their info below and throughout)  #
# Also, took some elements from FormMail by Matt Wright see                #
# Matt's Script Archive, Inc.:    http://www.worldwidemart.com/scripts/    #
#                                                                          #
# This script is free as the day it was born. Thank you to Extropia        #
# and Matt for helping me learn. It is a joy to give back some code I hope #
# will be of help to others.  - Julie Skokna :-)                           #
# Main hack: simplified mail code to bypass the mail-lib.pl routines which #
# do not print the from: and subject: in mail headers on some mail systems #
############################################################################

# Addendum 4-7-00 The big joke is that there is a simple fix to the mail-lib.pl
# from Extropia. Just make sure there are no double-spaced lines in the mail
# code! So, I did not really need to hack this script, but I am happy I did
# because of the increased functionality. See below! :-)


Description: WebFormMail is a script that combines the best of two fine scripts:
The Extropia.com WebResponder and Matt's FormMail

Why it was hacked: The motivation for hacking the original form_processor.cgi 
came when I could not get the script to send the mail properly and include
a From: and Subject: field variable in the header of the email.
This was more of an inconvenience, but it is nice to see who the mail
is From: and the Subject: is helpful in mail sorting.

Qmail seemed to be having trouble with the Extropia mail routines while
FormMail from Matt's script archives was sending the From: and Subject:
fields in the email. However, I did not want to give up the really nice
way that the WebResponder from Extropia.com puts the form data into a 
database. It would be great not to have to retype all that info that
people are sending in. So, I combined what I considered the best elements
from both scripts with happy results.

The files: form_processor.cgi use with setup file webformmail.setup.cgi
The form.htm will access the script with this setup file. It will write
to the webformmail.data.cgi file.

Some features:

1. The script will send a confirmation email to the web visitor. 

2. You can configure in the setup file the top of the message as well 
as a "signature" at the bottom of the email that the visitor receives.

3. You also set hidden input variables on the form which will carry the 
setup_file name, redirect page url (for after your form is sent), the 
subject of the email that is sent to the admin, the subject of the email
confirmation that is sent to the visitor:

Example:
  <input TYPE="hidden" NAME="setup_file" VALUE="webbox_feed.setup.cgi">
  <INPUT TYPE = "hidden" NAME = "form_to_user_email_subject" VALUE = "WebBox Mailing List Join"><br>
  <input TYPE="hidden" NAME="subject" VALUE="WEBSITE: Join Mailing List"><br>
  <input TYPE="hidden" NAME="redirect" VALUE="http://webbox.hypermart.net/joinsent.shtml"><br>
             

4. The environment variables HTTP_USER_AGENT and REMOTE_HOST are sent to
the admin but not to the visitor. They are also sent to the database so
later you can make reports of where your visitors are coming from and 
what software they are using.

5. The form data is sent to a database for later retrieval and use in a 
database program. The file is pipe-delimited.

6. Checks the url of the calling form and will not let just any form on the
web access your script. You configure the @referers in the setup file to
include your domain name.

7. Includes a script (in the Form directory called webformmail_feed.cgi) which will 
generate the form if you call it.

Files I edited / added:

I changed the form_processor.cgi and the setup file (webformmail.setup.cgi). 
The code changes are documented in the files with comments.

The form.htm in the form_processor directory is the form that calls the 
script. You can use it as a template. I suggest placing the form right on
your website, but if you do, then you need to edit the setup_file path and
make sure you put your domain url in the @referers in the setup file.

I also created the webformmail_feed.cgi to generate the form above. You would put
a link to the webformmail_feed.cgi to call the script and it would display the form.
Again, you will have to play with the location of the form_processor.cgi to
make sure the form is able to find the script.

WHAT YOU NEED TO DO:

1. After getting your files untarred on the server (see the installation 
documentation in the Documentation directory), then set the permissions.

2. Edit the setup file (webformmail.setup.cgi) by first saving it to a new 
filename and then putting your own variables in to customize it for your
uses.

  - It is important to put the path to your server's email program
    into the setup file.
  - You can configure the script to send an email to the visitor.
  - You can set up the top and signature for the email message that is sent to
    the visitor. 
  - Set it up to redirect the visitor to a page of your choice on your website
    (or wherever you'd like I guess) after they submit their form. It is nice to
    have a customized message to thank them and give any more information you 
    might need to give.
  - Set the path to the redirect page if you are using one.
  - Put in your email address for the form data to be sent to if you choose this
    option. Don't forget to escape the @ sign in the email address (webbox\@netzero.net).
  - Configure the @referers array to include your domain name.
  - Create your form to access the script. See the form.htm in the form_processor
    directory. Make sure you make the value of the visitor's email as 
    "client_email" as this is referenced in the script and used to email the 
    confirmation to the visitor.
    The form included will help you as it has a few words of advice and you can
    see how I did it.
  - If you plan on generating the form from the separate script located 
    in the Forms directory, then paste your html code for the form into the 
    section after the print qq~ and before the ~; so it will print.

Good luck and I hope that this is of help to anyone who had been struggling
with getting their webresponder to send the mail with the From: and Subject:
in the header AND anyone who wished they didn't have to retype all that info
coming in through their FormMail scripts.

My thanks to Extropia.com and Matt Wright for making their scripts available!

Oh, also, I have included the original form processor script named
form_processor.cgi.ori which can be used with the default setup files from 
Extropia.

Julie Skokna :-)
admin@agoodweb.com
AGoodWeb.com