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,
});
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.