1CGI::Application::MailfUosremr(3Cpomn)tributed Perl DocuCmGeIn:t:aAtpipolnication::Mailform(3pm)
2
6 CGI::Application::Mailform - A simple HTML form to email system
7
9 ## In "mailform.cgi" --
10 use CGI::Application::Mailform;
11 # Create a new Mailform instance...
13 my $mf = CGI::Application::Mailform->new();
14 # 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 # 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 # Now run...
28 $mf->run();
29 exit(0);
30 ## 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 ## In "thankyou.html" --
43 <html><body>
44 <h1>Thanks for your submission! It has been sent.</h1>
45 </body></html>
46
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 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 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 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 1. Create 'mailform.html'
74 2. Create 'thankyou.html'
75 3. Create 'mailform.cgi'
76 Examples of these files are provided in the directory "Examples" which
78 can be found in the installation tar file for CGI::Application.
79 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 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 For example:
94 <form action="mailform.cgi">
96 <input type="hidden" name="rm" value="submitform">
97 <!-- Your HTML form input fields go here -->
98 </form>
99 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 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 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 For example:
120 <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 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 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 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 Your instance script 'mailform.cgi' must start with the following:
157 #!/usr/bin/perl -w
159 use CGI::Application::Mailform;
160 my $mf = CGI::Application::Mailform->new();
161 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 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 REQUIRED VARIABLES
174 MAIL_FROM
176 $mf->param('MAIL_FROM' => 'webmaster@your.domain');
177 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 This variable is required. If not specified,
188 CGI::Application::Mailform will die() with appropriate errors.
189 MAIL_TO
191 $mf->param('MAIL_TO' => 'form_recipient@your.domain');
192 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 This variable is required. If not specified,
200 CGI::Application::Mailform will die() with appropriate errors.
201 HTMLFORM_REDIRECT_URL
203 $mf->param('HTMLFORM_REDIRECT_URL' => '/uri/or/url/to/mailform.html');
204 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 This variable is required. If not specified,
211 CGI::Application::Mailform will die() with appropriate errors.
212 SUCCESS_REDIRECT_URL
214 $mf->param('SUCCESS_REDIRECT_URL' => '/uri/or/url/to/thankyou.html');
215 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 This variable is required. If not specified,
222 CGI::Application::Mailform will die() with appropriate errors.
223 FORM_FIELDS
225 $mf->param('FORM_FIELDS' => [qw/name address comments etc/]);
226 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 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 OPTIONAL VARIABLES
238 SMTP_HOST
240 $mf->param('SMTP_HOST' => 'mail.your.domain');
241 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 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 SUBJECT
254 $mf->param('SUBJECT' => 'New form submission');
255 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 This variable is optional. If not supplied,
262 CGI::Application::Mailform will set the subject to a reasonable
263 default.
264 ENV_FIELDS
266 $mf->param('ENV_FIELDS' => [qw/REMOTE_ADDR HTTP_USER_AGENT/]);
267 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 Any environment variable which is present in the CGI environment
275 may be included. Typical variables might be:
276 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 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 http://hoohoo.ncsa.uiuc.edu/cgi/env.html
303 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 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 $mf->run();
313 exit(0);
314 These lines cause your configured Mailform ($mf) to be executed, and
316 for the program to cleanly exit, respectively.
317 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 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
333 CGI::Application
334
336 Jesse Erlbaum <jesse@erlbaum.net>
337
339 Copyright (c) 2001, 2002, Jesse Erlbaum <jesse@erlbaum.net>.
340 This library is free software; you can redistribute it and/or modify it
342 under the same terms as Perl itself.
343perl v5.38.0 2023-07-20 CGI::Application::Mailform(3pm)