Template::Plugins

Template::Plugins(3) User Contributed Perl Documentation Template::Plugins(3)



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 configura-
       tion 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 rele-
       vant 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 con-
       figuration 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 mod-
       ules (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_PLUG-
       INS" 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, Tem-
       plate.



perl v5.8.8			  2008-01-21		 Template::Plugins(3)