CGI::Application::Mailform(3pm)

1CGI::Application::MailfUosremr(3C)ontributed Perl DocumeCnGtIa:t:iAopnplication::Mailform(3)
2
3
4

NAME

6       CGI::Application::Mailform - A simple HTML form to email system
7

SYNOPSIS

9         ## In "mailform.cgi" --
10         use CGI::Application::Mailform;
11
12         # Create a new Mailform instance...
13         my $mf = CGI::Application::Mailform->new();
14
15         # Configure your mailform
16         $mf->param('MAIL_FROM'   => 'webmaster@your.domain');
17         $mf->param('MAIL_TO'     => 'form_recipient@your.domain');
18         $mf->param('HTMLFORM_REDIRECT_URL' => '/uri/or/url/to/mailform.html');
19         $mf->param('SUCCESS_REDIRECT_URL'  => '/uri/or/url/to/thankyou.html');
20         $mf->param('FORM_FIELDS' => [qw/name address comments etc/]);
21
22         # Optional variables
23         $mf->param('SMTP_HOST'   => 'mail.your.domain');
24         $mf->param('SUBJECT'     => 'New form submission');
25         $mf->param('ENV_FIELDS'  => [qw/REMOTE_ADDR HTTP_USER_AGENT/]);
26
27         # Now run...
28         $mf->run();
29         exit(0);
30
31
32
33         ## In "mailform.html" --
34         <form action="mailform.cgi">
35         <input type="hidden" name="rm" value="submitform">
36         <!-- Your HTML form input fields here -->
37         <input type="submit" name="submit">
38         </form>
39
40
41
42         ## In "thankyou.html" --
43         <html><body>
44           <h1>Thanks for your submission!  It has been sent.</h1>
45         </body></html>
46

DESCRIPTION

