local-lib5/man/man3/Template::Plugins.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Template::Plugins 3"
 132 .TH Template::Plugins 3 "2008-12-09" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Template::Plugins \- Plugin provider module
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&    use Template::Plugins;
 139 .Ve
 140 .PP
 141 .Vb 1
 142 \&    $plugin_provider = Template::Plugins\->new(\e%options);
 143 .Ve
 144 .PP
 145 .Vb 1
 146 \&    ($plugin, $error) = $plugin_provider\->fetch($name, @args);
 147 .Ve
 148 .SH "DESCRIPTION"
 149 .IX Header "DESCRIPTION"
 150 The \f(CW\*(C`Template::Plugins\*(C'\fR module defines a provider class which can be used
 151 to load and instantiate Template Toolkit plugin modules.
 152 .SH "METHODS"
 153 .IX Header "METHODS"
 154 .Sh "new(\e%params)"
 155 .IX Subsection "new(%params)"
 156 Constructor method which instantiates and returns a reference to a
 157 \&\f(CW\*(C`Template::Plugins\*(C'\fR object.  A reference to a hash array of configuration
 158 items may be passed as a parameter.  These are described below.
 159 .PP
 160 Note that the Template front-end module creates a \f(CW\*(C`Template::Plugins\*(C'\fR
 161 provider, passing all configuration items.  Thus, the examples shown
 162 below in the form:
 163 .PP
 164 .Vb 5
 165 \&    $plugprov = Template::Plugins\->new({
 166 \&        PLUGIN_BASE => 'MyTemplate::Plugin',
 167 \&        LOAD_PERL   => 1,
 168 \&        ...
 169 \&    });
 170 .Ve
 171 .PP
 172 can also be used via the Template module as:
 173 .PP
 174 .Vb 5
 175 \&    $ttengine = Template\->new({
 176 \&        PLUGIN_BASE => 'MyTemplate::Plugin',
 177 \&        LOAD_PERL   => 1,
 178 \&        ...
 179 \&    });
 180 .Ve
 181 .PP
 182 as well as the more explicit form of:
 183 .PP
 184 .Vb 5
 185 \&    $plugprov = Template::Plugins\->new({
 186 \&        PLUGIN_BASE => 'MyTemplate::Plugin',
 187 \&        LOAD_PERL   => 1,
 188 \&        ...
 189 \&    });
 190 .Ve
 191 .PP
 192 .Vb 3
 193 \&    $ttengine = Template\->new({
 194 \&        LOAD_PLUGINS => [ $plugprov ],
 195 \&    });
 196 .Ve
 197 .ie n .Sh "fetch($name, @args)"
 198 .el .Sh "fetch($name, \f(CW@args\fP)"
 199 .IX Subsection "fetch($name, @args)"
 200 Called to request that a plugin of a given name be provided. The relevant
 201 module is first loaded (if necessary) and the
 202 \&\fIload()\fR class method called to return the factory
 203 class name (usually the same package name) or a factory object (a prototype).
 204 The \fInew()\fR method is then called as a class or object
 205 method against the factory, passing all remaining parameters.
 206 .PP
 207 Returns a reference to a new plugin object or \f(CW\*(C`($error, STATUS_ERROR)\*(C'\fR
 208 on error.  May also return \f(CW\*(C`(undef, STATUS_DECLINED)\*(C'\fR to decline to
 209 serve the request.  If \f(CW\*(C`TOLERANT\*(C'\fR is set then all errors will be
 210 returned as declines.
 211 .SH "CONFIGURATION OPTIONS"
 212 .IX Header "CONFIGURATION OPTIONS"
 213 The following list summarises the configuration options that can be provided
 214 to the \f(CW\*(C`Template::Plugins\*(C'\fR \fInew()\fR constructor.  Please consult
 215 Template::Manual::Config for further details and examples of each
 216 configuration option in use.
 217 .Sh "\s-1PLUGINS\s0"
 218 .IX Subsection "PLUGINS"
 219 The \s-1PLUGINS\s0 option can be used to provide
 220 a reference to a hash array that maps plugin names to Perl module names.
 221 .PP
 222 .Vb 7
 223 \&    my $plugins = Template::Plugins\->new({
 224 \&        PLUGINS => {
 225 \&            cgi => 'MyOrg::Template::Plugin::CGI',
 226 \&            foo => 'MyOrg::Template::Plugin::Foo',
 227 \&            bar => 'MyOrg::Template::Plugin::Bar',
 228 \&        },
 229 \&    });
 230 .Ve
 231 .Sh "\s-1PLUGIN_BASE\s0"
 232 .IX Subsection "PLUGIN_BASE"
 233 If a plugin is not defined in the \s-1PLUGINS\s0
 234 hash then the \s-1PLUGIN_BASE\s0 is used to
 235 attempt to construct a correct Perl module name which can be successfully
 236 loaded.
 237 .PP
 238 .Vb 4
 239 \&    # single value PLUGIN_BASE
 240 \&    my $plugins = Template::Plugins\->new({
 241 \&        PLUGIN_BASE => 'MyOrg::Template::Plugin',
 242 \&    });
 243 .Ve
 244 .PP
 245 .Vb 5
 246 \&    # multiple value PLUGIN_BASE
 247 \&    my $plugins = Template::Plugins\->new({
 248 \&        PLUGIN_BASE => [   'MyOrg::Template::Plugin',
 249 \&                           'YourOrg::Template::Plugin'  ],
 250 \&    });
 251 .Ve
 252 .Sh "\s-1LOAD_PERL\s0"
 253 .IX Subsection "LOAD_PERL"
 254 The \s-1LOAD_PERL\s0 option can be set to allow
 255 you to load regular Perl modules (i.e. those that don't reside in the
 256 \&\f(CW\*(C`Template::Plugin\*(C'\fR or another user-defined namespace) as plugins.
 257 .PP
 258 If a plugin cannot be loaded using the
 259 \&\s-1PLUGINS\s0 or
 260 \&\s-1PLUGIN_BASE\s0 approaches then,
 261 if the \s-1LOAD_PERL\s0 is set, the
 262 provider will make a final attempt to load the module without prepending any
 263 prefix to the module path.
 264 .PP
 265 Unlike regular plugins, modules loaded using \s-1LOAD_PERL\s0
 266 do not receive a Template::Context reference as the first argument to the
 267 \&\f(CW\*(C`new()\*(C'\fR constructor method.
 268 .Sh "\s-1TOLERANT\s0"
 269 .IX Subsection "TOLERANT"
 270 The \s-1TOLERANT\s0 flag can be set to indicate
 271 that the \f(CW\*(C`Template::Plugins\*(C'\fR module should ignore any errors encountered while
 272 loading a plugin and instead return \f(CW\*(C`STATUS_DECLINED\*(C'\fR.
 273 .Sh "\s-1DEBUG\s0"
 274 .IX Subsection "DEBUG"
 275 The \s-1DEBUG\s0 option can be used to enable
 276 debugging messages for the \f(CW\*(C`Template::Plugins\*(C'\fR module by setting it to
 277 include the \f(CW\*(C`DEBUG_PLUGINS\*(C'\fR value.
 278 .PP
 279 .Vb 1
 280 \&    use Template::Constants qw( :debug );
 281 .Ve
 282 .PP
 283 .Vb 3
 284 \&    my $template = Template\->new({
 285 \&        DEBUG => DEBUG_FILTERS | DEBUG_PLUGINS,
 286 \&    });
 287 .Ve
 288 .SH "TEMPLATE TOOLKIT PLUGINS"
 289 .IX Header "TEMPLATE TOOLKIT PLUGINS"
 290 Please see Template::Manual::Plugins For a complete list of all the plugin
 291 modules distributed with the Template Toolkit.
 292 .SH "AUTHOR"
 293 .IX Header "AUTHOR"
 294 Andy Wardley <abw@wardley.org> <http://wardley.org/>
 295 .SH "COPYRIGHT"
 296 .IX Header "COPYRIGHT"
 297 Copyright (C) 1996\-2007 Andy Wardley.  All Rights Reserved.
 298 .PP
 299 This module is free software; you can redistribute it and/or
 300 modify it under the same terms as Perl itself.
 301 .SH "SEE ALSO"
 302 .IX Header "SEE ALSO"
 303 Template::Manual::Plugins, Template::Plugin, Template::Context, Template.