perldoc > Template::Plugins

man perldoc info pydoc3 ri search

📛 NAME

🔌 Template::Plugins - Plugin provider module

🚀 Quick Reference

Use Case	Command	Description
🔧 Create plugin provider	Template::Plugins->new(\%options)	Instantiate a plugin provider with configuration
🔍 Fetch a plugin	$provider->fetch($name, @args)	Load and instantiate a plugin by name
🗂️ Custom plugin mapping	PLUGINS => { cgi => 'MyOrg::Plugin::CGI' }	Map plugin names to custom Perl modules
📂 Plugin base namespace	PLUGIN_BASE => 'MyOrg::Template::Plugin'	Set base namespace for plugin resolution
🌐 Load Perl modules as plugins	LOAD_PERL => 1	Allow loading any Perl module as a plugin
🛡️ Tolerant error handling	TOLERANT => 1	Ignore plugin load errors, return declined
🐛 Debug plugin loading	DEBUG => DEBUG_PLUGINS	Enable plugin debugging messages

📖 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.

📛 NAME 🚀 Quick Reference 📖 SYNOPSIS 📝 DESCRIPTION ⚙️ METHODS 🔧 CONFIGURATION OPTIONS 📦 TEMPLATE TOOLKIT PLUGINS ✍️ AUTHOR ©️ COPYRIGHT 🔗 SEE ALSO