Template::Plugins(3)

okay bestie, this is the Template::Plugins manual page — Template::Plugins(3) — from the User Contributed Perl Documentation crew. it's giving plugin provider realness, and we're gonna keep every detail, no cap. 💖

💖 NAME 💖

Template::Plugins - Plugin provider module. short, sweet, iconic 🎀

✨ SYNOPSIS ✨

the vibe check:

use Template::Plugins;

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

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

🌸 DESCRIPTION 🌸

so Template::Plugins defines a provider class — think of it as the friend who goes and gets plugin modules for you — and it can load and instantiate Template Toolkit plugin modules. that's the whole flex ✨

🛠️ METHODS 🛠️

🌟 new(\%params) 🌟

okay so new(\%params) is the constructor method: it instantiates and returns a reference to a Template::Plugins object. slay. you can pass it a reference to a hash array of config items as a parameter, and those are described below.

quick note: the Template front-end module creates a Template::Plugins provider and passes all configuration items. so the examples below that look like:

$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) 🔍

so fetch($name, @args) is what gets called when you want a plugin with a given name. first the relevant module gets loaded (if necessary), then the load() class method is called to return the factory class name (usually the same package name) or a factory object (a prototype). after that, new() is called as a class or object method against the factory, passing all the remaining parameters. she's organized 💅

Returns a reference to a new plugin object or ($error, STATUS_ERROR) on error. it may also return (undef, STATUS_DECLINED) to decline to serve the request. and if TOLERANT is set, all errors will be returned as declines. okay that's the tea ☕

💅 CONFIGURATION OPTIONS 💅

The following list summarises the configuration options you can provide to the Template::Plugins new() constructor. Please consult Template::Manual::Config for further details and examples of each configuration option in use. lowkey essential reading, bestie 🫶

🍓 PLUGINS 🍓

The PLUGINS option can be used to provide a reference to a hash array that maps plugin names to Perl module names. mapping slay:

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. here's the single value and multiple value energy:

# 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. yes, those ones.

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. final attempt energy.

important caveat: unlike regular plugins, modules loaded using LOAD_PERL do not receive a Template::Context reference as the first argument to the new() constructor method. so don't expect that, bestie 🫶

🧚 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. tolerant queen behavior.

💜 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. like this:

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/> — author icon 👑

🎀 COPYRIGHT 🎀

Copyright (C) 1996-2022 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. license line, periodt.

🔥 SEE ALSO 🔥

• Template::Manual::Plugins
• Template::Plugin
• Template::Context
• Template

✨ cute sign-off: source/version vibes are perl v5.42.0, date is 2024-06-23, and yes it's the Template::Plugins(3) manual. bye bestie, go instantiate something cute 💅🫶