Form Mailer with Attachments 5.1
| ||||||||||||||||||
|
||||||||||||
|
||||||||||||
 |
||||||||||||
Attachment supproted FormMailer Users Guide
- Introduction
- Requirements
- Configuration
- Installation
- Processing multiple Forms
- E-mail Notifications (authorizing Recipients)
- Carbon Copy Recipients
- Hidden fields in e-mail notifications
- Form tag requirements
- Uploading multiple files from Web Forms
- Maximum size of file uploads
- Defining acceptable file types
- Requiring Form fields be filled in
- Thank you and Error redirect pages
- Script Modifications
Introduction
Thank you for choosing Form Mailer with Attachments. This is a simple but robust program for delivering Form submissions to you via e-mail. The power of this program is that it EASILY allows you to incorporate file attachments for e-mail delivery and website Form file uploads.
To Top
Requirements
This program requires a UNIX, Linux, Mac or Windows server running Perl 5 or later with the CGI.pm module installed.
To Top
Configuration
Before you can install this program, there are three configuration items you must first address.
Path To Perl
All CGI programs written in Perl must start with a line that tells the web server where to look for the Perl interpreter (rarely required on Windows Servers). This means the very first line of the afm.cgi file MUST be the Path to Perl. Here are some examples of the common paths to Perl:
#!/usr/lib/perl
#!/usr/bin/perl
#!/usr/local/bin/perl
This program was shipped with a default path of: #!/usr/bin/perl
After setting the path to Perl, read through the available settings and set appropriately. Your Host's support/FAQ pages should inform you of correct setting paths. If the required information can not be found on your Website Host's support/FAQ pages then you should contact your System Administrator or your Website Host's Support Dept. for the correct values.
The default values shipped with the Script are usually sufficient to get the Script running. You just need to enter your e-mail address to receive notifications. If you're not sure what to enter in the $dir variable which is where any file uploads will be stored, leave it as is and run the Script after you've followed the installation instructions. The Script will print your server's correct path.
To Top
Installation
To install this program, you must have an FTP client and be familiar with how to use its basic functions. If your not sure how to achieve any of the stated functions or commands with your FTP client, please refer to our tutorial on installation and on using FTP clients at:
http://www.perlservices.net/en/faq/installation.shtml
Here are the installation steps:
1. Open your FTP client and connect to your web space.
2. Making sure your FTP client is set to transfer cgi files in ASCII mode and not binary mode, transfer the afm.cgi file to your cgi-bin.
3. CHMOD afm.cgi to 755 (rwx-rx-rx).
4. Create a Form in a regular HTML document (or use the included upload.html file) and point the Form's action attribute to afm.cgi Script. If using your own custom Form, be sure to use the following attributes in your Form tag :
method="post" and enctype="multipart/form-data"
Failing to include the above attributes will result in failed file uploads. Here's an example Form tag.
<form action="/cgi-bin/afm.cgi" method="post" enctype="multipart/form-data">
The above tag will work on any domain or server as long as the afm.cgi file is in your cgi-bin folder.
To Top
Processing multiple Forms
One copy of AFM can be employed to process multiple Forms, each with disparate configuration and functionality settings. However this can only be achieved by configuring each From from within the Form itself using hidden fields. Hidden Form fields take precedence over the Script's settings. This allows you to modify your Forms rather than the Script to control functionality. For security reasons, not all settings found within the Script can be configured from within Form.
Only the following Script configuration settings can be defined in your Forms :
All other Script configured settings apply to all Forms connected to the Script.
To Top
E-mail Notifications (authorizing Recipients)
Recipients of e-mail notification can be hard coded to prevent spam and unwanted submissions. Recipients can be defined in one of the following two ways:
- Hard code the Recipient's e-mail address in to the Script's $notify setting found on line 54 or
- Hard code the intended Recipient's e-mail address in to your Form in a field named emailto as in
<input type="Hidden" name="emailto" value="you@yourserver.com">
This can also be converted to a select menu or radio buttons enabling your Visitors to direct their message to one of the available Recipients, as in
<select name="emailto">
<option value="you@yourserver.com"> Tech Support
<option value="me@yourserver.com"> Billing and Accounts
<option value="bea@yourserver.com"> Website Feedback
</select>
or
<input type="Radio" name="emailto" value="you@yourserver.com">Tech Support
<input type="Radio" name="emailto" value="me@yourserver.com">Billing and Accounts
<input type="Radio" name="emailto" value="bea@yourserver.com">Website Feedback
Of course this later method leaves you, as well as others, susceptible to spam abuse. Which ever method you choose to use, we strongly suggest you make use of the security feature which prevents hackers from using your website to deliver mass spam mailings. On line 214 of the Script, in the @recipients array, you can define the authorized Recipients of any e-mail sent by this Script. Enter either the full e-mail address of authorized Recipients or domain names beginning with the @symbol. For example, if you have AFM processing two Forms and you wanted one Form to send mail to form_one@aol.com, and the other Form to send mail to a number of staff accounts on your ACME.com website, you would define the @recipients as such :
@recipients = qw~
form_one@aol.com
@ACME.com
~;
Notes:
- This security measure is only invoked if you define some Recipients. If the @recipients array is left blank, no check takes place.
- If you're adding your e-mail addresses to hidden Form fields, you're vulnerable to e-mail address harvesters which scour the web collecting e-mail addresses to spam.
To Top
Carbon Copy Recipients
A Carbon Copy of notification e-mail sent to the Recipient defined in either $notify or the emailto Form field can also be sent to a second Recipient. The CC Recipient is also defined as the main Recipient :
- Hard code the CC Recipient's e-mail address in to the Script's $notifyCC setting found on line 73 or
- Hard code the CC Recipient's e-mail address in to your Form in a field named emailtocc as in
<input type="Hidden" name="emailto" value="you@yourserver.com">
To Top
Hidden fields and the e-mail message
AFM utilizes hidden fields as well as hard coded configuration settings. When the Form is submitted those hidden fields would normally be placed in the e-mail along with the rest of the Form contents. However, we've included a function to prevent any unwanted fields from being printed in e-mail notifications. In the Script, on line 284, you will find an array named @hidden. AFM program was shipped with the Script's default hidden fields already defined. You can add any additional hidden or invaluable fields your Form incorporates to this list. List the each field name on it's own line as such :
@hidden = qw~
subject
emailto
required
redirect
requirefile
redirect_bademail
redirect_general_error
redirect_required
redirect_oversize
redirect_invalid
redirect_nodata
redirect_hijack
redirect_unauth
~;
To Top
Form Tag
Each one of your Forms should have the following Form tag. Without the correct value in the enctype attribute, any File uploads will fail with a 0kb size.
<form action="/cgi-bin/afm.cgi" method="post" enctype="multipart/form-data">
The action should point to your copy of the afm.cgi Script. That is, the folder you uploaded afm.cgi to followed by the Script file name.
To Top
Uploading multiple files from Web Forms
Your Forms can include as many file upload fields as you like. This is done by using the "file" type of field and naming it appropriately. Each file upload field can only upload one file, you cannot "select all". AFM requires file upload fields be named "FILE" in uppercase, followed by a unique number. Some valid names for file upload field names are:
FILE1, FILE2, FILE3, FILE4, FILE5, FILE6, FILE7, FILE55
Here is the tag to add one upload field to your Form :
<input type="file" name="FILE1" size=30>
Note that the name attribute "FILE" must be in uppercase letters.
<input type="file" name="FILE1">
<input type="file" name="FILE2">
<input type="file" name="FILE3">
<input type="file" name="FILE4">
<input type="file" name="FILE55">
To Top
Maximum size of file uploads
AFM ships with a default value of 250 assigned to the $max file size variable. Found on line 131 of the Script, the $max specifies the maximum kilobyte size of each individual file uploaded via your Forms. You can set this value as high as you like, but keep in mind your server's configuration file has ultimate control of this setting.
AFM's upload technology has, on a regular basis, successfully uploaded files larger than 1 Gigabyte. That's larger than the entire Windows XP® Operating system. As long as there's a live connection between the Client and Server, sufficient space is available on the server and your Web Server's configuration file has no limit on the temp upload directory and no limit on the length of time a CGI Script can be run, a file larger than your hard drive could theoretically be uploaded.
If the permitted size is in the MB range, multiply the number of MB allowed by 1024 to get the equivalent KB figure. 1 MB is equal to 1024 KB.
To Top
Defining acceptable file types
AFM allows you to specify the types of files that you consider to be safe and acceptable for transfer. On line 226 of the Script, you will find the @types array. This is where you specify the extension of any type of file you will accept as part of the Form submission. For example, if you want to accept only MS Word® and PDF documents, then you would add "doc" and "pdf" to the list, each extension listed on it's own line, as such :
@types = qw~
doc
~;
Remember to add only one extension per line with no spaces, do not include the period, case is ignored. Use the keyword "ALL" in uppercase and without quotes to accept all file types. Remember also, to include similar and associated file extensions to those you're accepting, as in : htm html shtml shtm
To Top
Requiring Form fields be filled in
If you need specific information from your Visitors, you can set those Form fields as required fields. That is, the Form will not be processed unless your Visitors enter a value or make a selection for those fields. To set specific fields as required, you include a hidden Form field named required within your Form. It's value is a comma separated list of the names of the fields which are required. This list must not contain any spaces, so if some of your required field names have spaces, you must rename them. Use underscores rather than spaces. For example, if you had the following three fields for which you required an answer :
<input type="text" name="email">
<input type="text" name="Age">
<input type="text" name="Your_Name">
then you would specify these as required fields using the following hidden field in your Form :
<input type="hidden" name="required" value="email,Age,Your_Name">
To Top
Thank you and Error redirect pages
AFM allows you to specify a distinct redirect page based on the Script's processed results. Note that you can set these as global defaults within the Script that apply to all Forms processed by AFM, or by using a hidden tag of the same name within your Forms to direct specific Forms to specific pages. The Script's redirect settings begin on line 240. All URLs, whether in Form fields or in the Script, must begin with http. An example of each redirects setting follows, the page you're redirecting the Visitor to may be named as you wish, so long as they actually exist :
Unexpected Error encountered
$redirect_general_error = qq~http://www.you.com/error.html~;
<input type="hidden" name="redirect_general_error" value="http://www.you.com/error.html">
Setting the global variable or the hidden Form field will redirect the Visitor to the specified page when an unexpected error is encountered by the Script. If this occurs remove all the redirect settings from the Form and from the Script and allow the Script to return a more descriptive error.
Files required but not uploaded
$redirect_nofiles = qq~http://www.you.com/missing_files.html~;
<input type="hidden" name="redirect_nofiles" value="http://www.you.com/missing_files.html">
Setting the global variable or the hidden Form field will redirect the Visitor to the specified page when no files were selected by the Visitor and you have set the $requirefile setting on line 173 of the Script or in your Form to Yes.
Required fields missed
$redirect_nodata = qq~http://www.you.com/missing.html~;
<input type="hidden" name="redirect_nodata" value="http://www.you.com/missing.html">
Setting the global variable or the hidden Form field will redirect the Visitor to the specified page upon a successful Form submission. If you do not specify either of these then a generic Thank you page will be displayed.
Invalid e-mail address entered
$redirect_bademail = qq~http://www.you.com/bademail.html~;
<input type="hidden" name="redirect_bademail" value="http://www.you.com/bademail.html">
Setting the global variable or the hidden Form field will redirect the Visitor to the specified page if they entered an e-mail address in an invalid format. Note that this error check is only invoked if you have a field in your Form named email in lowercase and you have set it as a required field.
File upload is too large
$redirect_oversize = qq~http://www.you.com/oversized.html~;
<input type="hidden" name="redirect_oversize" value="http://www.you.com/oversized.html">
Setting the global variable or the hidden Form field will redirect the Visitor to the specified page when they attempt to upload a file that is larger than you configured the Script to allow. If you do not specify either of these then a generic warning message will be displayed.
File upload type not permitted
$redirect_invalid = qq~http://www.you.com/invalid.html~;
<input type="hidden" name="redirect_invalid" value="http://www.you.com/invalid.html">
Setting the global variable or the hidden Form field will redirect the Visitor to the specified page when they attempt to upload a file which you have not defined as an acceptable file type. If you do not specify either of these then a generic warning message will be displayed.
Script is possibly being hi-jacked
$redirect_hijack = qq~http://www.you.com/hijack.html~;
<input type="hidden" name="redirect_hijack" value="http://www.you.com/hijack.html">
Setting the global variable or the hidden Form field will redirect the Visitor to the specified page when they attempt to execute the Script from a Form which does not reside on your server. This condition is determined by the value you have set (if any) in the $domain variable on line 194 of the Script checked against the referring URL. Note some of your Visitors may unknowingly have the "referrer" cloaked which would prevent them From being able to submit the Form at all.
Script is being hijacked Form mass spam mailing
$redirect_unauth = qq~http://www.you.com/unauth.html~;
<input type="hidden" name="redirect_unauth" value="http://www.you.com/unauth.html">
Setting the global variable or the hidden Form field will redirect the Visitor to the specified page when they attempt to use it to send e-mail to Recipients not specified by you in the @recipients array on line 214 of the Script. Note that this error check is only invoked if you have defined authorized Recipients in the @recipients array, which is strongly recommended.
Successful Form submission
$redirect = qq~http://www.you.com/success.html~;
<input type="hidden" name="redirect" value="http://www.you.com/success.html">
Setting the global variable or the hidden Form field will redirect the Visitor to the specified page upon a successful Form submission. If you do not specify a value here, a simple generic Thank you message and page will be displayed. If you have switched on the $print_contents variable on line 152, your Upload Directory's contents will be printed as a list of clickable hyper-links.
To Top
Script Modifications
This is a very simple program and is very easy to modify if you have a passing familiarity with Perl. However if you require modifications beyond your capabilities, we can modify this program to suit your needs at our standard programming rate and can suggest another suitable Script. Please do not ask for free modifications on this program. Even if we "just change that wording" a minimum charge applies.
To Top