/ 
OpenInteract-1.99_01
River stage zero No dependents
/ OpenInteract2::ContentGenerator::TT2Process

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

# Specify an object by fully-qualified name (preferrred)
my $proc_class = 'OpenInteract2::ContentGenerator::TT2Process';
my $html = $proc_class->process( { 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 = $proc_class->process( {}, { key => 'value' },
                                 { text => $little_template } );

# Pass the already-created object for parsing (rare)

my $site_template_obj = CTX->template_class->fetch( 'base_main' );
my $html = $proc_class->process( {}, { 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

initialize( \%config )

Creates a TT processing object with necessary parameters and returns it. We generally call initialize() from OpenInteract2::Context on the first request for a template object. Each website running in the same process gets its own template object.

Since we create one TT object per website, we can initialize that object with website-specific information. So the initialization process steps through the packages available in the website and asks each one for its list of template plugins. Once retrieved, the TT object is started up with them and they are available via the normal means.

Package plugins created in this matter are available either via:

[% USE MyPlugin %]

or by defining a custom_variable_class for the template and setting the plugin to be available without the TT 'use' statement. (See below for details.)

Note that you can also define custom initialization methods (on a global website basis) as described below.

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 values for the keys template_info.custom_init_class and template_info.custom_init_method. The class/method combination (if you do not specify a method name, 'handler' will be used) get passed the template configuration hashref, which you can modify as you see fit. There are many variables that you can change; learn about them at Template::Manual::Config.

Assume that TT can use the configuration variable 'SUNSET' to do something. To set the variable:

# In conf/server.ini

[template_info]
...
custom_init_class  = MyCustom::Template
custom_init_method = initialize

# In MyCustom/Template.pm:

package MyCustom::Template;

use strict;

sub initialize {
    my ( $class, $template_config ) = @_;
    $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.

Note that initialize() should only get executed once for every website for every Apache 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

process( \%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

Custom Processing

You have the opportunity to step in during the executing of process() with every request and set 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 that gets two arguments: the name of the current template (in 'package::name' format) and the template variable hashref:

sub my_variable {
    my ( $class, $template_name, $template_vars ) = @_;
    ...
}

To tell OI where your handler is, in your server configuration file specify:

[template_info]
custom_variable_class  = MyCustom::Template
custom_variable_method = variable

Either the 'custom_variable_method' or the default method name ('handler') will be called.

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 process() call.

Example where we make a custom plugin (see initialize() above) available to every template:

 # In server.ini:

 [template_info]
 custom_variable_class  = MyCustom::Template
 custom_variable_method = variable

 # In MyCustom/Template.pm:

 package MyCustom::Template;

 use strict;

 sub variable {
     my ( $class, $template_name, $template_vars ) = @_;
     $template_vars->{MyPlugin} = CTX->template               # gets the default template object...
                                     ->context                # ...gets the TT2 context
                                     ->plugin( 'MyPlugin' );  # ...sets our plugin
 }

 1;

Using this process, our templates will not need to execute a:

[% USE MyPlugin %]

before using the methods in the plugin.

BUGS

None known.

TO DO

Nothing known.

SEE ALSO

Template

OpenInteract2::ContentGenerator::TT2Context

OpenInteract2::ContentGenerator::TT2Plugin

OpenInteract2::ContentGenerator::TT2Provider

COPYRIGHT

Copyright (c) 2001-2003 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>