transparent results from the CPAN

CGI-Builder-TT2

	# Template uses a search path to find templates, and can use different
	# providers to get templates from a DB or the web, so a -f test might not
	# be valid here. The tt->context->template method loads the template or
	# throws an exception if loading fails.
    if ($s->page_content eq $print_code) {
		eval { $s->tt->context->template($s->tt_template) };
		return !$@;
    }
    else {
        return length $s->page_content;
    }
}


1;

__END__

=head1 NAME

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

=head1 VERSION 0.02

=head1 INSTALLATION

=over

=item Prerequisites

    CGI::Builder    >= 1.12
    Template        >= 2.0

=item CPAN

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

=item Standard installation

From the directory where this file is located, type:

    perl Makefile.PL
    make
    make test
    make install


=back

=head1 SYNOPSIS

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

=head1 DESCRIPTION

This module transparently integrates C<CGI::Builder> and C<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 C<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:

=over

=item *

create a page handler for each page as usual

=item *

create a new template object and assign a new template file

=item *

find the runtime values and assign them to the template object

=item *

run the template process and set the C<page_content> to the produced
output

=back

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.

=head2 Example

There's an extended example in the directory C<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. 

=head2 How it works

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

Since the C<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 ...
    }
( run in 0.871 second using v1.01-cache-2.11-cpan-ceb78f64989 )