48       CGI::Application::Mailform is a reusable and customizable mailform for
49       the web.  It is intentionally simple, and provides very few facilities.
50       What it does do is provide an easy-to-use, secure system for taking the
51       contents of a HTML form submission and sending it, via email, to a
52       specified recipient.
53
54       This module was created as an example of how to use CGI::Application, a
55       framework for creating reusable web-based applications.  In addition to
56       providing a simple example of CGI::Application's usage,
57       CGI::Application::Mailform is also a fully functional application,
58       capable of running in a production environment.
59
60       Just as is the case with any web-application built upon
61       CGI::Application, CGI::Application::Mailform will run on any web server
62       and operating system which supports the Common Gateway Interface (CGI).
63       It will run equally well on Apache as it runs on IIS or the iPlanet
64       server.  It will run perfectly well on UNIX, Linux, Solaris or Windows
65       NT.  It will take full advantage of the advanced capabilities of
66       MOD_PERL.  It will probably even run under FastCGI (although the author
67       has not personally tested it in that environment).
68
69   USAGE
70       Once CGI::Application::Mailform has been installed, you must complete
71       the following steps to create a custom mailform on your website:
72
73         1. Create 'mailform.html'
74         2. Create 'thankyou.html'
75         3. Create 'mailform.cgi'
76
77       Examples of these files are provided in the directory "Examples" which
78       can be found in the installation tar file for CGI::Application.
79
80   Create 'mailform.html'
81       The file 'mailform.html' is simply an HTML file which contains your web
82       form.  This is the form whose contents will be sent, via
83       CGI::Application::Mailform, to the specified recipient's email address.
84
85       This file need only contain the basic HTML form.  There are two
86       requirements for this form.  First, the "action" attribute of the
87       <form> element must refer to the CGI instance script ('mailform.cgi')
88       you are about to create.  Second, the form must set a "hidden" form
89       field with the name "rm" and the value "submitform".  This hidden
90       parameter is what tells the CGI::Application::Mailform application to
91       send the email message, as opposed to send the user to the HTML form.
92
93       For example:
94
95           <form action="mailform.cgi">
96           <input type="hidden" name="rm" value="submitform">
97           <!-- Your HTML form input fields go here -->
98           </form>
99
100       Your 'mailform.html' may also contain JavaScript to provide form
101       validation.  The CGI::Application::Mailform does not (currently) have
102       any internal form validation capabilities.  As described earlier, this
103       is a very simple system.  If it is necessary to enforce any fields as
104       "required", it is recommended that JavaScript be used.
105
106       NOTE:  It is not necessary that your HTML file be called
107       'mailform.html'.  You may name this file anything you like.  The only
108       naming limitation is that the name of this file should be correctly
109       referenced in your 'mailform.cgi', in the variable
110       'HTMLFORM_REDIRECT_URL'.
111
112   Create 'thankyou.html'
113       The next file you need to create is your 'thankyou.html' file.  This
114       file is the simplest of all.  This is the file to which users will be
115       redirected once they have successfully submitted their form data.  The
116       purpose of this screen is to inform and assure the user that their form
117       data submission has been successfully received and processed.
118
119       For example:
120
121           <html>
122           <head>
123               <title>Thank you!</title>
124           </head>
125           <body>
126               <p><h1>Thanks for your submission!</h1></p>
127               <p>We have received your form, and
128               we will get back to you shortly.</p>
129           </body>
130           </html>
131
132       NOTE:  It is not necessary that your HTML file be called
133       'thankyou.html'.  You may name this file anything you like.  The only
134       naming limitation is that the name of this file should be correctly
135       referenced in your 'mailform.cgi', in the variable
136       'SUCCESS_REDIRECT_URL'.
137
138   Create 'mailform.cgi'
139       The file 'mailform.cgi' is where all the functionality of
140       CGI::Application::Mailform is configured.  This file is referred to as
141       a "CGI instance script" because it creates an "instance" of your form.
142       A single website may have as many instance scripts as needed.  All of
143       these instance scripts may use CGI::Application::Mailform.  They may
144       each use a different form (with different fields, etc.) if desired.
145       The ability to create multiple instances of a single application, each
146       with a different configuration is one of the benefits of building web-
147       based applications using the CGI::Application framework.
148
149       Your instance script, 'mailform.cgi', must be created in such a way
150       that it is treated by your web server as an executable CGI application
151       (as opposed to a document).  Generally (on UNIX), this entails setting
152       the "execute bit" on the file and configuring your web server to treat
153       files ending ".cgi" as CGI applications.  Please refer to your
154       particular web server's manual for configuration details.
155
156       Your instance script 'mailform.cgi' must start with the following:
157
158           #!/usr/bin/perl -w
159           use CGI::Application::Mailform;
160           my $mf = CGI::Application::Mailform->new();
161
162       These lines invoke the Perl interpreter, include the
163       CGI::Application::Mailform module, and instantiate a Mailform object,
164       respectively.  (The author assumes your Perl binary is located at
165       "/usr/bin/perl".  If it is not, change the first line to refer to the
166       correct location of your Perl binary.)
167
168       Once you have a Mailform object ($mf), you have to configure the
169       Mailform for your particular application.  This is done by using the
170       param() method to set a number of variables.  These variables are
171       specified as follows.
172
173       REQUIRED VARIABLES
174
175       MAIL_FROM
176             $mf->param('MAIL_FROM' => 'webmaster@your.domain');
177
178           This variable specifies the email address from which the email
179           created by this mailform will appear to be sent.  This can be any
180           address you like.  Typically, this will be "webmaster@your.domain".
181           Keep in mind, this is the address to which a bounce or a reply will
182           be sent if one is generated as a result of the mailform email.  The
183           MAIL_FROM can also be useful for assisting the recipient of these
184           email messages in automatically filtering and organizing the
185           submissions they receive.
186
187           This variable is required.  If not specified,
188           CGI::Application::Mailform will die() with appropriate errors.
189
190       MAIL_TO
191             $mf->param('MAIL_TO' => 'form_recipient@your.domain');
192
193           This variable specifies the email address to which the email
194           created by this mailform should be sent.  This should be the email
195           address of the person to whom the form contents should be emailed.
196           This person will receive a reasonably formatted message every time
197           this mailform is submitted.
198
199           This variable is required.  If not specified,
200           CGI::Application::Mailform will die() with appropriate errors.
201
202       HTMLFORM_REDIRECT_URL
203             $mf->param('HTMLFORM_REDIRECT_URL' => '/uri/or/url/to/mailform.html');
204
205           This variable specifies the URL (or URI) to which the web user
206           should be redirected before they have submitted the mailform.  This
207           should be the HTML form which the user fills out, the contents of
208           which will be emailed once they are submitted.
209
210           This variable is required.  If not specified,
211           CGI::Application::Mailform will die() with appropriate errors.
212
213       SUCCESS_REDIRECT_URL
214             $mf->param('SUCCESS_REDIRECT_URL' => '/uri/or/url/to/thankyou.html');
215
216           This variable specifies the URL (or URI) to which the web user
217           should be redirected once they have submitted the mailform.
218           Typically, this would be a "thank you" screen which assures the
219           user that their form submission has been received and processed.
220
221           This variable is required.  If not specified,
222           CGI::Application::Mailform will die() with appropriate errors.
223
224       FORM_FIELDS
225             $mf->param('FORM_FIELDS' => [qw/name address comments etc/]);
226
227           This variable specifies the list of HTML form fields which will be
228           processed and sent via email to the specified recipient.  Only the
229           form fields specified in this list will be put in the email message
230           which is generated by this mailform and sent to the specified
231           recipient.
232
233           The value of this variable must be an array reference.  This
234           variable is required.  If not specified, CGI::Application::Mailform
235           will die() with appropriate errors.
236
237       OPTIONAL VARIABLES
238
239       SMTP_HOST
240             $mf->param('SMTP_HOST' => 'mail.your.domain');
241
242           This variable specifies the Internet host name  (or IP address) of
243           the server which provides Simple Mail Transfer Protocol (SMTP)
244           services.  CGI::Application::Mailform sends all mail via SMTP using
245           Net::SMTP.
246
247           If SMTP_HOST is unspecified, Net::SMTP will use the default host
248           which was specified when Net::SMTP was installed.  If
249           CGI::Application::Mailform is unable to make an SMTP connection, or
250           successfully send mail via the SMTP host, it will die() with
251           appropriate errors.
252
253       SUBJECT
254             $mf->param('SUBJECT' => 'New form submission');
255
256           This variable specifies the subject line of the email message which
257           is created by this mailform.  The subject is useful to the mailform
258           recipient in easily recognizing (and possibly filtering) form
259           submissions.
260
261           This variable is optional.  If not supplied,
262           CGI::Application::Mailform will set the subject to a reasonable
263           default.
264
265       ENV_FIELDS
266             $mf->param('ENV_FIELDS'  => [qw/REMOTE_ADDR HTTP_USER_AGENT/]);
267
268           This variable specifies the list of "environment" variables which
269           will be processed and sent via email to the specified recipient.
270           Only the environment variables specified in this list will be put
271           in the email message which is generated by this mailform and sent
272           to the specified recipient.
273
274           Any environment variable which is present in the CGI environment
275           may be included.  Typical variables might be:
276
277                   AUTH_TYPE
278                   CONTENT_LENGTH
279                   CONTENT_TYPE
280                   GATEWAY_INTERFACE
281                   HTTP_ACCEPT
282                   HTTP_USER_AGENT
283                   PATH_INFO
284                   PATH_TRANSLATED
285                   QUERY_STRING
286                   REMOTE_ADDR
287                   REMOTE_HOST
288                   REMOTE_IDENT
289                   REMOTE_USER
290                   REQUEST_METHOD
291                   SCRIPT_NAME
292                   SERVER_NAME
293                   SERVER_PORT
294                   SERVER_PROTOCOL
295                   SERVER_SOFTWARE
296
297           See your web server documentation for a complete list and
298           descriptions of the available environment variables.  The list of
299           environment variables specified by the CGI protocol can be found at
300           the following URL:
301
302               http://hoohoo.ncsa.uiuc.edu/cgi/env.html
303
304           The value of this variable must be an array reference.  This
305           variable is optional.  If not specified, no environment variables
306           will be included in the mailform email message.
307
308       Finally, you must actually cause your Mailform to be executed by
309       calling the run() method.  Your instance script 'mailform.cgi' should
310       end with the following lines:
311
312           $mf->run();
313           exit(0);
314
315       These lines cause your configured Mailform ($mf) to be executed, and
316       for the program to cleanly exit, respectively.
317
318       NOTE:  It is not necessary that your HTML file be called
319       'mailform.cgi'.  You may name this file anything you like.  The only
320       naming limitations are that this file should be named so that your web
321       server recognizes it as an executable CGI, and that your
322       'mailform.html' file specifies your instance script in the "action"
323       attribute of the <form> element.
324
325       All things considered, your CGI instance script will be a very small,
326       simple file.  Unlike other reusable "mailform" scripts, the instance
327       scripts are specifically intended to be very easy to work with.
328       Essentially, these instance scripts are "configuration files" for your
329       web-based application.  The structure of instance scripts is a benefit
330       of building applications based on the CGI::Application framework.
331

AUTHOR

336       Jesse Erlbaum <jesse@erlbaum.net>
337

LICENSE

339       Copyright (c) 2001, 2002, Jesse Erlbaum <jesse@erlbaum.net>.
340
341       This library is free software; you can redistribute it and/or modify it
342       under the same terms as Perl itself.
343
344
345
346perl v5.30.1                      2020-01-29     CGI::Application::Mailform(3)

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

AUTHOR

LICENSE