GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  CGI::APPLICATION::PLUGIN::ANYTEMPLATE::DRIVER::TEMPLATETOOLKIT (3)

.ds Aq ’

NAME

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

CONTENTS

DESCRIPTION

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

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

EMBEDDED COMPONENT SYNTAX (Template::Toolkit)

The Template::Toolkit 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") %]



TT OBJECT CACHING (singleton support)

    Introduction

In a persistent environment, rather than creating a Template::Toolkit object each time you fill a template, it is much more efficient to load a single Template::Toolkit 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 Template::Toolkit options (such as POST_CHOMP, etc.).

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

    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 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 config is used. For instance:



    package My::Project;
    sub setup {
        my $self = shift;
        $self->template->config(                 # My::Project is used to store
            type          => TemplateToolkit,  # cached TT object
        );
    }



A typical CGI::Application module hierarchy looks like this:



    CGI::Application
        My::Project
            My::Webapp



In this hierarchy, it makes sense to store the cached TT object in My::Project. To make this happen, either call $self->template->config from within My::Project, or explicitly name the storage_class when you call $self->template->config.

    Disabling TT Object Caching

You can disable Template::Toolkit object caching entirely by providing a false value to the object_caching driver config parameter:



        $self->template->config(
            type          => TemplateToolkit,
            TemplateToolkit => {
                object_caching => 0,
            },
        );



    TT Object Caching and Include Paths

The include_paths driver config parameter is not cached; it is set every time you call $self->template->load. So you can safely used cached TT objects even if the applications sharing the TT object need different include_paths.

CONFIGURATION

The CGI::Application::Plugin::AnyTemplate::Driver::TemplateToolkit driver accepts the following config parameters:
embed_tag_name The name of the tag used for embedding components. Defaults to CGIAPP.
template_extension If auto_add_template_extension is true, then CGI::Application::Plugin::AnyTemplate will append the value of template_extension to filename. By default the template_extension is .xhtml.
emulate_associate_query <B>This feature is now deprecated and will be removed in a future release.B>

If this config parameter is true, then CGI::Application::Plugin::AnyTemplate::Driver::TemplateToolkit will copy all of the webapp’s query params into the template.

This is similar to what would happen if you used HTML::Template’s associate feature with the webapp’s query object:



    my $driver = HTML::Template->new(
        associate => $self->query,
    );



By default emulate_associate_query is false.

object_caching Whether or not to cache the Template::Toolkit object in a persistent environment

By default, object_caching is enabled.

See TT OBJECT CACHING (singleton support), above.

storage_class What class to use as the storage key when object caching is enabled.

By default, storage_class defaults to the package containing the subroutine that called $self->template->config.

See TT OBJECT CACHING (singleton support), above.

All other configuration parameters are passed on unchanged to Template::Toolkit.

CONFIGURING UTF-8 TEMPLATES

AnyTemplate does NOT support Template::Toolkit’s binmode option at runtime:



    # not possible with AnyTemplate
    $tt->process($infile, $vars, $outfile, { binmode => 1 })
        || die $tt->error(), "\n";
   
    # not possible with AnyTemplate
    $tt->process($infile, $vars, $outfile, binmode => 1)
        || die $tt->error(), "\n";
   
    # not possible with AnyTemplate
    $tt->process($infile, $vars, $outfile, binmode => :utf8)
        || die $tt->error(), "\n";



Instead, use the ENCODING option in the initial config:



    $self->template->config(
        default_type => TemplateToolkit,
        TemplateToolkit => {
            ENCODING => UTF-8
        }
    );



If you have a mix of encodings in your templates, use a separate AnyTemplate configuration for each encoding:



    $self->template(ascii)->config(
        default_type => TemplateToolkit,
    );
    $self->template(utf-8)->config(
        default_type => TemplateToolkit,
        TemplateToolkit => {
            ENCODING => UTF-8
        }
    );



    required_modules

The required_modules function returns the modules required for this driver to operate. In this case: Template.

DRIVER METHODS

initialize Initializes the TemplateToolkit driver. See the docs for CGI::Application::Plugin::AnyTemplate::Base for details.
render_template Fills the Template::Toolkit object with $self->param

If the param emulate_associate_query is true, then set params for each of $self->{’webapp’}->query, mimicking HTML::Template’s associate mechanism.

Also set up a CGI::Application::Plugin::AnyTemplate::ComponentHandler object so that the CGIAPP.embed callback will work.

Returns the output of the filled template as a string reference.

See the docs for CGI::Application::Plugin::AnyTemplate::Base for details.

SEE ALSO



    CGI::Application::Plugin::AnyTemplate
    CGI::Application::Plugin::AnyTemplate::Base
    CGI::Application::Plugin::AnyTemplate::ComponentHandler
    CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplate
    CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplateExpr
    CGI::Application::Plugin::AnyTemplate::Driver::HTMLTemplatePluggable
    CGI::Application::Plugin::AnyTemplate::Driver::Petal

    CGI::Application

    Template::Toolkit
    HTML::Template

    HTML::Template::Pluggable
    HTML::Template::Plugin::Dot

    Petal

    Exporter::Renaming

    CGI::Application::Plugin::TT



ACKNOWLEDGEMENTS

Thanks to Cees Hek for discussing the issues of caching in a persistent environment. And also for his excellent CGI::Application::Plugin::TT module, from which I stole ideas and some code: especially the bit about how to change the include path in a TT object after you’ve initialized it.

AUTHOR

Michael Graham, <mgraham@cpan.org>

COPYRIGHT & LICENSE

Copyright 2005 Michael Graham, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 CGI::APPLICATION::PLUGIN::ANYTEMPLATE::DRIVER::TEMPLATETOOLKIT (3) 2016-03-18

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.