Index

NAME
SYNOPSIS
DESCRIPTION
INITIALIZATION
- Custom Initialization
PROCESSING
- Custom Processing
BUGS
TO DO
SEE ALSO
COPYRIGHT
AUTHORS

Code Index:

package OpenInteract::Template::Process
__END__
EOF

NAME

OpenInteract::Template::Process - Process OpenInteract templates

SYNOPSIS

 # Specify an object by fully-qualified name (preferrred)

 my $html = $R->template->handler( {}, { key => 'value' },
                                   { name => 'my_pkg::this_template' } );

 # Specify an object by package and name

 my $html = $R->template->handler( {}, { key => 'value' },
                                   { package => 'my_pkg',
                                     db      => '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 = $R->template->handler( {}, { key => 'value' },
                                   { text => $little_template } );

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

 my $site_template_obj = $R->site_template->fetch( 'mypkg::myname' );
 my $html = $R->template->handler( {}, { key => 'value' },
                                   { object => $site_template_obj } );

DESCRIPTION

This class processes templates within OpenInteract. The main method is handler() -- 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 OpenInteract::Request 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 and template blocks. 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.)

Package BLOCKs created in this manner can be used via the TT 'PROCESS' directive:

[% PROCESS mycustomblock( this = that ) -%]

See Template::Manual::Directives (Template::Manual::Directives) for more information.

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}
  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 (Template::Manual::Config).

For instance, say you have a template of all the BLOCKs you use to define common graphical elements. (You can more easily do this with template widgets, but this is just an example.) You can save this template as $WEBSITE_DIR/template/myblocks.tmpl. Then to make it available to all templates processed by your site, you can do:

 # In conf/server.perl

 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 ) = @_;
     push @{ $template_config->{PRE_PROCESS} }, 'myblocks';
 }

Easy! Since 'myblocks.tmpl' is a global template, it will get picked up by OpenInteract::Template::Provider when TT tries to process it before every request. And since TT does template caching, you should not get the performance hit associated with parsing/compiling the global BLOCKs template with every template processed.

Since this is a normal Perl handler, you can perform any actions you like here. For instance, you can retrieve templates from a website via LWP, save them to a file and specify that file in PRE_PROCESS.

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.

(Non sequitur: the same MACRO/BLOCK can be specified in multiple PRE_PROCESS items. Items read later in the list get precedence.)

PROCESSING

handler( \%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 package and name separately
```
 package => 'package_name',
 db      => 'template_name'
```
Note that both the template name and package are required. This is a change from older versions when the template package was optional.

Method 3: Specify the text yourself
```
 text    => $scalar_with_text
 or
 text    => \$scalar_ref_with_text
```
Method 4: Specify an object of type OpenInteract::SiteTemplate (OpenInteract::SiteTemplate)
```
 object => $site_template_obj
```

Custom Processing

You have the opportunity to step in during the executing of handler() 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 handler() call.

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

  # In server.perl:

  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 ) = @_;
      my $R = OpenInteract::Request->instance;
      $template_vars->{MyPlugin} = $R->template_object
                                     ->context
                                     ->plugin( 'MyPlugin' );
  }

  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.

COPYRIGHT

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>