NAME¶
CGI::Application::Mailform - A simple HTML form to email system
SYNOPSIS¶
## In "mailform.cgi" --
use CGI::Application::Mailform;
# Create a new Mailform instance...
my $mf = CGI::Application::Mailform->new();
# Configure your mailform
$mf->param('MAIL_FROM' => 'webmaster@your.domain');
$mf->param('MAIL_TO' => 'form_recipient@your.domain');
$mf->param('HTMLFORM_REDIRECT_URL' => '/uri/or/url/to/mailform.html');
$mf->param('SUCCESS_REDIRECT_URL' => '/uri/or/url/to/thankyou.html');
$mf->param('FORM_FIELDS' => [qw/name address comments etc/]);
# Optional variables
$mf->param('SMTP_HOST' => 'mail.your.domain');
$mf->param('SUBJECT' => 'New form submission');
$mf->param('ENV_FIELDS' => [qw/REMOTE_ADDR HTTP_USER_AGENT/]);
# Now run...
$mf->run();
exit(0);
## In "mailform.html" --
<form action="mailform.cgi">
<input type="hidden" name="rm" value="submitform">
<!-- Your HTML form input fields here -->
<input type="submit" name="submit">
</form>
## In "thankyou.html" --
<html><body>
<h1>Thanks for your submission! It has been sent.</h1>
</body></html>
DESCRIPTION¶
CGI::Application::Mailform is a reusable and customizable mailform for the web.
It is intentionally simple, and provides very few facilities. What it does do
is provide an easy-to-use, secure system for taking the contents of a HTML
form submission and sending it, via email, to a specified recipient.
This module was created as an example of how to use CGI::Application, a
framework for creating reusable web-based applications. In addition to
providing a simple example of CGI::Application's usage,
CGI::Application::Mailform is also a fully functional application, capable of
running in a production environment.
Just as is the case with any web-application built upon CGI::Application,
CGI::Application::Mailform will run on any web server and operating system
which supports the Common Gateway Interface (CGI). It will run equally well on
Apache as it runs on IIS or the iPlanet server. It will run perfectly well on
UNIX, Linux, Solaris or Windows NT. It will take full advantage of the
advanced capabilities of MOD_PERL. It will probably even run under FastCGI
(although the author has not personally tested it in that environment).
USAGE¶
Once CGI::Application::Mailform has been installed, you must complete the
following steps to create a custom mailform on your website:
1. Create 'mailform.html'
2. Create 'thankyou.html'
3. Create 'mailform.cgi'
Examples of these files are provided in the directory "Examples" which
can be found in the installation tar file for CGI::Application.
The file 'mailform.html' is simply an HTML file which contains your web form.
This is the form whose contents will be sent, via CGI::Application::Mailform,
to the specified recipient's email address.
This file need only contain the basic HTML form. There are two requirements for
this form. First, the "action" attribute of the <form> element
must refer to the CGI instance script ('mailform.cgi') you are about to
create. Second, the form must set a "hidden" form field with the
name "rm" and the value "submitform". This hidden
parameter is what tells the CGI::Application::Mailform application to send the
email message, as opposed to send the user to the HTML form.
For example:
<form action="mailform.cgi">
<input type="hidden" name="rm" value="submitform">
<!-- Your HTML form input fields go here -->
</form>
Your 'mailform.html' may also contain JavaScript to provide form validation. The
CGI::Application::Mailform does not (currently) have any internal form
validation capabilities. As described earlier, this is a very simple system.
If it is necessary to enforce any fields as "required", it is
recommended that JavaScript be used.
NOTE: It is not necessary that your HTML file be called 'mailform.html'. You may
name this file anything you like. The only naming limitation is that the name
of this file should be correctly referenced in your 'mailform.cgi', in the
variable 'HTMLFORM_REDIRECT_URL'.
Create 'thankyou.html'¶
The next file you need to create is your 'thankyou.html' file. This file is the
simplest of all. This is the file to which users will be redirected once they
have successfully submitted their form data. The purpose of this screen is to
inform and assure the user that their form data submission has been
successfully received and processed.
For example:
<html>
<head>
<title>Thank you!</title>
</head>
<body>
<p><h1>Thanks for your submission!</h1></p>
<p>We have received your form, and
we will get back to you shortly.</p>
</body>
</html>
NOTE: It is not necessary that your HTML file be called 'thankyou.html'. You may
name this file anything you like. The only naming limitation is that the name
of this file should be correctly referenced in your 'mailform.cgi', in the
variable 'SUCCESS_REDIRECT_URL'.
The file 'mailform.cgi' is where all the functionality of
CGI::Application::Mailform is configured. This file is referred to as a
"CGI instance script" because it creates an "instance" of
your form. A single website may have as many instance scripts as needed. All
of these instance scripts may use CGI::Application::Mailform. They may each
use a different form (with different fields, etc.) if desired. The ability to
create multiple instances of a single application, each with a different
configuration is one of the benefits of building web-based applications using
the CGI::Application framework.
Your instance script, 'mailform.cgi', must be created in such a way that it is
treated by your web server as an executable CGI application (as opposed to a
document). Generally (on UNIX), this entails setting the "execute
bit" on the file and configuring your web server to treat files ending
".cgi" as CGI applications. Please refer to your particular web
server's manual for configuration details.
Your instance script 'mailform.cgi' must start with the following:
#!/usr/bin/perl -w
use CGI::Application::Mailform;
my $mf = CGI::Application::Mailform->new();
These lines invoke the Perl interpreter, include the CGI::Application::Mailform
module, and instantiate a Mailform object, respectively. (The author assumes
your Perl binary is located at "/usr/bin/perl". If it is not, change
the first line to refer to the correct location of your Perl binary.)
Once you have a Mailform object ($mf), you have to configure the Mailform for
your particular application. This is done by using the
param() method
to set a number of variables. These variables are specified as follows.
REQUIRED VARIABLES
- MAIL_FROM
-
$mf->param('MAIL_FROM' => 'webmaster@your.domain');
This variable specifies the email address from which the email created by
this mailform will appear to be sent. This can be any address you like.
Typically, this will be "webmaster@your.domain". Keep in mind,
this is the address to which a bounce or a reply will be sent if one is
generated as a result of the mailform email. The MAIL_FROM can also be
useful for assisting the recipient of these email messages in
automatically filtering and organizing the submissions they receive.
This variable is required. If not specified, CGI::Application::Mailform will
die() with appropriate errors.
- MAIL_TO
-
$mf->param('MAIL_TO' => 'form_recipient@your.domain');
This variable specifies the email address to which the email created by this
mailform should be sent. This should be the email address of the person to
whom the form contents should be emailed. This person will receive a
reasonably formatted message every time this mailform is submitted.
This variable is required. If not specified, CGI::Application::Mailform will
die() with appropriate errors.
- HTMLFORM_REDIRECT_URL
-
$mf->param('HTMLFORM_REDIRECT_URL' => '/uri/or/url/to/mailform.html');
This variable specifies the URL (or URI) to which the web user should be
redirected before they have submitted the mailform. This should be the
HTML form which the user fills out, the contents of which will be emailed
once they are submitted.
This variable is required. If not specified, CGI::Application::Mailform will
die() with appropriate errors.
- SUCCESS_REDIRECT_URL
-
$mf->param('SUCCESS_REDIRECT_URL' => '/uri/or/url/to/thankyou.html');
This variable specifies the URL (or URI) to which the web user should be
redirected once they have submitted the mailform. Typically, this would be
a "thank you" screen which assures the user that their form
submission has been received and processed.
This variable is required. If not specified, CGI::Application::Mailform will
die() with appropriate errors.
- FORM_FIELDS
-
$mf->param('FORM_FIELDS' => [qw/name address comments etc/]);
This variable specifies the list of HTML form fields which will be processed
and sent via email to the specified recipient. Only the form fields
specified in this list will be put in the email message which is generated
by this mailform and sent to the specified recipient.
The value of this variable must be an array reference. This variable is
required. If not specified, CGI::Application::Mailform will die()
with appropriate errors.
OPTIONAL VARIABLES
- SMTP_HOST
-
$mf->param('SMTP_HOST' => 'mail.your.domain');
This variable specifies the Internet host name (or IP address) of the server
which provides Simple Mail Transfer Protocol (SMTP) services.
CGI::Application::Mailform sends all mail via SMTP using Net::SMTP.
If SMTP_HOST is unspecified, Net::SMTP will use the default host which was
specified when Net::SMTP was installed. If CGI::Application::Mailform is
unable to make an SMTP connection, or successfully send mail via the SMTP
host, it will die() with appropriate errors.
- SUBJECT
-
$mf->param('SUBJECT' => 'New form submission');
This variable specifies the subject line of the email message which is
created by this mailform. The subject is useful to the mailform recipient
in easily recognizing (and possibly filtering) form submissions.
This variable is optional. If not supplied, CGI::Application::Mailform will
set the subject to a reasonable default.
- ENV_FIELDS
-
$mf->param('ENV_FIELDS' => [qw/REMOTE_ADDR HTTP_USER_AGENT/]);
This variable specifies the list of "environment" variables which
will be processed and sent via email to the specified recipient. Only the
environment variables specified in this list will be put in the email
message which is generated by this mailform and sent to the specified
recipient.
Any environment variable which is present in the CGI environment may be
included. Typical variables might be:
AUTH_TYPE
CONTENT_LENGTH
CONTENT_TYPE
GATEWAY_INTERFACE
HTTP_ACCEPT
HTTP_USER_AGENT
PATH_INFO
PATH_TRANSLATED
QUERY_STRING
REMOTE_ADDR
REMOTE_HOST
REMOTE_IDENT
REMOTE_USER
REQUEST_METHOD
SCRIPT_NAME
SERVER_NAME
SERVER_PORT
SERVER_PROTOCOL
SERVER_SOFTWARE
See your web server documentation for a complete list and descriptions of
the available environment variables. The list of environment variables
specified by the CGI protocol can be found at the following URL:
http://hoohoo.ncsa.uiuc.edu/cgi/env.html
The value of this variable must be an array reference. This variable is
optional. If not specified, no environment variables will be included in
the mailform email message.
Finally, you must actually cause your Mailform to be executed by calling the
run() method. Your instance script 'mailform.cgi' should end with the
following lines:
$mf->run();
exit(0);
These lines cause your configured Mailform ($mf) to be executed, and for the
program to cleanly exit, respectively.
NOTE: It is not necessary that your HTML file be called 'mailform.cgi'. You may
name this file anything you like. The only naming limitations are that this
file should be named so that your web server recognizes it as an executable
CGI, and that your 'mailform.html' file specifies your instance script in the
"action" attribute of the <form> element.
All things considered, your CGI instance script will be a very small, simple
file. Unlike other reusable "mailform" scripts, the instance scripts
are specifically intended to be very easy to work with. Essentially, these
instance scripts are "configuration files" for your web-based
application. The structure of instance scripts is a benefit of building
applications based on the CGI::Application framework.
SEE ALSO¶
CGI::Application
AUTHOR¶
Jesse Erlbaum <jesse@erlbaum.net>
LICENSE¶
Copyright (c) 2001, 2002, Jesse Erlbaum <jesse@erlbaum.net>.
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.