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!
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 the HTML::Template manpage 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 the HTML::Template manpage for more information about the template syntax.

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();

AUTHOR

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