
Here are some examples of different ways to use the TFmail
CGI script.

TFMAIL INSTALLATION

All of the following examples work with a single TFmail
instalation, as follows:

The directory /home/tfmail/ on a UNIX web server is set
aside for files related to TFmail.

The following files from the TFmail.pl archive (which is
available from http://nms-cgi.sourceforge.net/scripts.shtml)
are installed on the server under the /home/tfmail/
directory.

  NMSTreq.pm   - installed in /home/tfmail/lib/
  MIME_Lite.pm - installed in /home/tfmail/lib/
  spage.trt    - installed in /home/tfmail/cfg/
  email.trt    - installed in /home/tfmail/cfg/

The CGI script itself, TFmail.pl, is installed in the
server's cgi-bin directory.  The configuration section at
the top of the script reads as follows:

  # USER CONFIGURATION SECTION
  # --------------------------
  # Modify these to your own settings, see the README file
  # for detailed instructions.

  use constant DEBUGGING      => 0;
  use constant LIBDIR         => '/home/tfmail/lib';
  use constant MAILPROG       => '/usr/lib/sendmail -oi -t';
  use constant POSTMASTER     => 'tfmail-postmaster@cleaton.net';
  use constant CONFIG_ROOT    => '/home/tfmail/cfg';
  use constant MAX_DEPTH      => 0;
  use constant CONFIG_EXT     => '.trc';
  use constant TEMPLATE_EXT   => '.trt';
  use constant ENABLE_UPLOADS => 0;
  use constant USE_MIME_LITE  => 1;
  use constant LOGFILE_ROOT   => '';
  use constant LOGFILE_EXT    => '.log';
  use constant CHARSET        => 'iso-8859-1';

  # USER CONFIGURATION << END >>
  # ----------------------------
  # (no user serviceable parts beyond here)
   

EXMAPLE 1 - BASIC

This example sets up a simple form to submit to the address
tfmail-basic@cleaton.net.  The server side configuration
file for this example is /home/tfmail/cfg/basic.trc, which
has the following contents:


%% NMS configuration file %%
#
# basic.trc - A basic example of TFmail setup and
# configuration.
#

#
# recipient: the email address(s) to which TFmail should
# send the results of the form submission.
#
recipient: tfmail-basic@cleaton.net

#
# subject: the subject line for the e-mail
#
subject: TFmail example - basic

#
# End of basic.trc
#
###############################################


The HTML form for this example is:


<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
 <head>
  <title>TFmail example</title>
  <link rel="stylesheet" type="text/css" href="/css/nms.css" />
  <style>
    h1.title {
                text-align : center;
             }
  </style>
 </head>
 <body>
  <h1 class="title">TFmail example</h1>
  <p>Please fill in this form</p>
  <form method="post" action="/cgi-bin/TFmail.pl">
   <input type="hidden" name="_config" value="basic" />
   <table>
    <tr>
     <td>Your name:</td>
     <td><input type="text" name="name" /></td>
    </tr>
    <tr>
     <td>Your age:</td>
     <td><input type="text" name="age" /></td>
    </tr>
    <tr>
     <td>Your phone number:</td>
     <td><input type="text" name="phone" /></td>
    </tr>
    <tr>
     <td>Some comments:</td>
     <td><textarea name="comments" cols="80" rows="6"></textarea></td>
    </tr>
   </table>
   <p><input type="submit" value="Send Comments" /></p>
  </form>
  <hr size="1" width="75%" />
  <p align="center">
   <font size="-1">
    <a href="http://nms-cgi.sourceforge.net/">TFmail</a>
     &copy; 2002 London Perl Mongers
   </font>
  </p>
 </body>
</html>


The hidden "_config" input in the HTML form with a value of "basic"
tells TFmail.pl to read the configuration from the configuration
file /home/tfmail/cfg/basic.trc 

There is a test page for this example (with the TFmail.pl script
modified so that no mail will really be sent) at:

   http://cleaton.net/tfmail/basic.html


EXMAPLE 2 - CUSTOM

Now we extend example 1 by taking control of the layout of the
e-mail body and the HTML success page that the form generates.

The server side configuration file for this example is
/home/tfmai/cfg/custom.trc, which has the following contents:


%% NMS configuration file %%
#
# custom.trc - A basic example of TFmail setup and
# configuration, with the success page and e-mail body
# customised to suit the form.
#

#
# recipient: the email address(s) to which TFmail should
# send the results of the form submission.
#
recipient: tfmail-custom@cleaton.net

#
# subject: the subject line for the e-mail
#
subject: tfmail example - custom

#
# For this example, we use customised template files to
# allow us some extra control over the layout of the
# success page and e-mail.
email_template:        custom_email
success_page_template: custom_spage

#
# End of custom.trc
#
###############################################


The template file that sets the layout of the email body is
/home/tfmail/cfg/custom_email.trt, which has the following
contents:


%% NMS email template file %%
This is a TFmail form submission.  The input values were as
follows:

{= FOREACH input_field =}
Input "{= name =}" had value "{= value =}"
{= END =}

-------------------------------------------------------------

IP address of remote user: {= env.REMOTE_ADDR =}
User Agent:              : {= env.HTTP_USER_AGENT =}
Referer:                 : {= env.HTTP_REFERER =}


The template file that sets the layout of the success page is
/home/tfmail/cfg/custom_spage.trt, which has the following
contents:


%% NMS html template file %%
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Thank You</title>
    <link rel="stylesheet" type="text/css" href="/css/nms.css" />
    <style>
       h1.title {
                   text-align : center;
                }
    </style>
  </head>
  <body>
    <h1 class="title">Thank You</h1>
    <p>This is what you submitted on {= date =}</p>
    <table border="1" align="center">
{= FOREACH input_field =}
    <tr>
     <td><b>{= name =}</b></td>
     <td>{= value =}</td>
    </tr>
{= END =}
    </table>
    <hr size="1" width="75%" />
  </body>
</html>


The HTML form for this example is the same as example 1, but with
the value of the "_config" input changed from "basic" to "custom".

There is a test page for this example (with the TFmail.pl script
modified so that no mail will really be sent) at:

   http://cleaton.net/tfmail/custom.html


EXAMPLE 3 - INLINE TEMPLATES

This examples is very similar to example 2, but rather than
having the success page and email templates in separate files,
we 'inline' them into the config file.  This cuts down on the
number of files that need to be uploaded to the server.

The server side configuration file for this example is
/home/tfmai/cfg/inline.trc, which has the following contents:


%% NMS configuration file %%
#
# inline.trc - A basic example of TFmail setup and
# configuration, with the success page and e-mail body
# customised to suit the form.
#
# Inline templates used for both the success page and the
# e-mail body.
#

#
# recipient: the email address(s) to which TFmail should
# send the results of the form submission.
#
recipient: tfmail-inline@cleaton.net

#
# subject: the subject line for the e-mail
#
subject: tfmail example - inline

#
# For this example, we use customised inline templates to
# allow us some extra control over the layout of the
# success page and e-mail.

email_template:
%This is a TFmail form submission.  The input values were as
%follows:
%
%{= FOREACH input_field =}
%Input "{= name =}" had value "{= value =}"
%{= END =}
%
%-------------------------------------------------------------
%
%IP address of remote user: {= env.REMOTE_ADDR =}
%User Agent:                {= env.HTTP_USER_AGENT =}
%Referer:                   {= env.HTTP_REFERER =}
%

success_page_template:
%<?xml version="1.0" encoding="iso-8859-1"?>
%<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
%    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
%<html xmlns="http://www.w3.org/1999/xhtml">
%  <head>
%    <title>Thank You</title>
%    <link rel="stylesheet" type="text/css" href="/css/nms.css" />
%    <style>
%       h1.title {
%                   text-align : center;
%                }
%    </style>
%  </head>
%  <body>
%    <h1 class="title">Thank You</h1>
%    <p>This is what you submitted on {= date =}</p>
%    <hr size="1" width="75%" />
%{= FOREACH input_field =}
%    <p><font color="red">{= name =}</font> <b>=</b> {= value =}</p>
%{= END =}
%    <hr size="1" width="75%" />
%  </body>
%</html>

#
# End of inline.trc
#
###############################################

The HTML form for this example is the same as example 1, but with
the value of the "_config" input changed from "basic" to "inline".

There is a test page for this example (with the TFmail.pl script
modified so that no mail will really be sent) at:

   http://cleaton.net/tfmail/inline.html


