Template::Plugins(3pm)

1Template::Plugins(3)  User Contributed Perl Documentation Template::Plugins(3)
2
3
4

NAME

6       Template::Plugins - Plugin provider module
7

SYNOPSIS

9           use Template::Plugins;
10
11           $plugin_provider = Template::Plugins->new(\%options);
12
13           ($plugin, $error) = $plugin_provider->fetch($name, @args);
14

DESCRIPTION

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

METHODS

20   new(\%params)
21       Constructor method which instantiates and returns a reference to a
22       "Template::Plugins" object.  A reference to a hash array of
23       configuration items may be passed as a parameter.  These are described
24       below.
25
26       Note that the Template front-end module creates a "Template::Plugins"
27       provider, passing all configuration items.  Thus, the examples shown
28       below in the form:
29
30           $plugprov = Template::Plugins->new({
31               PLUGIN_BASE => 'MyTemplate::Plugin',
32               LOAD_PERL   => 1,
33               ...
34           });
35
36       can also be used via the Template module as:
37
38           $ttengine = Template->new({
39               PLUGIN_BASE => 'MyTemplate::Plugin',
40               LOAD_PERL   => 1,
41               ...
42           });
43
44       as well as the more explicit form of:
45
46           $plugprov = Template::Plugins->new({
47               PLUGIN_BASE => 'MyTemplate::Plugin',
48               LOAD_PERL   => 1,
49               ...
50           });
51
52           $ttengine = Template->new({
53               LOAD_PLUGINS => [ $plugprov ],
54           });
55
56   fetch($name, @args)
57       Called to request that a plugin of a given name be provided. The
58       relevant module is first loaded (if necessary) and the load() class
59       method called to return the factory class name (usually the same
60       package name) or a factory object (a prototype).  The new() method is
61       then called as a class or object method against the factory, passing
62       all remaining parameters.
63
64       Returns a reference to a new plugin object or "($error, STATUS_ERROR)"
65       on error.  May also return "(undef, STATUS_DECLINED)" to decline to
66       serve the request.  If "TOLERANT" is set then all errors will be
67       returned as declines.
68

CONFIGURATION OPTIONS

70       The following list summarises the configuration options that can be
71       provided to the "Template::Plugins" new() constructor.  Please consult
72       Template::Manual::Config for further details and examples of each
73       configuration option in use.
74
75   PLUGINS
76       The PLUGINS option can be used to provide a reference to a hash array
77       that maps plugin names to Perl module names.
78
79           my $plugins = Template::Plugins->new({
80               PLUGINS => {
81                   cgi => 'MyOrg::Template::Plugin::CGI',
82                   foo => 'MyOrg::Template::Plugin::Foo',
83                   bar => 'MyOrg::Template::Plugin::Bar',
84               },
85           });
86
87   PLUGIN_BASE
88       If a plugin is not defined in the PLUGINS hash then the PLUGIN_BASE is
89       used to attempt to construct a correct Perl module name which can be
90       successfully loaded.
91
92           # single value PLUGIN_BASE
93           my $plugins = Template::Plugins->new({
94               PLUGIN_BASE => 'MyOrg::Template::Plugin',
95           });
96
97           # multiple value PLUGIN_BASE
98           my $plugins = Template::Plugins->new({
99               PLUGIN_BASE => [   'MyOrg::Template::Plugin',
100                                  'YourOrg::Template::Plugin'  ],
101           });
102
103   LOAD_PERL
104       The LOAD_PERL option can be set to allow you to load regular Perl
105       modules (i.e. those that don't reside in the "Template::Plugin" or
106       another user-defined namespace) as plugins.
107
108       If a plugin cannot be loaded using the PLUGINS or PLUGIN_BASE
109       approaches then, if the LOAD_PERL is set, the provider will make a
110       final attempt to load the module without prepending any prefix to the
111       module path.
112
113       Unlike regular plugins, modules loaded using LOAD_PERL do not receive a
114       Template::Context reference as the first argument to the new()
115       constructor method.
116
117   TOLERANT
118       The TOLERANT flag can be set to indicate that the "Template::Plugins"
119       module should ignore any errors encountered while loading a plugin and
120       instead return "STATUS_DECLINED".
121
122   DEBUG
123       The DEBUG option can be used to enable debugging messages for the
124       "Template::Plugins" module by setting it to include the "DEBUG_PLUGINS"
125       value.
126
127           use Template::Constants qw( :debug );
128
129           my $template = Template->new({
130               DEBUG => DEBUG_FILTERS | DEBUG_PLUGINS,
131           });
132

TEMPLATE TOOLKIT PLUGINS

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

AUTHOR

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

COPYRIGHT

141       Copyright (C) 1996-2022 Andy Wardley.  All Rights Reserved.
142
143       This module is free software; you can redistribute it and/or modify it
144       under the same terms as Perl itself.
145