BASIC INFORMATION
Name: Selena Sol's Form Processor
Version: 4.01
Last Modified: 02-04-97
DESCRIPTION
This form processing script allows a site administrator to process
multiple HTML forms with one script. By taking advantage of various
hidden tags which this script can understand, the admin can use this one
script to process all of her forms in multiple ways from dynamic email
to building a database. We have included three examples of how you might
use this script including a Jump Box, a Download Form and a Simple
Feedback form.
COPYRIGHT INFORMATION
This application was written by Selena Sol (selena@eff.org,
http://www.eff.org/~erict) having been inspired by countless other Perl
authors. Feel free to copy, cite, reference, sample, borrow, resell or
plagiarize the contents. However, if you don't mind, please let me know
where it goes so that I can at least watch and take part in the
development of the memes. Information wants to be free, support public
domain freeware. Donations are appreciated and will be spent on further
upgrades and other public domain scripts.
Finally, PLEASE SEND WORKING URL's to selena@eff.org. I maintain a list
of implementations around the world.
SUPPORT
This script comes with no guarantees or warranties. Don't expect the
scripts to be perfect. They have evolved continually since late 1996
and will continue to do so.
Bug reports are greatly appreciated but installation support is extremely
discouraged. I have attempted to include as much information as I could
think of in this README and in the FAQs available at
http://www.eff.org/~erict/Scripts/.
And there is always lively discussion in Selena Sol's Discussion Forum
(http://www.sidestreets.com:8080/~77). Please try ALL available sources
of information BEFORE you email me. But if you must, make sure to include
the following bits of information (I may not respond to your email if you
do not answer ALL of the following questions):
1. What type of Web server are you running?
2. What type of Operating System is the Web server running on?
3. What is the "exact" error message from the Web?
4. What is the "exact" error message in your web server's error log?
5. What is the "exact" error message you receive when running the script
from the command line.
6. Are you running this script on an ISP? If so, what is the email
address of the Sysadmin there?
7. Are you using a virtual server setup? If so, what is the root path set
in your Web server's environment?
8. In which directory is the Perl interpreter located?
9. In which directory is sendmail located (if you are using a script which
demands use of sendmail)
Again, I MAY NOT ANSWER YOUR QUESTION unless you have answered all nine of
these questions.
BASIC INSTALLATION (DOWNLOADING THE SCRIPT)
It is recommended that you point your Web browser to "Selena Sol's Script
Archive" to get the latest version of this script. The Script Archive is
located at the following URL:
http://www.eff.org/~erict/Scripts/
From the "Script Archive" frontpage, follow the hyperlinks to the detailed
page dedicated to this script. Then click on the hyperlink "Download the
scripts as a single tar file".
BASIC INSTALLATION (UNARCHIVING THE APPLICATION)
Tar is a UNIX command that allows you to create a single archive file
containing many files. Such archiving allows you to maintain directory
relationships and facilitates transferring complex programs with many
separate but integrated parts which must have their relationships
preserved. Tar has a motley of options which allow you to do archiving and
unarchiving in many ways. However, for the purpose of untarring this
application, the commands will be fairly simple.
Once you have downloaded the TAR file transfer it to an executable
directory on your web server and "untar" it. On UNIX systems, you may
type the following at the command line (in the same directory as the TAR
file itself):
tar xvfp web_store.tar
Tar will go through the archive file and separate out each individual
directory and file, expanding them into their appropriate places
underneath the current directory. The "xvfp" letters in the tar command
above are parameters that tell the program to extract the files and
directories out of the ".tar" file. Specifically, "x" tells tar to extract
the files. "v" tells tar to output information about the status of its
extraction while it is performing the work, "f" informs tar to use the
".tar" filename as the source of the files to be extracted, and "p" notes
that the original permissions should be maintained. The reason the
"f" parameter has to be used is that tar, by default, archives files and
directories to a tape drive. Tar is actually short for "[T]ape [AR]chive".
Figure 1-2 shows the output of the above command.
(Note: If you are using a non-UNIX Operating System, you may
download a TAR/UNTAR program by pointing your Web browser
to http://www.shareware.com I suggest using WINZIP if you are on
a windows-based operating system. Also, be warned...do not
untar the scripts on your local machine, modify them, and then
transfer the modified application to you server unless you take
care to transfer all files using ASCII mode. If you get the
following when running the script from the command line:
"Can't find string terminator " end_of_html"
anywhere before EOF"
You can be sure that you have transferred the files improperly.
BASIC INSTALLATION (SETTING PERMISSIONS)
Untarring the files is only one part of the equation of installing the Form
Processor application and getting it to actually run. Frequently, the Web
server needs to be given special permission to run your scripts and have
the scripts perform their job with the appropriate "rights".
The cardinal rule for setting up Web server software is that the server
should be given only minimal capabilities. This definitely rules out the
Web server running as the ROOT user (Super user on UNIX). More often than
not, it means the Web server is run as a user that has no rights to do
anything significant -- the user "nobody". By default, "nobody" usually
does not have permission to read any files in directories that you create.
However, when you download scripts, you need to make it so that the
scripts can be read and executed by the Web server software. In other
words, "nobody" has to be able to get to the files.
In UNIX, the magic command for performing this task is "chmod". chmod is
explained in detail in the Customization and Installation FAQ on the
scripts archive, but the following chart is provided here to as a quick
reference.
PERMISSION COMMAND
U G W
rwx rwx rwx chmod 777 filename
rwx rwx r-x chmod 775 filename
rwx r-x r-x chmod 755 filename
rw- rw- rw- chmod 666 filename
rw- rw- r-- chmod 664 filename
rw- r-- r-- chmod 644 filename
U = User
G = Group
W = World
r = Readable
w = writable
x = executable
- = no permission
[WARNING] You may be tempted to simply use chmod 777 on all the files and
directories since that assures the Web server can do anything with the
files. However, it is strongly advised that you do not leave the files in
this state. It is considered a big security risk to leave your scripts
open to changes by the Web server instead of being read-only. Anyone on
the server could use another rogue CGI script to write over your scripts
and make them do something completely different. There is still a risk
involved in making the messages directory writable, but at least if
someone is going to be messing with your area, they will only destroy a
bit of data and not your main programs. It is "OK" to set the scripts to
777 if you are troubleshooting a problem and want to rule out permissions
entirely, but do not leave the scripts like this. On another security
note, if you are really concerned with the security of your data such as,
please do not use a shared server where other people can write CGI scripts
using the same Web server configuration. It is much better to use your
own server software or purchase space on a "virtual server" which may be
shared, but is set up in such a way that each user's scripts are shielded
from each other.
Note: Not setting your permissions correctly is the
NUMBER ONE reason why installations fail. Take time to
get this right.
The actual permissions required for the subdirectories and files used by
this application are listed in the next section.
BASIC INSTALLATION (FILES, DIRECTORIES, AND PERMISSIONS)
The TAR file will then expand into a root directory called Form_processor.
Form_processor will contain several sub-directories and several files.
The diagram below depicts the directory structure as well as the
permissions which must be applied to the files and subdirectories used by
the application.
Form_processor Root Directory (dr-xr-xr-x)
|____Databases Sub-directory (drwxrwxrwx)
| |____download.data (-rw-rw-rw-)
| |____feedback.data (-rw-rw-rw-)
|____Forms Sub-directory (dr-xr-xr-x)
| |____download_form.cgi (-r-xr-xr-x)
| |____feedback.cgi (-r-xr-xr-x)
|____Library Sub-directory (dr-xr-xr-x)
| |____cgi-lib.pl (-r--r--r--)
| |____mail-lib.pl (-r--r--r--)
|____Setup_files Sub-directory (dr-xr-xr-x)
| |____download.setup (-r--r--r--)
| |____feedback.setup (-r--r--r--)
|____form_processor.cgi (-r-xr-xr-x)
Databases - This sub-directory is used to hold the data files which store
information submitted by clients. The sub-directory itself must
be readable, writable, and executable by the web server. It
contains two demo files: download.data and feedback.data. Both of
these files must be readable, and writable by the web server and
are made up of database rows separated by the newline character and
delimited by a character defined in the setup file corresponding
to the first part of the filename. That is, feedback.data
corresponds to feedback.setup.
Note: Two sample HTML forms were prepared to be distributed with
this application. One form is used to select a file to download
and the other is a simple feedback form. Each of these forms have
separate dat, setup and HTML files.
Forms - The Forms subdirectory is used to hold two sample HTML forms used
to query a customer for information which can be processed by the
script. The subdirectory must be readable and executable by the
Web server and contains two files: download_form.cgi and
feedback.cgi which must both be readable and executable as well.
These two files are actually perl CGI scripts which simply print
out HTML. The reason that we do not just put HTML forms here is
because on some servers, you are not allowed to incorporate HTML
files in the same directories as CGI scripts...So, for the sake of
simplicity in the demos, we the HTML forms were made out of CGI
scripts.
In fact, you need not use CGI scripts to generate your HTML
forms and you need not store your HTML forms in the Forms directory.
They can go anywhere on your site so long as the setup file
correctly defines their location.
Library - This subdirectory contains two supporting files which are used
by the script to help with processing requests. The subdirectory
must be readable and executable by the web server and both files
must be readable.
cgi-lib.pl - The library file used to read and parse incoming
form data.
mail-lib.pl - The library file used to send mail to the form
admin.
You must define the local path of sendmail at line
42 of this library. You must also take out the "-n"
if you are using an email alias.
If you are using an NT server and cannot use sendmail at
all, you must replace this version with the SMTP version
available at
http://www.eff.org/~erict/Scripts/
Setup_files is a subdirectory containing the setup files used by the
script to process separate forms. Every form processed by this
script MUST have a corresponding setup file which defines how the
form should be processed. The subdirectory itself must be
readable and executable and both demo setup files must be readable
by the web server.
Setup files contains all of the customizable aspects of this
script in the form of several variables and subroutines. Most of
the customizing that you will do (for example creating separate
forms) will be done by modifying this file.
Note: It is essential that you also change two lines in
form_processor.cgi which have hard-coded server-specific
variables.
Firstly, you must change the very first line of the script to
reference the local location of the Perl interpreter. Thus, if
your Perl interpreter is located at "/usr/bin/perl", you must
change the first line to read as follows:
#!/usr/bin/perl
instead of the default line
!/usr/local/bin/perl
Secondly, you "may" have to change line 45 which reads by default
as follows:
require "./Library/cgi-lib.pl";
If you have moved cgi-lib.pl somewhere other than the directory in
which it is distributed, you will have to define the new path on
that line.
The following options are defined in the setup
files.
$should_i_mail determines if the script sends the results of form
submission to the form administrator(s) defined in $email_to. If
set to "yes" it will email, if set to "no" it won't.
$should_i_send_user_email determines if the script will send an
email confirmation to the user who submitted information via the
form. This variable can only be set to yes if the form includes
an input field for client_email such as:
Otherwise, the script will not know where to email the
confirmation to.
$email_of_sender determines who email should be sent from if the
client_email input field is not included in the form.
$email_to is the email address of the administrator who will
receive the results of form submission if $should_i_mail is set to
"yes".
$email_subject is the subject of the email sent to the
administrator if $should_i_mail is set to "yes".
Note: Because the at sign (@) has special meaning to Perl, you
must make sure that all at signs are escaped with a backslash (\).
Thus, erict@eff.org becomes erict\@eff.org. If you are getting a
"document contains no data" error, this is a likely cause.
$url_of_the_form is the URL of the HTML (or CGI) document which
generates the form that this script is required to process.
$location_of_mail_lib is the location of mail-lib.pl on the local
server.
$should_I_append_a_database determines if the script will write
all client-submitted information to a database file. If set to
"yes" the script will do so, "no" it won't.
$location_of_database is the location of the database file that
the script will write to if the above variable is set to "yes".
$database_delimiter is the symbol to be used to delimit the
database. Note, be default the pipe (|) symbol is used to delimit
the database. However, because the pipe symbol has special
meaning to Perl, we must escape it with the backslash (\). Thus,
if you were using a colon (what has no special meaning) to delimit
the database, you would say $database_delimiter = ":"; without the
backslash.
@form_variables is a list of form variables that the script will
expect to see coming in from the form (though some may have no
values). The order in this list determines the order in which
they will be written to the database and sent in the email to the
form administrator. EVERY form input field in your HTML form
MUST be included in this list, or it will not be processed.
%form_variable_name_map is an associative array which maps those
fields with a display name for the email sent to the admin. This
is really just to make the email format nicer looking.
@required_variables is the list of fields that the customer
MUST fill out if the form is to be processed.
$should_user_verify tells the script whether or not it should
display a confirmation screen to the user before it actually
finalizes the processing of the script. Thus, the user has one
last chance to look over what they entered and hot the back button
if they see any mistakes.
required_fields_error_message simply prints out an HTML note to
the user who has not filled out the required fields on a form.
Notice that the subroutine begins first by sending the HTTP header
so that the browser will know to expect HTML from the script. it
also uses the qq operator with the tilde (~) delimiter to delimit
the HTML code to be sent to the browser. because the tilde is
used as a delimiter, you may not include any tildes in the text to
display unless they are escaped with a backslash (\). Thus
http://www.yourdomain.com/~you
must be written as
http://www.yourdomain.com/\~you
The cannot_find_database subroutine is used to send a note to the
user if there is a problem accessing the database. Most likely
reasons for this is a permissions problem or an error in the
definition of the database path in this file.
As we did above, we'll send out the http header and use the qq~
operator.
The html_reply* subroutines determine what is sent to the customer
after she submits the information. Typically they will get some
sort've thank you note as in the case of the feedback.cgi example.
However, in the download example, we will actually send them a
file. Notice that the script goes through and checks to see which
product the user has requested and then uses the "Location" http
header to send the customer to the location of the correct file.
The display_verification_screen subroutine is used to redisplay
the info that the user entered into the form as a final
confirmation. It is important to note that the script must not
only display that info to the user, but include it as hidden
variables which the script will be able to process. This info
MUST be maintained as state info by the HTML form using this
method or else it will be lost. Also, the submit button is created
with the "verified" NAME. It is essential that you leave the NAME
value as verified because the script uses that as a keyword. You
can, however, change the VALUE to anything you want.
form_processor.cgi - is the main script which processes forms. It must be
readable and executable by the web server.
RUNNING THE SCRIPT
This script should be run by pointing your browser to the form which
references form_processor.cgi in the