Template::Plugins - Plugin provider module |
Template::Plugins - Plugin provider module
use Template::Plugins; $plugin_provider = Template::Plugins->new(\%options); ($plugin, $error) = $plugin_provider->fetch($name, @args);
The Template::Plugins
module defines a provider class which can be used
to load and instantiate Template Toolkit plugin modules.
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 ], });
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.
The following list summarises the configuration options that can be provided
to the Template::Plugins
new() constructor. Please consult
the Template::Manual::Config manpage for further details and examples of each
configuration option in use.
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', }, });
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' ], });
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 the Template::Context manpage reference as the first argument to the
new()
constructor method.
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
.
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 the Template::Manual::Plugins manpage For a complete list of all the plugin modules distributed with the Template Toolkit.
Andy Wardley <abw@wardley.org> http://wardley.org/
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.
the Template::Manual::Plugins manpage, the Template::Plugin manpage, the Template::Context manpage, Template.
Template::Plugins - Plugin provider module |