view release on metacpan or  search on metacpan

lib/CGI/Application/Plugin/AnyTemplate/Driver/TemplateToolkit.pm  view on Meta::CPAN

package CGI::Application::Plugin::AnyTemplate::Driver::TemplateToolkit;

=head1 NAME

CGI::Application::Plugin::AnyTemplate::Driver::TemplateToolkit - Template::Toolkit plugin to AnyTemplate

=head1 DESCRIPTION

This is a driver for L<CGI::Application::Plugin::AnyTemplate>, which
provides the implementation details specific to rendering templates via
the L<Template::Toolkit|Template> templating system.

All C<AnyTemplate> drivers are designed to be used the same way.  For
general usage instructions, see the documentation of
L<CGI::Application::Plugin::AnyTemplate>.

=head1 EMBEDDED COMPONENT SYNTAX (Template::Toolkit)

The L<Template::Toolkit|Template> syntax for embedding components is:

    [% CGIAPP.embed("some_run_mode", param1, param2, 'literal string3') %]

This can be overridden by the following configuration variables:

    embed_tag_name       # default 'CGIAPP'

For instance by setting the following values in your configuration file:

    embed_tag_name       'MYAPP'

Then the embedded component tag will look like:

    [% MYAPP.embed("some_run_mode") %]


=head1 TT OBJECT CACHING (singleton support)

=head2 Introduction

In a persistent environment, rather than creating a L<Template::Toolkit|Template>
object each time you fill a template, it is much more efficient to load
a single L<Template::Toolkit|Template> object and use this object to render all
of your templates.

However, in a persistent environment, you may have several different
applications running, and they all might need to set different
L<Template::Toolkit|Template> options (such as C<POST_CHOMP>, etc.).

By default, when the C<TemplateToolkit> driver creates a
L<Template::Toolkit|Template> object, it caches it.  From that point on, whenever
the same application needs a L<Template::Toolkit|Template> object, the driver
uses the cached object rather than creating a new one.

=head2 Multiple Applications in a Shared Persistent Environment

An attempt is made to prevent different applications from
sharing the same TT object.

Internally, the TT objects are stored in a private hash keyed by the web
application's class name.

You can explicitly specify the class name when you call C<config>:

        $self->template->config(
            type          => 'TemplateToolkit',
            TemplateToolkit => {
                storage_class => 'My::Project',
            },
        );

If you don't specify the class name, then the package containing the subroutine
that called C<config> is used.  For instance:

    package My::Project;
    sub setup {
        my $self = shift;
        $self->template->config(                 # My::Project is used to store