← Back to branch summary

~ubuntu-branches/ubuntu/quantal/libtemplate-perl/quantal

« back to all changes in this revision

Viewing changes to html/old/modules/Template/Plugin.html

  • Committer: Package Import Robot
  • Author(s): Benjamin Mako Hill
  • Date: 2012-04-08 19:06:29 UTC
  • mfrom: (0.7.1) (0.5.2) (5.1.3 sid)
  • Revision ID: package-import@ubuntu.com-20120408190629-wbcbs2ea39mex6lt
Tags: 2.24-1
http://bugs.debian.org/664561
https://launchpad.net/bugs/688836
* New upstream release (Closes: #664561)
* Bump Standards-Version to 3.9.3
* Changed to the short description to mention the term "Template
  Toolkit". (LP: #688836)

Show diffs side-by-side

added added

removed removed

Lines of Context:
html/old/modules/Template/Plugin.html
 
1
 
 
2
 
 
3
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Strict//EN">
 
4
<html>
 
5
  <head>
 
6
    <title>Template::Plugin</title>
 
7
    <link rel="stylesheet" type="text/css" href="../../css/blue.css" title="Clear Blue">
 
8
    <link rel="alternate stylesheet" type="text/css" href="../../css/orange.css" title="Clear Orange">
 
9
    <link rel="alternate stylesheet" type="text/css" href="../../css/green.css" title="Clear Green">
 
10
    <link rel="alternate stylesheet" type="text/css" href="../../css/purple.css" title="Clear Purple">
 
11
    <link rel="alternate stylesheet" type="text/css" href="../../css/grey.css" title="Clear Grey">
 
12
    <!--[if IE 6]>
 
13
    <link rel="stylesheet" type="text/css" href="../../css/ie6.css" />
 
14
    <![endif]-->
 
15
    <link rel="stylesheet" type="text/css" href="/css/print.css" media="print">
 
16
    <script type="text/javascript" src="../../js/tt2.js"></script>
 
17
    <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
 
18
    <meta name="author" content="Andy Wardley">
 
19
  </head>
 
20
  <body id="body"> 
 
21
    <div id="layout">
 
22
        <div id="header">
 
23
          <a href="../../index.html" id="logo" alt="" title="Click for the Home Page"><span class="alt">TT2 Home Page</span></a>
 
24
          <ul id="trail">
 
25
            <li><a href="../../modules/index.html">Modules</a></li>
 
26
            <li><a href="../../modules/Template/index.html">Template::*</a></li>
 
27
            <li class="last"><a href="../../modules/Template/Plugin.html">Plugin.pm</a></li>
 
28
          </ul>
 
29
          <div class="controls">
 
30
            <a href="#" class="menu show" onclick="widescreen_off(); return false" title="Show Menu">
 
31
              <span class="about">Click to view the menu.  It's very nice.</span>
 
32
            </a>
 
33
            <a href="#" class="menu hide" onclick="widescreen_on();  return false" title="Hide Menu">
 
34
              <span class="about">Click to hide the menu and go all widescreen!</span>
 
35
            </a>
 
36
          
 
37
          <div class="pager">
 
38
            <a href="../../modules/Template/Parser.html" title="Template::Parser" class="go back">Back<span class="about"><h4>Template::Parser</h4>LALR(1) parser for compiling template documents</span></a>
 
39
            <a href="../../modules/Template/index.html" title="Template::* Modules" class="go up">Up<span class="about"><h4>Template::* Modules</h4></span></a>
 
40
            <a href="../../modules/Template/Plugin/index.html" title="Template::Plugin::* Modules" class="go next">Next<span class="about"><h4>Template::Plugin::* Modules</h4></span></a>
 
41
          </div>
 
42
          </div>
 
43
          <h1 class="headline">Template::Plugin</h1>
 
44
          <h2 class="subhead">Base class for Template Toolkit plugins</h1>
 
45
        
 
46
        </div>
 
47
        <div id="page">
 
48
          <div id="sidebar">
 
49
            <a href="../../index.html" id="logo"></a>
 
50
            <div id="menu">
 
51
              <ul class="menu">
 
52
                <li class="l0 first"><a href="../../manual/index.html">Manual</a></li>
 
53
                <li class="l0"><a href="../../modules/index.html" class="warm">Modules</a></li>
 
54
                <li class="l1"><a href="../../modules/Template.html">Template.pm</a></li>
 
55
                <li class="l1"><a href="../../modules/Template/index.html" class="warm">Template::*</a></li>
 
56
                <li class="l2"><a href="../../modules/Template/Base.html">Base.pm</a></li>
 
57
                <li class="l2"><a href="../../modules/Template/Config.html">Config.pm</a></li>
 
58
                <li class="l2"><a href="../../modules/Template/Constants.html">Constants.pm</a></li>
 
59
                <li class="l2"><a href="../../modules/Template/Context.html">Context.pm</a></li>
 
60
                <li class="l2"><a href="../../modules/Template/Directive.html">Directive.pm</a></li>
 
61
                <li class="l2"><a href="../../modules/Template/Document.html">Document.pm</a></li>
 
62
                <li class="l2"><a href="../../modules/Template/Exception.html">Exception.pm</a></li>
 
63
                <li class="l2"><a href="../../modules/Template/Filters.html">Filters.pm</a></li>
 
64
                <li class="l2"><a href="../../modules/Template/Grammar.html">Grammar.pm</a></li>
 
65
                <li class="l2"><a href="../../modules/Template/Iterator.html">Iterator.pm</a></li>
 
66
                <li class="l2"><a href="../../modules/Template/Namespace/index.html">Namespace::*</a></li>
 
67
                <li class="l2"><a href="../../modules/Template/Parser.html">Parser.pm</a></li>
 
68
                <li class="l2"><a href="../../modules/Template/Plugin.html" class="warm">Plugin.pm</a></li>
 
69
                <li class="l2"><a href="../../modules/Template/Plugin/index.html">Plugin::*</a></li>
 
70
                <li class="l2"><a href="../../modules/Template/Plugins.html">Plugins.pm</a></li>
 
71
                <li class="l2"><a href="../../modules/Template/Provider.html">Provider.pm</a></li>
 
72
                <li class="l2"><a href="../../modules/Template/Service.html">Service.pm</a></li>
 
73
                <li class="l2"><a href="../../modules/Template/Stash.html">Stash.pm</a></li>
 
74
                <li class="l2"><a href="../../modules/Template/Stash/index.html">Stash::*</a></li>
 
75
                <li class="l2"><a href="../../modules/Template/Test.html">Test.pm</a></li>
 
76
                <li class="l2"><a href="../../modules/Template/VMethods.html">VMethods.pm</a></li>
 
77
                <li class="l2"><a href="../../modules/Template/View.html">View.pm</a></li>
 
78
                <li class="l0"><a href="../../tools/index.html">Tools</a></li>
 
79
                <li class="l0 last"><a href="../../tutorial/index.html">Tutorial</a></li>
 
80
              </ul>
 
81
              <div class="foot"></div>
 
82
            </div>
 
83
          </div>
 
84
          <div id="content">
 
85
          <div class="section">
 
86
            <div class="head">
 
87
              <h1 id="contents" onclick="switch_section(this)" title="Click title to show/hide section content.">Contents</h1>
 
88
              <a href="#body" class="top" title="Back up to the top of the page" >Top</a>
 
89
            </div>
 
90
            <div class="body">
 
91
              <ul class="toc">
 
92
                  <li class=""><a href="#SYNOPSIS">SYNOPSIS</a></li>
 
93
                  <li class=""><a href="#DESCRIPTION">DESCRIPTION</a></li>
 
94
                  <li class=""><a href="#METHODS">METHODS</a></li>
 
95
                  <li class="sub"><a href="#method_load">load($context)</a></li>
 
96
                  <li class="sub"><a href="#method_new">new($context, @params)</a></li>
 
97
                  <li class="sub"><a href="#method_error">error($error)</a></li>
 
98
                  <li class=""><a href="#DEEPER_MAGIC">DEEPER MAGIC</a></li>
 
99
                  <li class=""><a href="#AUTHOR">AUTHOR</a></li>
 
100
                  <li class=""><a href="#COPYRIGHT">COPYRIGHT</a></li>
 
101
                  <li class=""><a href="#SEE_ALSO">SEE ALSO</a></li>
 
102
              
 
103
              </ul>
 
104
            </div>
 
105
          </div>
 
106
          
 
107
                <div class="pod">
 
108
            <div class="section">
 
109
              <div class="head">
 
110
                <h1 id="SYNOPSIS" onclick="switch_section(this)" title="Click title to show/hide section content.">SYNOPSIS</h1>
 
111
                <a href="#body" class="top" title="Back up to the top of the page" >Top</a>
 
112
              </div>
 
113
              <div class="body">
 
114
                <pre>package MyOrg::Template::Plugin::MyPlugin;
 
115
use base qw( Template::Plugin );
 
116
use Template::Plugin;
 
117
use MyModule;
 
118
 
 
119
sub new {
 
120
    my $class   = shift;
 
121
    my $context = shift;
 
122
    bless {
 
123
        ...
 
124
    }, $class;
 
125
}</pre>
 
126
              </div>
 
127
            </div>
 
128
            <div class="section">
 
129
              <div class="head">
 
130
                <h1 id="DESCRIPTION" onclick="switch_section(this)" title="Click title to show/hide section content.">DESCRIPTION</h1>
 
131
                <a href="#body" class="top" title="Back up to the top of the page" >Top</a>
 
132
              </div>
 
133
              <div class="body">
 
134
                <p>
 
135
                      A "plugin" for the Template Toolkit is simply a Perl module which exists
 
136
                      in a known package location (e.g. <code>Template::Plugin::*</code>) and
 
137
                      conforms to a regular standard, allowing it to be loaded and used
 
138
                      automatically.
 
139
                    </p>
 
140
                    <p>
 
141
                      The <code>Template::Plugin</code> module defines a base class from which
 
142
                      other plugin modules can be derived. A plugin does not have to be derived
 
143
                      from Template::Plugin but should at least conform to its object-oriented
 
144
                      interface.
 
145
                    </p>
 
146
                    <p>
 
147
                      It is recommended that you create plugins in your own package namespace
 
148
                      to avoid conflict with toolkit plugins. e.g.
 
149
                    </p>
 
150
                    <pre>package MyOrg::Template::Plugin::FooBar;</pre>
 
151
                    <p>
 
152
                      Use the <a href="../../manual/Config.html#section_PLUGIN_BASE">PLUGIN_BASE</a> option to specify the namespace
 
153
                      that you use. e.g.
 
154
                    </p>
 
155
                    <pre>use Template;
 
156
my $template = Template-&gt;new({ 
 
157
    PLUGIN_BASE =&gt; 'MyOrg::Template::Plugin',
 
158
});</pre>
 
159
              </div>
 
160
            </div>
 
161
            <div class="section">
 
162
              <div class="head">
 
163
                <h1 id="METHODS" onclick="switch_section(this)" title="Click title to show/hide section content.">METHODS</h1>
 
164
                <a href="#body" class="top" title="Back up to the top of the page" >Top</a>
 
165
              </div>
 
166
              <div class="body">
 
167
                <p>
 
168
                      The following methods form the basic interface between the Template
 
169
                      Toolkit and plugin modules.
 
170
                    </p>
 
171
                    <div class="subsection">
 
172
                  <div class="head">
 
173
                    <h2 id="method_load" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">load($context)</h2>
 
174
                    <a href="#body" class="top" title="Back up to the top of the page" >Top</a>
 
175
                  </div>
 
176
                  <div class="body">
 
177
                    <p>
 
178
                          This method is called by the Template Toolkit when the plugin module is
 
179
                          first loaded. It is called as a package method and thus implicitly
 
180
                          receives the package name as the first parameter. A reference to the <a
 
181
                          href="../../modules/Template/Context.html">Template::Context</a>
 
182
                          object loading the plugin is also passed. The default behaviour for the
 
183
                          <code>load()</code> method is to simply return the class name. The
 
184
                          calling context then uses this class name to call the <code>new()</code>
 
185
                          package method.
 
186
                        </p>
 
187
                        <pre>package MyPlugin;
 
188
 
 
189
sub load {               # called as MyPlugin-&gt;load($context)
 
190
    my ($class, $context) = @_;
 
191
    return $class;       # returns 'MyPlugin'
 
192
}</pre>
 
193
                  </div>
 
194
                </div>    <div class="subsection">
 
195
                  <div class="head">
 
196
                    <h2 id="method_new" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">new($context, @params)</h2>
 
197
                    <a href="#body" class="top" title="Back up to the top of the page" >Top</a>
 
198
                  </div>
 
199
                  <div class="body">
 
200
                    <p>
 
201
                          This method is called to instantiate a new plugin object for the
 
202
                          <code>USE</code> directive. It is called as a package method against the
 
203
                          class name returned by <a href="#method_load">load()</a>. A reference to
 
204
                          the <a href="../../modules/Template/Context.html">Template::Context</a> object creating the plugin is passed, along
 
205
                          with any additional parameters specified in the <code>USE</code>
 
206
                          directive.
 
207
                        </p>
 
208
                        <pre>sub new {                # called as MyPlugin-&gt;new($context)
 
209
    my ($class, $context, @params) = @_;
 
210
    bless {
 
211
        _CONTEXT =&gt; $context,
 
212
    }, $class;           # returns blessed MyPlugin object
 
213
}</pre>
 
214
                  </div>
 
215
                </div>    <div class="subsection">
 
216
                  <div class="head">
 
217
                    <h2 id="method_error" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">error($error)</h2>
 
218
                    <a href="#body" class="top" title="Back up to the top of the page" >Top</a>
 
219
                  </div>
 
220
                  <div class="body">
 
221
                    <p>
 
222
                          This method, inherited from the <a href="../../modules/Template/Base.html">Template::Base</a> module, is used for reporting and returning
 
223
                          errors. It can be called as a package method to set/return the
 
224
                          <code>$ERROR</code> package variable, or as an object method to
 
225
                          set/return the object <code>_ERROR</code> member. When called with an
 
226
                          argument, it sets the relevant variable and returns <code>undef.</code>
 
227
                          When called without an argument, it returns the value of the variable.
 
228
                        </p>
 
229
                        <pre>package MyPlugin;
 
230
use base 'Template::Plugin';
 
231
 
 
232
sub new {
 
233
    my ($class, $context, $dsn) = @_;
 
234
 
 
235
    return $class-&gt;error('No data source specified')
 
236
        unless $dsn;
 
237
 
 
238
    bless {
 
239
        _DSN =&gt; $dsn,
 
240
    }, $class;
 
241
}</pre>
 
242
                        <pre>package main;
 
243
 
 
244
my $something = MyPlugin-&gt;new()
 
245
    || die MyPlugin-&gt;error(), "\n";
 
246
 
 
247
$something-&gt;do_something()
 
248
    || die $something-&gt;error(), "\n";</pre>
 
249
                  </div>
 
250
                </div>
 
251
              </div>
 
252
            </div>
 
253
            <div class="section">
 
254
              <div class="head">
 
255
                <h1 id="DEEPER_MAGIC" onclick="switch_section(this)" title="Click title to show/hide section content.">DEEPER MAGIC</h1>
 
256
                <a href="#body" class="top" title="Back up to the top of the page" >Top</a>
 
257
              </div>
 
258
              <div class="body">
 
259
                <p>
 
260
                      The <a href="../../modules/Template/Context.html">Template::Context</a> object that handles the loading and use of
 
261
                      plugins calls the <a href="#method_new">new()</a> and <a
 
262
                      href="#method_error">error()</a> methods against the package name
 
263
                      returned by the <a href="#method_load">load()</a> method. In pseudo-code
 
264
                      terms looks something like this:
 
265
                    </p>
 
266
                    <pre>$class  = MyPlugin-&gt;load($context);       # returns 'MyPlugin'
 
267
 
 
268
$object = $class-&gt;new($context, @params)  # MyPlugin-&gt;new(...)
 
269
    || die $class-&gt;error();               # MyPlugin-&gt;error()</pre>
 
270
                    <p>
 
271
                      The <a href="#method_load">load()</a> method may alterately return a
 
272
                      blessed reference to an object instance. In this case, <a
 
273
                      href="#method_new">new()</a> and <a href="#method_error">error()</a> are
 
274
                      then called as <i>object</i> methods against that prototype instance.
 
275
                    </p>
 
276
                    <pre>package YourPlugin;
 
277
 
 
278
sub load {
 
279
    my ($class, $context) = @_;
 
280
    bless {
 
281
        _CONTEXT =&gt; $context,
 
282
    }, $class;
 
283
}
 
284
 
 
285
sub new {
 
286
    my ($self, $context, @params) = @_;
 
287
    return $self;
 
288
}</pre>
 
289
                    <p>
 
290
                      In this example, we have implemented a 'Singleton' plugin. One object
 
291
                      gets created when <a href="#method_load">load()</a> is called and this
 
292
                      simply returns itself for each call to <a href="#method_new">new().</a>
 
293
                    </p>
 
294
                    <p>
 
295
                      Another implementation might require individual objects to be created for
 
296
                      every call to <a href="#method_new">new(),</a> but with each object
 
297
                      sharing a reference to some other object to maintain cached data,
 
298
                      database handles, etc. This pseudo-code example demonstrates the
 
299
                      principle.
 
300
                    </p>
 
301
                    <pre>package MyServer;
 
302
 
 
303
sub load {
 
304
    my ($class, $context) = @_;
 
305
    bless {
 
306
        _CONTEXT =&gt; $context,
 
307
        _CACHE   =&gt; { },
 
308
    }, $class;
 
309
}
 
310
 
 
311
sub new {
 
312
    my ($self, $context, @params) = @_;
 
313
    MyClient-&gt;new($self, @params);
 
314
}
 
315
 
 
316
sub add_to_cache   { ... }
 
317
 
 
318
sub get_from_cache { ... }</pre>
 
319
                    <pre>package MyClient;
 
320
 
 
321
sub new {
 
322
    my ($class, $server, $blah) = @_;
 
323
    bless {
 
324
        _SERVER =&gt; $server,
 
325
        _BLAH   =&gt; $blah,
 
326
    }, $class;
 
327
}
 
328
 
 
329
sub get {
 
330
    my $self = shift;
 
331
    $self-&gt;{ _SERVER }-&gt;get_from_cache(@_);
 
332
}
 
333
 
 
334
sub put {
 
335
    my $self = shift;
 
336
    $self-&gt;{ _SERVER }-&gt;add_to_cache(@_);
 
337
}</pre>
 
338
                    <p>
 
339
                      When the plugin is loaded, a <code>MyServer</code> instance is created.
 
340
                      The <a href="#method_new">new()</a> method is called against this object
 
341
                      which instantiates and returns a <code>MyClient</code> object, primed to
 
342
                      communicate with the creating <code>MyServer</code>.
 
343
                    </p>
 
344
              </div>
 
345
            </div>
 
346
            <div class="section">
 
347
              <div class="head">
 
348
                <h1 id="AUTHOR" onclick="switch_section(this)" title="Click title to show/hide section content.">AUTHOR</h1>
 
349
                <a href="#body" class="top" title="Back up to the top of the page" >Top</a>
 
350
              </div>
 
351
              <div class="body">
 
352
                <p>
 
353
                      Andy Wardley &lt;abw@wardley.org&gt; <a
 
354
                      href="http://wardley.org/">http://wardley.org/</a>
 
355
                    </p>
 
356
              </div>
 
357
            </div>
 
358
            <div class="section">
 
359
              <div class="head">
 
360
                <h1 id="COPYRIGHT" onclick="switch_section(this)" title="Click title to show/hide section content.">COPYRIGHT</h1>
 
361
                <a href="#body" class="top" title="Back up to the top of the page" >Top</a>
 
362
              </div>
 
363
              <div class="body">
 
364
                <p>
 
365
                      Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
 
366
                    </p>
 
367
                    <p>
 
368
                      This module is free software; you can redistribute it and/or modify it
 
369
                      under the same terms as Perl itself.
 
370
                    </p>
 
371
              </div>
 
372
            </div>
 
373
            <div class="section">
 
374
              <div class="head">
 
375
                <h1 id="SEE_ALSO" onclick="switch_section(this)" title="Click title to show/hide section content.">SEE ALSO</h1>
 
376
                <a href="#body" class="top" title="Back up to the top of the page" >Top</a>
 
377
              </div>
 
378
              <div class="body">
 
379
                <p>
 
380
                      <a href="../../modules/Template.html">Template</a>, <a href="../../modules/Template/Plugins.html">Template::Plugins</a>, <a href="../../modules/Template/Context.html">Template::Context</a>
 
381
                    </p>
 
382
              </div>
 
383
            </div>
 
384
            
 
385
            </div></div>
 
386
          <br class="clear" />
 
387
          <div class="pageinfo">
 
388
            /modules/Template/Plugin.html last modified 10:55:06 31-May-2007
 
389
          </div>
 
390
        </div>
 
391
        
 
392
        <div id="footer">
 
393
          <a href="http://opensource.org/" class="osi"></a>
 
394
          <div class="controls">
 
395
          <div class="pager">
 
396
            <a href="../../modules/Template/Parser.html" title="Template::Parser" class="go back">Back<span class="about"><h4>Template::Parser</h4></span></a>
 
397
            <a href="../../modules/Template/index.html" title="Template::* Modules" class="go up">Up<span class="about"><h4>Template::* Modules</h4></span></a>
 
398
            <a href="../../modules/Template/Plugin/index.html" title="Template::Plugin::* Modules" class="go next">Next<span class="about"><h4>Template::Plugin::* Modules</h4></span></a>
 
399
          </div>
 
400
          </div>
 
401
          <div class="copyright">
 
402
            Copyright &copy; 1996-2007 <a href="http://wardley.org/">Andy Wardley</a>.  All Rights Reserved.
 
403
          </div>
 
404
          <div class="licence">
 
405
            The <a href="http://template-toolkit.org/">Template Toolkit</a> is <a href="http://opensource.org/">Open Source</a> software.
 
406
            You can redistribute and/or modify it under the terms of the <a href="http://www.opensource.org/licenses/gpl-license.php">GNU Public Licence</a>
 
407
            or the <a href="http://www.opensource.org/licenses/artistic-license.php">Perl Artistic Licence</a>.
 
408
          </div>
 
409
        </div>
 
410
        <div id="palette">
 
411
          <ul>
 
412
            <li class="first"><a href="#" class="blue" onclick="set_style('Clear Blue')"></a></li>
 
413
            <li><a href="#" class="orange" onclick="set_style('Clear Orange')"></a></li>
 
414
            <li><a href="#" class="green" onclick="set_style('Clear Green')"></a></li>
 
415
            <li><a href="#" class="purple" onclick="set_style('Clear Purple')"></a></li>
 
416
            <li><a href="#" class="grey" onclick="set_style('Clear Grey')"></a></li>
 
417
          </ul>
 
418
        </div>
 
419
    </div>  </body>
 
420
</html>