++ed by:
FANY
Author image Cees Hek
and 1 contributors

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.