NAME

CGI::Builder::TT2 - CGI::Builder and Template Toolkit 2 integration

VERSION 0.02

INSTALLATION

Prerequisites

    CGI::Builder    >= 1.12
    Template        >= 2.0

CPAN

    perl -MCPAN -e 'install CGI::Builder::TT2'

Standard installation

From the directory where this file is located, type:

    perl Makefile.PL
    make
    make test
    make install

SYNOPSIS

    # just include it in your build
    
    use CGI::Builder
    qw| CGI::Builder::TT2
      |;

DESCRIPTION

This module transparently integrates "CGI::Builder" and "Template" in a very handy, powerful and flexible framework that can save you a lot of coding, time and resources.

With this module, you don't need to produce the "page_content" within your page handlers anymore (unless you want to); you don't even need to manage a template system yourself (unless you want to).

If you use a template system on your own (i.e. not integrated in a CBF extension), you will have to write all this code explicitly:

create a page handler for each page as usual
create a new template object and assign a new template file
find the runtime values and assign them to the template object
run the template process and set the "page_content" to the produced output

You can save all that by just including this module in your build, because it implements an internal transparent and automatic template system that even without your explicit intervention is capable of finding the correct template and the correct runtime values to fill it, and generates the page_content automagically. With this module you can even eliminate the page handlers that are just setting the page_content, because the page is automatically sent by the template system.

Example

There's an extended example in the directory "example/" of the module distribution. Anyway, here a snippet to get the general idea:

    package WebApp;
    use CGI::Builder qw/ CGI::Builder::TT2 /;
    
    sub PH_index
    {
        my $self = shift;
    
        $self->tt_vars( environment => \%ENV );
    }

Here's the template:

    <html>
    <head>
        <meta http-equiv=content-type content="text/html;charset=iso-8859-1">
        <title>A random example :)</title>
    </head>
    <body>
        <table>
        [% FOREACH k IN environment.keys %]
        <tr>
            <td>[% k %]</td>
            <td>[% environment.$k %]</td>
        </tr>
        [% END %]
        </table>
    </body>
    </html>

This is just one of the styles you can adopt with CGI::Builder::TT2. Read further.

How it works

This module implements a default value for the "page_content" property: a CODE reference that produces and print the page content by using an internal "Template" object.

Since the "page_content" property is set to its own default value before the page handler is called, the page handler can completely (and usually should) avoid to produce any output.

    sub PH_myPage
    {
      ... do_something_useful ...
      ... no_need_to_set_page_content ...
      ... returned_value_will_be_ignored ...
    }

This module just calls the page handler related with the "page_name", but it does not expect any returned value from it.

The output will be generated internally by the merger of the template file and the runtime values that are looked up from the "FooBar::Lookup" package ('FooBar' is not literal, but stands for your application namespace plus the '::Lookups' string).

In simplest cases you can also avoid to create the page handler for certain pages: by default the template with the same page name will be used to produce the output.

This does not mean that you cannot do things otherwise when you need to. Just create a page handler and add there all the properties you want, or set those you want to override:

   sub PH_mySpecialPage
   {
     my $s = shift ;
     $s->tt_vars( 
        special_key          => 'that' ,
        another_special_keys => 'this'
     ) ;
     $s->tt_template = '/that/special/template.tt2' ;
   }

Since the page handler adds values to the "tt_vars" properties group, and sets the "tt_template" property, the application will add those values to the (possibly empty) template variables set, and the template system will print with a specific template and not with the default 'mySpecialPage.tt2'.

If some page handler needs to produce the output on its own (completely bypassing the template system) it can do so by setting the "page_content" property as usual (i.e. with the page content or with a reference to it)

   sub PH_mySpecialPage
   {
     my $s = shift ;
      ... do_something_useful ...
     # will bypass the template system
     $s->page_content  = 'something';
     $s->page_content .= 'something more';
   }

For the 'mySpecialPage' page, the application will not use the template system at all, because the "page_content" property was set to the output.

Note: For former CGI::Application users: the returned value of any page handler will be ALWAYS ignored, so set explicitly the "page_content" property when needed.

Lookups

These features mimics the mechanisms implemented in CGI::Builder::Magic, to provide another way to pass variables to the templates. A way that CGI::Builder users could be familiar with.

*::Lookups package

This is a special package that your application should define to allow the object to auto-magically look up the run time values.

The name of this package is contained in the "tt_lookups_package" property. The default value for this property is 'FooBar::Lookup' where 'FooBar' is not literal, but stands for your CBB namespace plus the '::Lookups' string, so if you define a CBB package as 'WebApp' you should define a 'WebApp::Lookups' package too (or set the "tt_lookup_package" property with the name of the package you will use as the lookup).

In this package you should define all the variables and subs needed to supply any runtime value that will be substituted in place of the matching label or block in any template.

