NAME
    CGI::Application::Plugin::TT - Add Template Toolkit support to
    CGI::Application

SYNOPSIS
     use base qw(CGI::Application);
     use CGI::Application::Plugin::TT;

     sub myrunmode {
       my $self = shift;

       my %params = {
                     email       => 'email@company.com',
                     menu        => [
                                     { title => 'Home',     href => '/home.html',
                                       title => 'Download', href => '/download.html', },
                                    ],
                     session_obj => $self->session,
       };

       return $self->tt_process('template.tmpl', \%params);
     }

DESCRIPTION
    CGI::Application::Plugin::TT adds support for the popular Template
    Toolkit engine to your CGI::Application modules by providing several
    helper methods that allow you to process template files from within your
    runmodes.

    It compliments the support for HTML::Template that is built into
    CGI::Application through the load_tmpl method. It also provides a few
    extra features than just the ability to load a template.

METHODS
  tt_process
    This is a simple wrapper around the Template Toolkit process method. It
    accepts two parameters, a template filename, and a hashref of template
    parameters. The return value will be a scalar reference to the output of
    the template.

      sub myrunmode {
        my $self = shift;

        return $self->tt_process('my_runmode.tmpl', { foo => 'bar' });
      }
 
  tt_config
    This method can be used to customize the functionality of the
    CGI::Application::Plugin::TT module, and the Template Toolkit module
    that it wraps. The recommended place to call "tt_config" is in the
    "cgiapp_init" stage of CGI::Application. If this method is called after
    a call to tt_process or tt_obj, then it will die with an error message.

    It is not a requirement to call this method, as the module will work
    without any configuration. However, most will find it useful to set at
    least a path to the location of the template files.

    The following parameters are accepted:

    TEMPLATE_OPTIONS
        This allows you to customize how the Template object is created by
        providing a list of options that will be passed to the Template
        constructor. Please see the documentation for the Template module
        for the exact syntax of the parameters, or see below for an example.

  tt_obj
    This method will return the underlying Template Toolkit object that is
    used behind the scenes. It is usually not necesary to use this object
    directly, as you can process templates and configure the Template object
    through the tt_process and tt_config methods. Every call to this method
    will return the same object during a single request.

    It may be useful for debugging purposes.

  tt_params
    This method will accept a hash or hashref of parameters that will be
    included in the processing of every call to tt_process. It is important
    to note that the parameters defined using tt_params will be passed to
    every template that is processed during a given request cycle. Usually
    only one template is processed per request, but it is entirely possible
    to call tt_process multiple times with different templates. Everytime
    tt_process is called, the hashref of parameters passed to tt_process
    will be merged with the parameters set using the tt_params method.
    Parameters passed through tt_process will have precidence in case of
    duplicate parameters.

    This can be useful to add global values to your templates, for example
    passing the user's name automatically if they are logged in.

      sub cgiapp_prerun {
        my $self = shift;

        $self->tt_params(username => $ENV{REMOTE_USER}) if $ENV{REMOTE_USER};
      }

  tt_params_clear
    This method will clear all the currently stored parameters that have
    been set with tt_params.

  tt_pre_process
    This is an overridable method that works in the spirit of cgiapp_prerun.
    The method will be called just before a template is processed, and will
    be passed the same parameters that were passed to tt_process (ie the
    template filename, and a hashref of template parameters). It can be used
    to make last minute changes to the template, or the parameters before
    the template is processed.

  tt_post_process
    This, like it's counterpart cgiapp_postrun, is called right after a
    template has been processed. It will be passed a scalar reference to the
    processed template.

EXAMPLE
    In a CGI::Application module:

      use CGI::Application::Plugin::TT;
      use base qw(CGI::Application);
  
      # configure the template object once during the init stage
      sub cgiapp_init {
        my $self = shift;
 
        # Configure the template
        $self->tt_config(
                  TEMPLATE_OPTIONS => {
                            INCLUDE_PATH => '/path/to/template/files',
                            POST_CHOMP   => 1,
                            FILTERS => {
                                         'currency' => sub { sprintf('$ %0.2f', @_) },
                            },
                  },
        );
      }
 
      sub cgiapp_prerun {
        my $self = shift;
 
        # Add the username to all templates if the user is logged in
        $self->tt_params(username => $ENV{REMOTE_USER}) if $ENV{REMOTE_USER};
      }

      sub tt_pre_process {
        my $self = shift;
        my $template = shift;
        my $params = shift;

        # could add the username here instead if we want
        $params->{username} = $ENV{REMOTE_USER}) if $ENV{REMOTE_USER};

        return;
      }

      sub tt_post_process {
        my $self    = shift;
        my $htmlref = shift;
 
        # clean up the resulting HTML
        require HTML::Clean;
        my $h = HTML::Clean->new($htmlref);
        $h->strip;
        my $newref = $h->data;
        $$htmlref = $$newref;
        return;
      }
 
      sub my_runmode {
        my $self = shift;
 
        my %params = (
                foo => 'bar',
        );
 
        # return the template output
        return $self->tt_process('my_runmode.tmpl', \%params);
      }

BUGS
    This is alpha software and as such, the features and interface are
    subject to change. So please check the Changes file when upgrading.

SEE ALSO
    CGI::Application, Template, perl(1)

AUTHOR
    Cees Hek <cees@crtconsulting.ca>

LICENSE
    Copyright (C) 2004 Cees Hek <cees@crtconsulting.ca>

    This library is free software. You can modify and or distribute it under
    the same terms as Perl itself.