Template::Plugins
Author: Andy Wardley

TT2 Home Page

- Modules
- Template::*
- Plugins.pm

Click to view the menu. It's very nice. Click to hide the menu and go all widescreen!
Back

#### Template::Plugin::* Modules

Up

#### Template::* Modules

Next

#### Template::Provider

Provider module for loading/compiling templates

# Template::Plugins

## Plugin provider module

# Contents

Top

# SYNOPSIS

Top

    use Template::Plugins;

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

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

# DESCRIPTION

Top

The `Template::Plugins` module defines a provider class which can be used to load and instantiate Template Toolkit plugin modules.

# METHODS

Top

## new(\%params)

Top

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)

Top

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

Top

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

Top

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

Top

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

    =head2 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

Top

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

Top

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

Top

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

# AUTHOR

Top

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

# COPYRIGHT

Top

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

Top

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

/modules/Template/Plugins.html last modified 10:55:06 31-May-2007