FormMail.pl - Handle HTML forms and mail the results
http://server/cgi-path/FormMail.pl?FormURL=relative_form_URL
This program requires Perl version 5.004. It uses the CGI, HTML::Parser and Net::SMTP (part of the libnet library) modules, and parts of the libwww-perl library.
The FormMail program acts differently on being called with the GET and the POST request
method.
When called using the GET request method (like above), it takes as its parameter (named FormURL) a relative URL containing a HTML form, retrieves it, mangles it (this
includes redirecting the FORM ACTION
to itself) and sends it to the client.
When the form is then submitted (with the POST request method),
FormMail checks the values entered against policies layed down in the HTML form
file, and either re-sends the form (inserting already filled out fields
with the values entered), or sends an E-Mail to the address specified in
the FORM ACTION and optionally redirects the browser to another URL.
Commands to direct FormMail's processing are integrated into the HTML form file as comments of the
form <!--!command!parameter-->.
All of the following commands remain in effect until the next such command
is read. An implicit not_required command is assumed at the top of the form (this default is configurable;
see below under $default_is_required).
All input fields up to the next requirement command are marked as required,
i.e. are checked to have a non-empty contents. The
parameter is ignored.
All input fields up to the next requirement command are marked as optional,
i.e. are not checked. The parameter is ignored.
The parameter must have the form name eq value or name ne value.
All input fields up to the next requirement command are marked as required,
i.e. are checked to have a non-empty contents, if the input field name's value is (not) equal to value.
The parameter must have the form name eq value or name ne value.
All input fields up to the next requirement command are marked as optional,
i.e. are not checked, if the input field name's value is (not) equal to value.
parameter must be of the form user@domain.name. It is used for the
From: header field in the E-Mail.
parameter is used as the Subject: header field of the E-Mail.
The contents of parameter is sent with the E-Mail, in front of the list of form field name/value
pairs.
The contents of parameter is sent with the E-Mail, behind the list of form field name/value pairs.
The parameter is the filename of a perl script (residing in FormMail's own directory) which defines a FormMail::process routine. This
routine is called after all parameters have been verified and before the
mail is sent. The routine is called with two parameters: An array reference
containing the field names, and a hash reference containing the values of
the form fields. If FormMail::process wants to insert any new fields
into the mail sent, it can do so by inserting the name into the array, and
the value into the hash. It can signal the outcome of the processing by its
return value: If it returns a false value, the form will be resent, with
the text of the
only_if_process_fails command inserted.
The parameter is the URL that the browser is redirected to if sending the E-Mail was successful.
The parameter is the URL that the browser is redirected to if sending the E-Mail was not successful.
The contents of parameter is sent as text, if FormMail is called with the GET request method (which is the usual way it is called before processing).
The contents of parameter is sent as text on re-sending the form (that is, if FormMail is called with the POST request method - which happens when the form gets submitted), and required
input fields have not been filled in.
The contents of parameter is sent as text on re-sending the form (that is, if FormMail is called with the POST request method - which happens when the form gets submitted), and the process file returned false.
Near the top of FormMail.pl is a configuration section with the following entries:
The IP address or host name of the mail host to try and send the mail to.
A mail address to turn to in case of problems. This should be a mail
address of someone responsible for the site, and is incorporated as a LINK
REV="MADE" tag into the HEADs of all HTML pages sent.
A filename to save the mail to, in case the mailing process failed.
What to assume at the top of a form: required (1) or not_required (0).
If this variable is defined, it is taken as a filename to redirect STDERR to (in append mode).
If this variable is defined, it is taken as a filename to CGI::save the
received form variables to. When debugging interactively, setting the
environment variable FORMMAIL_DEBUG to a true value will cause FormMail
to read the file, and populate parameters passed from it.
The variable FormURL must not be used as a name for a form entry field.
The FORM ACTION must be a mailto URL.
Each entry field in the form must have a NAME attribute.
Each OPTION must have a VALUE attribute, i.e. you can't (yet) use the option's text as the OPTION field's value.
In the program, all values associated with the same form variable name are
concatenated into a newline separated string. So they'd better belong to
the same context (i.e. to the same SELECT or INPUT TYPE=RADIO|CHECKBOX
field).
The parse engine for the (not_)required_if expressions is rather simplistic. So please don't try to abuse it.
Copyright (c) 1999 Martin Vorländer. All rights reserved. This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.
None that I know of... of course, there will be some. I'd appreciate any feedback.
This program relies heavily on the following modules, and owes much to their authors:
CGI by Lincoln D. Stein
HTML::Parser by Gisle Aas
various from the libwww library by Gisle Aas and Martijn Koster
Net::SMTP from the libnet library by Graham Barr
Many thanks also go to the Perl UseNet community and Larry Wall.
0.9 (17-Jan-1998)
Initial version released
1.0 (02-Jan-1998)
Reworked for presentation at the German Perl Workshop 1.0
Martin Vorländer <mv@pdv-systeme.de>