NAME

CGI::Application::MailPage - module to allow users to send HTML pages to friends.

SYNOPSIS

use CGI::Application::MailPage;
my $mailpage = CGI::Application::MailPage->new(
               PARAMS => { document_root => '/home/httpd', 
                           smtp_server => 'smtp.foo.org' });
$mailpage->run();

DESCRIPTION

CGI::Application::MailPage is a CGI::Application module that allows users to send HTML pages to their friends. This module provides the functionality behind a typical "Mail This Page To A Friend" link.

To use this module you need to create a simple "stub" script. It should look like:

#!/usr/bin/perl
use CGI::Application::MailPage;
my $mailpage = CGI::Application::MailPage->new(
               PARAMS => { 
                           document_root => '/home/httpd', 
                           smtp_server => 'smtp.foo.org',
                         },
             );
$mailpage->run();

You'll need to replace the "/home/httpd" with the real path to your document root - the place where the HTML files are kept for your site. You'll also need to change "smtp.foo.org" to your SMTP server.

Put this somewhere where CGIs can run and name it something like mailpage.cgi. Now, add a link in the pages you want people to be able to send to their friends that looks like:

<A HREF="mailpage.cgi">mail this page to a friend</A>

This gets you the default behavior and look. To get something more to your specifications you can use the options described below.

OPTIONS

CGI::Application modules accept options using the PARAMS arguement to new(). To give options for this module you change the new() call in the "stub" shown above:

my $mailpage = CGI::Application::MailPage->new(
                   PARAMS => {
                               document_root => '/home/httpd',
                               smtp_server => 'smtp.foo.org',
                               use_page_param => 1,
                             }
                );

The use_page_param option tells MailPage not to use the REFERER header to determine the page to mail. See below for more information about use_page_param and other options.

document_root (required)

This parameter is used to specify the document root for your server - this is the place where the HTML files are kept. MailPage needs to know this so that it can find the HTML files to email.
smtp_server (required)

This must be set to an SMTP server that MailPage can use to send mail. Future versions of MailPage may support other methods of sending mail, but for now you'll need a working SMTP server.
use_page_param

By default MailPage uses the REFERER header to determine the page that the user wants to mail to their friends. This doesn't always work right, particularily on very old browsers. If you don't want to use REFERER then you can set this option and write your links to the application as:
```
<A HREF="mailpage.cgi?page=http://host/page.html">mail page</A>
```
You'll have to replace http://host/page.html with the url for each page you put the link in. You could cook up some Javascript to do this for you, but if the browser has working Javascript then it probably has a working REFERER!

The value of 'page' doesn't have to be a full url, but could be relative to the web root. For instance this would work as well:
```
<A HREF="mailpage.cgi?page=/page.html">mail page</A>
```
email_subject

The default subject of the email sent from the program. Defaults to empty, requiring the user to enter a subject.
form_template

This application uses HTML::Template to generate its HTML pages. If you would like to customize the HTML you can copy the default form template and edit it to suite your needs. The default form template is called 'form.tmpl' and you can get it from the distribution or from wherever this module ended up in your @INC. Pass in the path to your custom template as the value of this parameter.

See HTML::Template for more information about the template syntax.
thanks_template

The default "Thanks" page template is called 'thanks.tmpl' and you can get it from the distribution or from wherever this module ended up in your @INC. Pass in the path to your custom template as the value of this parameter.

See HTML::Template for more information about the template syntax.
email_template

The default email template is called 'email.tmpl' and you can get it from the distribution or from wherever this module ended up in your @INC. Pass in the path to your custom template as the value of this parameter.

See HTML::Template for more information about the template syntax.
error_template

The default template to display errors is called 'error.tmpl' and you can get it from the distribution or from wherever this module ended up in your @INC. Pass in the path to you custom template as the value of this parameter.

read_file_callback

You can provide a subroutine reference that will be called when MailPage needs to open an HTML file on your site. This can used to resolve complex aliasing problems or to perform any desired manipulation of the HTML text. The called subroutine recieves one arguement, the name of the file to be opened. It should return the text of the file. Here's an example that changes all 'p's to 'q's in the text of the files:

