--- name: "CGI::Application::Plugin::AnyTemplate::Driver::TemplateToolkit" section: "3pm" platform: "linux" package: "libcgi-application-plugin-anytemplate-perl" version: "0.18-3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/CGI::Application::Plugin::AnyTemplate::Driver::TemplateToolkit" --- # CGI::Application::Plugin::AnyTemplate::Driver::TemplateToolkit(3pm) Template::Toolkit plugin to AnyTemplate ## NAME CGI::Application::Plugin::AnyTemplate::Driver::TemplateToolkit - Template::Toolkit plugin to AnyTemplate ## 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 **This feature is now deprecated and will be removed in a future release.** 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, `""` ## 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.