local-lib5/man/man3/Template::Plugin.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::Plugin 3"
 132 .TH Template::Plugin 3 "2008-11-13" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Template::Plugin \- Base class for Template Toolkit plugins
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 4
 138 \&    package MyOrg::Template::Plugin::MyPlugin;
 139 \&    use base qw( Template::Plugin );
 140 \&    use Template::Plugin;
 141 \&    use MyModule;
 142 .Ve
 143 .PP
 144 .Vb 7
 145 \&    sub new {
 146 \&        my $class   = shift;
 147 \&        my $context = shift;
 148 \&        bless {
 149 \&            ...
 150 \&        }, $class;
 151 \&    }
 152 .Ve
 153 .SH "DESCRIPTION"
 154 .IX Header "DESCRIPTION"
 155 A \*(L"plugin\*(R" for the Template Toolkit is simply a Perl module which
 156 exists in a known package location (e.g. \f(CW\*(C`Template::Plugin::*\*(C'\fR) and
 157 conforms to a regular standard, allowing it to be loaded and used
 158 automatically.
 159 .PP
 160 The \f(CW\*(C`Template::Plugin\*(C'\fR module defines a base class from which other
 161 plugin modules can be derived.  A plugin does not have to be derived
 162 from Template::Plugin but should at least conform to its object-oriented
 163 interface.
 164 .PP
 165 It is recommended that you create plugins in your own package namespace
 166 to avoid conflict with toolkit plugins.  e.g.
 167 .PP
 168 .Vb 1
 169 \&    package MyOrg::Template::Plugin::FooBar;
 170 .Ve
 171 .PP
 172 Use the \s-1PLUGIN_BASE\s0 option to specify
 173 the namespace that you use. e.g.
 174 .PP
 175 .Vb 4
 176 \&    use Template;
 177 \&    my $template = Template\->new({
 178 \&        PLUGIN_BASE => 'MyOrg::Template::Plugin',
 179 \&    });
 180 .Ve
 181 .SH "METHODS"
 182 .IX Header "METHODS"
 183 The following methods form the basic interface between the Template
 184 Toolkit and plugin modules.
 185 .Sh "load($context)"
 186 .IX Subsection "load($context)"
 187 This method is called by the Template Toolkit when the plugin module
 188 is first loaded.  It is called as a package method and thus implicitly
 189 receives the package name as the first parameter.  A reference to the
 190 Template::Context object loading the plugin is also passed.  The
 191 default behaviour for the \f(CW\*(C`load()\*(C'\fR method is to simply return the class
 192 name.  The calling context then uses this class name to call the \f(CW\*(C`new()\*(C'\fR
 193 package method.
 194 .PP
 195 .Vb 1
 196 \&    package MyPlugin;
 197 .Ve
 198 .PP
 199 .Vb 4
 200 \&    sub load {               # called as MyPlugin\->load($context)
 201 \&        my ($class, $context) = @_;
 202 \&        return $class;       # returns 'MyPlugin'
 203 \&    }
 204 .Ve
 205 .ie n .Sh "new($context, @params)"
 206 .el .Sh "new($context, \f(CW@params\fP)"
 207 .IX Subsection "new($context, @params)"
 208 This method is called to instantiate a new plugin object for the \f(CW\*(C`USE\*(C'\fR
 209 directive. It is called as a package method against the class name returned by
 210 \&\fIload()\fR. A reference to the Template::Context object creating the plugin
 211 is passed, along with any additional parameters specified in the \f(CW\*(C`USE\*(C'\fR
 212 directive.
 213 .PP
 214 .Vb 6
 215 \&    sub new {                # called as MyPlugin\->new($context)
 216 \&        my ($class, $context, @params) = @_;
 217 \&        bless {
 218 \&            _CONTEXT => $context,
 219 \&        }, $class;           # returns blessed MyPlugin object
 220 \&    }
 221 .Ve
 222 .Sh "error($error)"
 223 .IX Subsection "error($error)"
 224 This method, inherited from the Template::Base module, is used for
 225 reporting and returning errors.   It can be called as a package method
 226 to set/return the \f(CW$ERROR\fR package variable, or as an object method to
 227 set/return the object \f(CW\*(C`_ERROR\*(C'\fR member.  When called with an argument, it
 228 sets the relevant variable and returns \f(CW\*(C`undef.\*(C'\fR  When called without an
 229 argument, it returns the value of the variable.
 230 .PP
 231 .Vb 2
 232 \&    package MyPlugin;
 233 \&    use base 'Template::Plugin';
 234 .Ve
 235 .PP
 236 .Vb 2
 237 \&    sub new {
 238 \&        my ($class, $context, $dsn) = @_;
 239 .Ve
 240 .PP
 241 .Vb 2
 242 \&        return $class\->error('No data source specified')
 243 \&            unless $dsn;
 244 .Ve
 245 .PP
 246 .Vb 4
 247 \&        bless {
 248 \&            _DSN => $dsn,
 249 \&        }, $class;
 250 \&    }
 251 .Ve
 252 .PP
 253 .Vb 1
 254 \&    package main;
 255 .Ve
 256 .PP
 257 .Vb 2
 258 \&    my $something = MyPlugin\->new()
 259 \&        || die MyPlugin\->error(), "\en";
 260 .Ve
 261 .PP
 262 .Vb 2
 263 \&    $something\->do_something()
 264 \&        || die $something\->error(), "\en";
 265 .Ve
 266 .SH "DEEPER MAGIC"
 267 .IX Header "DEEPER MAGIC"
 268 The Template::Context object that handles the loading and use of plugins
 269 calls the \fInew()\fR and \fIerror()\fR methods against the package name returned by
 270 the \fIload()\fR method. In pseudo-code terms looks something like this:
 271 .PP
 272 .Vb 1
 273 \&    $class  = MyPlugin\->load($context);       # returns 'MyPlugin'
 274 .Ve
 275 .PP
 276 .Vb 2
 277 \&    $object = $class\->new($context, @params)  # MyPlugin\->new(...)
 278 \&        || die $class\->error();               # MyPlugin\->error()
 279 .Ve
 280 .PP
 281 The \fIload()\fR method may alterately return a blessed reference to an
 282 object instance.  In this case, \fInew()\fR and \fIerror()\fR are then called as
 283 \&\fIobject\fR methods against that prototype instance.
 284 .PP
 285 .Vb 1
 286 \&    package YourPlugin;
 287 .Ve
 288 .PP
 289 .Vb 6
 290 \&    sub load {
 291 \&        my ($class, $context) = @_;
 292 \&        bless {
 293 \&            _CONTEXT => $context,
 294 \&        }, $class;
 295 \&    }
 296 .Ve
 297 .PP
 298 .Vb 4
 299 \&    sub new {
 300 \&        my ($self, $context, @params) = @_;
 301 \&        return $self;
 302 \&    }
 303 .Ve
 304 .PP
 305 In this example, we have implemented a 'Singleton' plugin.  One object
 306 gets created when \fIload()\fR is called and this simply returns itself for
 307 each call to \fInew()\fR.
 308 .PP
 309 Another implementation might require individual objects to be created
 310 for every call to \fInew()\fR, but with each object sharing a reference to
 311 some other object to maintain cached data, database handles, etc.
 312 This pseudo-code example demonstrates the principle.
 313 .PP
 314 .Vb 1
 315 \&    package MyServer;
 316 .Ve
 317 .PP
 318 .Vb 7
 319 \&    sub load {
 320 \&        my ($class, $context) = @_;
 321 \&        bless {
 322 \&            _CONTEXT => $context,
 323 \&            _CACHE   => { },
 324 \&        }, $class;
 325 \&    }
 326 .Ve
 327 .PP
 328 .Vb 4
 329 \&    sub new {
 330 \&        my ($self, $context, @params) = @_;
 331 \&        MyClient\->new($self, @params);
 332 \&    }
 333 .Ve
 334 .PP
 335 .Vb 1
 336 \&    sub add_to_cache   { ... }
 337 .Ve
 338 .PP
 339 .Vb 1
 340 \&    sub get_from_cache { ... }
 341 .Ve
 342 .PP
 343 .Vb 1
 344 \&    package MyClient;
 345 .Ve
 346 .PP
 347 .Vb 7
 348 \&    sub new {
 349 \&        my ($class, $server, $blah) = @_;
 350 \&        bless {
 351 \&            _SERVER => $server,
 352 \&            _BLAH   => $blah,
 353 \&        }, $class;
 354 \&    }
 355 .Ve
 356 .PP
 357 .Vb 4
 358 \&    sub get {
 359 \&        my $self = shift;
 360 \&        $self\->{ _SERVER }\->get_from_cache(@_);
 361 \&    }
 362 .Ve
 363 .PP
 364 .Vb 4
 365 \&    sub put {
 366 \&        my $self = shift;
 367 \&        $self\->{ _SERVER }\->add_to_cache(@_);
 368 \&    }
 369 .Ve
 370 .PP
 371 When the plugin is loaded, a \f(CW\*(C`MyServer\*(C'\fR instance is created. The \fInew()\fR
 372 method is called against this object which instantiates and returns a \f(CW\*(C`MyClient\*(C'\fR
 373 object, primed to communicate with the creating \f(CW\*(C`MyServer\*(C'\fR.
 374 .SH "AUTHOR"
 375 .IX Header "AUTHOR"
 376 Andy Wardley <abw@wardley.org> <http://wardley.org/>
 377 .SH "COPYRIGHT"
 378 .IX Header "COPYRIGHT"
 379 Copyright (C) 1996\-2007 Andy Wardley.  All Rights Reserved.
 380 .PP
 381 This module is free software; you can redistribute it and/or
 382 modify it under the same terms as Perl itself.
 383 .SH "SEE ALSO"
 384 .IX Header "SEE ALSO"
 385 Template, Template::Plugins, Template::Context