Template::Plugins - Plugin provider module

       Andy Wardley <abw@wardley.org> <http://wardley.org/>

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

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

   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.

       Template::Plugins - Plugin provider module

       Template::Manual::Plugins, Template::Plugin, Template::Context, Template.

perl v5.40.0                                       2024-10-20                             Template::Plugins(3pm)

           use Template::Plugins;

           $plugin_provider = Template::Plugins->new(\%options);

           ($plugin, $error) = $plugin_provider->fetch($name, @args);

       Please see Template::Manual::Plugins For a complete list of all the plugin modules distributed with the
       Template Toolkit.