Template::Plugins(3pm)
NAME
Template::Plugins - Plugin provider module
SYNOPSIS
use Template::Plugins; $plugin_provider = Template::Plugins->new(\%options); ($plugin, $error) = $plugin_provider->fetch($name, @args);
DESCRIPTION
The "Template::Plugins" module defines a provider class which can be
used to load and instantiate Template Toolkit plugin modules.
METHODS
- new(\%params)
- Constructor method which instantiates and returns a reference to a
"Template::Plugins" object. A reference to a hash array of
configuration items may be passed as a parameter. These are described below. - Note that the Template front-end module creates a "Template::Plugins"
provider, passing all configuration items. Thus, the examples shown
below in the form:
$plugprov = Template::Plugins->new({PLUGIN_BASE => 'MyTemplate::Plugin',
LOAD_PERL => 1,
...}); - can also be used via the Template module as:
$ttengine = Template->new({PLUGIN_BASE => 'MyTemplate::Plugin',
LOAD_PERL => 1,
...}); - as well as the more explicit form of:
$plugprov = Template::Plugins->new({PLUGIN_BASE => 'MyTemplate::Plugin',
LOAD_PERL => 1,
...});$ttengine = Template->new({LOAD_PLUGINS => [ $plugprov ],}); - fetch($name, @args)
- Called to request that a plugin of a given name be provided. The
relevant module is first loaded (if necessary) and the load() class method called to return the factory class name (usually the same
package name) or a factory object (a prototype). The new() method is then called as a class or object method against the factory, passing
all remaining parameters. - Returns a reference to a new plugin object or "($error, STATUS_ERROR)"
on error. May also return "(undef, STATUS_DECLINED)" to decline to
serve the request. If "TOLERANT" is set then all errors will be
returned as declines.
CONFIGURATION OPTIONS
- The following list summarises the configuration options that can be
provided to the "Template::Plugins" new() constructor. Please consult Template::Manual::Config for further details and examples of each
configuration option in use. - PLUGINS
- The PLUGINS option can be used to provide a reference to a hash array
that maps plugin names to Perl module names.
my $plugins = Template::Plugins->new({PLUGINS => {cgi => 'MyOrg::Template::Plugin::CGI',
foo => 'MyOrg::Template::Plugin::Foo',
bar => 'MyOrg::Template::Plugin::Bar',},}); - PLUGIN_BASE
- If a plugin is not defined in the PLUGINS hash then the PLUGIN_BASE is
used to attempt to construct a correct Perl module name which can be
successfully loaded.
# single value PLUGIN_BASE
my $plugins = Template::Plugins->new({PLUGIN_BASE => 'MyOrg::Template::Plugin',});# multiple value PLUGIN_BASE
my $plugins = Template::Plugins->new({PLUGIN_BASE => [ 'MyOrg::Template::Plugin','YourOrg::Template::Plugin' ],}); - LOAD_PERL
- The LOAD_PERL option can be set to allow you to load regular Perl
modules (i.e. those that don't reside in the "Template::Plugin" or
another user-defined namespace) as plugins. - If a plugin cannot be loaded using the PLUGINS or PLUGIN_BASE
approaches then, if the LOAD_PERL is set, the provider will make a
final attempt to load the module without prepending any prefix to the
module path. - Unlike regular plugins, modules loaded using LOAD_PERL do not receive a
Template::Context reference as the first argument to the "new()"
constructor method. - TOLERANT
- The TOLERANT flag can be set to indicate that the "Template::Plugins"
module should ignore any errors encountered while loading a plugin and instead return "STATUS_DECLINED". - DEBUG
- The DEBUG option can be used to enable debugging messages for the
"Template::Plugins" module by setting it to include the "DEBUG_PLUGINS" value.
use Template::Constants qw( :debug );my $template = Template->new({DEBUG => DEBUG_FILTERS | DEBUG_PLUGINS,});
TEMPLATE TOOLKIT PLUGINS
Please see Template::Manual::Plugins For a complete list of all the
plugin modules distributed with the Template Toolkit.
AUTHOR
Andy Wardley <abw@wardley.org> <http://wardley.org/>
COPYRIGHT
Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
SEE ALSO
- Template::Manual::Plugins, Template::Plugin, Template::Context,
Template.