NAME
OpenInteract2::ContentGenerator::TT2Process - Process Template Toolkit templates in OpenInteract
SYNOPSIS
# NOTE: You will probably never deal with this class. It's don'e
# behind the scenes for you in the '$action->generate_content' method
# Get a content generator by name from the context; name is
# configured in server configuration under 'content_generator'
my $generator = CTX->content_generator( 'TT' );
# Specify an object by fully-qualified name (preferrred)
my $html = $generator->generate( {}, { key => 'value' },
{ name => 'my_pkg::this_template' } );
# Directly pass text to be parsed (fairly rare)
my $little_template = 'Text to replace -- here is my login name: ' .
'[% login.login_name %]';
my $html = $generator->generate( {}, { key => 'value' },
{ text => $little_template } );
# Pass the already-created object for parsing (rare)
my $site_template_obj = CTX->lookup_class( 'template' )->fetch( 'base_main' );
my $html = $generator->generate( {}, { key => 'value' },
{ object => $site_template_obj } );
DESCRIPTION
This class processes templates within OpenInteract. The main method is process()
-- just feed it a template name and a whole bunch of keys and it will take care of finding the template (from a database, filesystem, or wherever) and generating the finished content for you.
Shorthand used below: TT == Template Toolkit.
INITIALIZATION
Base Initialization
initialize( \%config )
Performs all initialization, including reading plugins from all packages. It then creates a TT processing object with necessary parameters and stores it for later use. We call initialize()
from OpenInteract2::ContentGenerator when the OI2 context is first initialized and never again so we can perform expensive operations here.
Initializing Template Plugins
To declare a plugin exported by a package, specify it in the package.conf
file for that package. The value is in two parts: the first part is the name by which the plugin is known, the second is the plugin class:
template_plugin MyPlugin OpenInteract2::TT2Plugin::MyPlugin
See OpenInteract2::Manual::Templates for information about creating your own template plugins.
Custom Initialization
You can define information in the server configuration of your website that enables you to modify the configuration passed to the new()
method of Template.
In your server configuration, define template_info.custom_init_class
as the class that contains a method 'custom_template_initialize()'. The method gets passed the template configuration hashref, which you can modify in-place as you see fit. It also gets a copy of the server configuration for the TT content generator as the second argument.
There are many variables that you can change; learn about them at Template::Manual::Config. For example, assume that TT can use the configuration variable 'SUNSET' to do something. To set the variable:
# In conf/server.ini
[content_generator TT]
...
custom_init_class = MyCustom::Template
# In MyCustom/Template.pm:
package MyCustom::Template;
use strict;
sub custom_template_initialize {
my ( $class, $tt_config, $init_params ) = @_;
$template_config->{SUNSET} = '7:13 AM';
}
Easy! Since this is a normal Perl method, you can perform any actions you like here. For instance, you can retrieve templates from a website via LWP, save them to your package template directory and process them via PROCESS/INCLUDE as you normally would. Or set template caching/compiling options on a SOAP server for your 100-machine cluster and read them from a single source.
Note that initialize()
should only get executed once at context initialization. (Standalone server: once; preforking server, probably once per child.) Most of the time this is fairly infrequent, so you can execute code here that takes a little more time than if it were being executed with every request.
PROCESSING
Base Processing
generate( \%template_params, \%template_variables, \%template_source )
Generate template content, given keys and values in \%template_variables
and a template identifier in \%template_source
.
Parameters:
template_params (\%)
Configuration options for the template. Note that you can set defaults for these at configuration time as well.
template_variables (\%)
The key/value pairs that will get plugged into the template. These can be arbitrarily complex, since the Template Toolkit can do anything :-)
template_source
Tell the method how to find the source for the template you want to process. There are a number of ways to do this:
Method 1: Use a combined name (preferred method)
name => 'package_name::template_name'
Method 2: Specify the text yourself
text => $scalar_with_text or text => \$scalar_ref_with_text
Method 3: Specify an object of type OpenInteract2::SiteTemplate
object => $site_template_obj
Customized Variables
You have the opportunity to step in during the executing of generate()
with every request and create/modify/remove template variables. To do so, you need to define a handler and tell OI where it is.
To define the handler, just define a normal Perl class method 'customize_template_vars()' that gets two arguments: the name of the current template (in 'package::name' format) and the template variable hashref:
sub customize_template_vars {
my ( $class, $template_name, $template_vars ) = @_;
$template_vars->{MOTD} = 'No matter where you go, there you are';
}
To tell OI where your handler is, in your server configuration file specify:
[content_generator TT]
...
custom_variable_class = MyCustom::Template
You can set (or, conceivably, remove) information bound for every template. Variables set via this method are available to the template just as if they had been passed in via the generate()
call.
SEE ALSO
OpenInteract2::ContentGenerator
COPYRIGHT
Copyright (c) 2001-2004 Chris Winters. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
AUTHORS
Chris Winters <chris@cwinters.com>