phpman > perldoc > 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 AT 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.