#!/usr/bin/perl -w
use CGI::Application::MailPage;

sub p_to_q {
  my $filename = shift;
  open(FILE, $filename) or die;

  my $buffer;
  while(<FILE>) {
    s/p/q/g;
    $buffer .= $_;
  }
 
  return $buffer;
}

my $mailpage = CGI::Application::MailPage->new(
               PARAMS => { 
                           document_root => '/home/httpd', 
                           smtp_server => 'smtp.foo.org',
                           read_file_callback => \&p_to_q,
                         },
             );
$mailpage->run();

acceptable_domains

You may provide a list (array ref) of domains that are acceptable for this mailpage instance to send out in the emails. This prevents spammers, etc from using your mailpage to send out pages of advertisements, etc. If you give any values to this list, all 'page' urls that are being sent must either be relative or must be in your list of acceptable domains.
remote_fetch

If this is true, then MailPage will try and perform a remote fetch of the page using LWP instead of looking on the local filesystem for that page.
extra_tmpl_params

If this value is a hash ref, then it will be combined with the parameters generated by MailPage for each template. The values in your hash will override those created by MailPage. The resulting hash will be passed to the template in question. This gives even more flexibility in making the mailpage section look just like the rest of your site. It is your responsibility to make sure that these parameters will be in the format that HTML::Template is expecting.
max_emails_per_request

This is an integer value which limits the number of email addresses that each request is allowed to send to. This option is useful to limit your server's potential to aid spammers in their nasty work.
max_emails_per_hour

This is an integer value which limits the number of emails that allowed to be sent in an hour. MailPage will use a file (specified by max_emails_per_hour_file) to keep track of how many have been sent for each hour. If you use this option, make sure that this location is readable and writeable by the process in question. This option is useful to limit your server's potential to aid spammers in their nasty work.
max_emails_per_hour_file

This is the name of the file used by max_emails_per_hour. It must be present if you are using max_emails_per_hour.
validation_profile

This is a validation profile structure for use by Data::FormValidator for validating user input. This profile is merged with the default profile and will override any existing rules. This allows you to customize the validation for all, or some of the fields. See "INPUT VALIDATION" for more details.

INPUT VALIDATION

MailPage uses Data::FormValidator to validate the input the user fills in when presented with the email information form. By default the following validation rules are used:

name

Required. Can only contain word characters (\w), apostrophes ('), hyphens (-), and open or closed parenthesis, commas (,) and periods (.) with a maximum length of 50 characters

from_email

Required. Must be a valid email address.

to_emails

Required. A list of email addresses separated by whitespace or commas. All email addresses must be valid with at most max_emails_per_request individual addresses.

subject

Required. Can only contain word characters (\w), apostrophes ('), hyphens (-), and open or closed parenthesis, commas (,), periods (.), question marks (?) and exclamation points (!) with a maximum length of 50 characters

Required.

note

An optional text to send in the email. Can contain anything but a NULL byte with a maximum length of 250 characters.

format

Required. Must be one of the following values:

both_attachment
html
html_attachment
text
text_attachment
url

page

Can contain any characters except new lines (\n) or NULL bytes with a maximum length of 256 characters.

Each field is untainted, so it can be safely processed. You can customize these rules with the validation_profile parameter.

Error Messages

MailPage will pass flags for each error message into the template to be used as the template sees fit. The following error messages are created for each field:

missing_$field: If a required field is not present.
any_missing: If any required field is not present.
invalid_$field: If a field is present but fails validation.
any_invalid: If any field fails validation
error_$field_name: If a field is not present or fails the validation
any_errors: If any field is not present or fails the validation

AUTHOR

Co-maintainer Michael Peters (mpeters@plusthree.com).

Questions, bug reports and suggestions can be sent to the CGI::Application mailing list. You can subscribe by sending a blank message to cgiapp-subscribe@lists.vm.com. See you there!

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)