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

Template

OpenInteract2::ContentGenerator

OpenInteract2::TT2::Context

OpenInteract2::TT2::Plugin

OpenInteract2::TT2::Provider

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>

cpanm OpenInteract2::URL

perl -MCPAN -e shell
install OpenInteract2::URL