NAME

OpenInteract::Template::Provider - Retrieve templates for the Template Toolkit

SYNOPSIS

$Template::Config::CONTEXT = 'OpenInteract::Template::Context';
my $template = Template->new(
                      COMPILE_DIR    => '/tmp/ttc',
                      COMPILE_EXT    => '.ttc',
                      LOAD_TEMPLATES => [ OpenInteract::Template::Provider->new ] );
my ( $output );
$template->process( 'package::template', \%params, \$output );

DESCRIPTION

NOTE: As shown above, you need to use OpenInteract::Template::Context as a context for your templates since our naming scheme ('package::name') collides with the TT naming scheme for specifying a prefix before a template.

This package is a provider for the Template Toolkit while running under OpenInteract. Being a provider means that TT hands off any requests for templates to this class, which has OpenInteract-specific naming conventions (e.g., 'package::template') and knows how to find templates in the database, in the templates for a package or the templates in a website.

METHODS

All of the following are object methods and have as the first argument the object itself.

fetch( $text )

Overrides Template::Provider.

Uses $text to somehow retrieve a template. The actual work to retrieve a template is done in _load(), although this method ensures that the template name is 'safe' and creates a name we use to save the compiled template.

Returns a two-element list: the first is a compiled template, the second is an error message. (Of course, if there is no error the second item will be undefined.)

_load( $name, $content )

Loads the template content, returning a two-element list. The first item in the list is the TT hashref, the second is an error message.

We try four ways to retrieve a template, in this order:

1. scalar reference: If the template is a scalar reference it does not need to be retrieved, so we just put $content in the TT hashref structure as the data to process and return it.

2. glob reference: If the template is a glob reference we treat it as a filehandle and read all data from $content in the TT hashref structure as the data to process as return it.

3. generic website template: A website can store 'generic' templates, which means they are not part of any package. These are stored in the 'template' directory which can be set in the server configuration.

   This option is checked only if $name is not in the 'package::name' format used to uniquely identify templates by OpenInteract.

The next two checks split $name into $package and $template_name since $name is in the format 'package::name'. (Otherwise it is assumed to be handled by 2.)

4.

filesystem package template: Templates can be stored in the filesystem under $package. This checks to see if the template name in the package using $template_name. (See _find_package_template_filename() for how this is done.)

5.

database package template: Try to fetch the SPOPS object with $package and $template_name

Note that the order of 4 and 5 above are configurable from the server configuration, using the {template_info}{source} key.

_refresh( $cache_slot )

Called when we use $cache_slot for a template. This refreshes the time of the slot and brings it to the head of the LRU cache.

You can tune the expiration time of the cache by setting the key:

{cache}{template}{expire}

in your server configuration file to the amount of time (in seconds) to keep an entry in the cache.

_validate_template_name( $full_template_name )

Ensures that $full_template_name does not have any tricky filesystem characters (e.g., '..') in it.

_fetch_spops_template( $package, $template_name )

Retrieve a template from the database using the SPOPS object 'site_template'. Returns undef if an object with $package and $template_name is not found, or the matching object if it is found.

_fetch_oi_file( $filename )

Opens $filename, reads in the contents and puts it into a hashref used by TT -- with keys 'name', 'text', 'time' and 'load'. If successful, that hashref is returned. If it fails (cannot open file, whatever) the method throws a die.

_find_package_template_filename( $package, $template_name )

Try to find $template_name within the filesystem for $package. For example, c<$template_name> might be 'navigation_bar' so we look for:

DEFAULT_PACKAGE_TEMPLATE_DIR/$template_name
DEFAULT_PACKAGE_TEMPLATE_DIR/$template_name.TEMPLATE_EXTENSION

Where TEMPLATE_EXTENSION can be defined in the server configuration for your website (using the 'template_ext' key) or in the DEFAULT_TEMPLATE_EXTENSION constant in this class.

_get_anon_name( $text )

If we get an anonymous template to provide, we need to create a unique name for it so we can compile and cache it properly. This method returns a unique name based on $text.

BUGS

None known.

TO DO

Testing

Needs more testing in varied environments.

SEE ALSO

Template

Template::Provider

Slashcode (http://www.slashcode.com/)

COPYRIGHT

Copyright (c) 2001-2002 intes.net, inc.. 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>

Robert McArthur <mcarthur@dstc.edu.au>

Authors of Slashcode <http://www.slashcode.com/>

cpanm OpenInteract

perl -MCPAN -e shell
install OpenInteract