The lookup is confined to the *::Lookups package on purpose. It would be simpler to use the same CBB package, but this would extend the lookup to all the properties, methods and handlers of your CBB and this might cause conflict and security holes. So, by just adding one line to your CBB, (e.g. 'package FooBar::Lookups;') you can separate your CBB from the lookup-allowed part of it.

Note: Obviously you can also put the *::Lookup package in its own '.pm' file, thus making it simply loadable from different CBBs.

The Template syntax

This module implements a "Template" object, so the used "tags" are the default Template tags e.g.:

    [% FOREACH item IN array %]
      [% item %]
    [% END %]

Please, read Template::Manual.

How to organize your CBB

1.: Set all the actions common to all pages in the "OH_init()" handler (as usual)
2.: Prepare a template for each page addressed by your application
3.: Set the variables or the subs in the *::Lookups package that will be available to the internal "Template" object (that could be picked up by one or more templates processing)
4.: Define just the page handlers that needs to do something special
5.: Use the properties default values, that can save you a lot of time ;-)

PROPERTY and GROUP ACCESSORS

This module adds some template properties (all those prefixed with 'tt_') to the standard CBF properties. The default of these properties are usually smart enough to do the right job for you, but you can fine-tune the behavior of your CBB by setting them to the value you need.

tt_vars

This property group accessor allows you to set the variables that will be available in the template. If one of these variables has the same name of a variable that's in the lookups package, it will be overridden. You can pass any type of scalar value to the templates: numbers, strings and any type of references. Subroutines passed to the template in this way, when called, will receive a reference to the application object as their first argument. E.g.:

    package WebApp;
    use CGI::Builder qw/ CGI::Builder::TT2 /;
    
    sub foo
    {
        my $app   = shift;
        my $param = shift;
    
        # $app IS A 'Webapp'
        # $param's value is 'bar'
    }
    
    sub PH_index
    {
        my $self = shift;
    
        $self->tt_vars( my_sub => \&foo );
    }

And this is the corresponding template:

    [% my_sub( 'bar' ) %]

Moreover, every template will receive a reference to the CBF object in the variable "CBF", with no action required to the programmer. It should be noted that it's a good software practice to separate application logic from visualization logic: calling application methods from the template could drive to situations of coupling between these two aspects. But we will apply Perl's philosophy, giving rope to the programmer even if he could hang himself with it

tt_lookups_package

This property allows you to access and set the name of the package where the Template object. The default value for this property is 'FooBar::Lookup' where 'FooBar' is not literal, but stands for your application namespace plus the '::Lookups' string. (i.e. 'WebApp::Lookup').

tt_template

This property allows you to access and set the 'template' argument passed to the Template "process()" method. Set This property to an absolute path if you want bypass the "page_path" property.

CBF changed property defaults

CBF page_suffix

This module sets the default of the "page_suffix" to '.tt2'. You can override it by just setting another suffix of your choice.

CBF page_content

This module sets the default of the "page_content" to a CODE reference that produces the page content by using an internal Template object (see also "How it works"). If you want to bypass the template system in any Page Handler, just explicitly set the "page_content" to the content you want to send.

ADVANCED FEATURES

In this section you can find all the most advanced or less used features that document all the details of this module. In most cases you don't need to use them, anyway, knowing them will not hurt.

tt

This property returns the internal "Template" object.

This is not intended to be used to generate the page output - that is generated automatically - but it could be useful to generate other outputs (e.g. messages for sendmail) by using the same template object, thus preserving the same arguments.

Note: You can change the default arguments of the object by using the "tt_new_args" property, or you can completely override the creation of the internal object by overriding the "tt_new()" method.

tt_new()

This method is not intended to be used directly in your CBB. It is used internally to initialize and return the "Template" object. You can override it if you know what you are doing, or you can simply ignore it ;-).

tt_new_args( arguments )

This property group accessor handles the Template constructor arguments that are used in the creation of the internal Template object. Use it to finetune the behavior if you know what are doing. By default, only one option is set: "INCLUDE_PATH =" [ $_[0]->page_path ]>.

Note: You can completely override the creation of the internal object by overriding the "tt_new()" method.

SUPPORT

Even if this module has not been written by Domizio Demichelis, you can find support via the mailing list, which I read daily: I'll try to respond as soon as possible. Moreover, if the question involve CGI::Builder issues, you could receive a reply from CGI::Builder's author himself. The list is used for general support on the use of the CBF, announcements, bug reports, patches, suggestions for improvements or new features. The API to the CBF is stable, but if you use the CBF in a production environment, it's probably a good idea to keep a watch on the list.

You can join the CBF mailing list at this url:

    http://lists.sourceforge.net/lists/listinfo/cgi-builder-users

ACKNOWLEDGMENTS

Many thanks to Domizio Demichelis, author of the CGI::Builder framework, who helped me during the development of this module with prompt explanations, insightful advices and patience.

AUTHORS

Stefano Rodighiero, <larsen@perl.it> (<http://larsen.perlmonk.org>)

Vince Veselosky (<http://control-escape.com>) - Contributed with many ideas, comments and clever solutions to daunting problems. And the extended example, too.