1Template::Plugin(3) User Contributed Perl Documentation Template::Plugin(3)
2
6 Template::Plugin - Base class for Template Toolkit plugins
7
9 package MyOrg::Template::Plugin::MyPlugin;
10 use base qw( Template::Plugin );
11 use Template::Plugin;
12 use MyModule;
13 sub new {
15 my $class = shift;
16 my $context = shift;
17 bless {
18 ...
19 }, $class;
20 }
21
23 A "plugin" for the Template Toolkit is simply a Perl module which
24 exists in a known package location (e.g. Template::Plugin::*) and con‐
25 forms to a regular standard, allowing it to be loaded and used automat‐
26 ically.
27 The Template::Plugin module defines a base class from which other plug‐
29 in modules can be derived. A plugin does not have to be derived from
30 Template::Plugin but should at least conform to its object-oriented
31 interface.
32 It is recommended that you create plugins in your own package namespace
34 to avoid conflict with toolkit plugins. e.g.
35 package MyOrg::Template::Plugin::FooBar;
37 Use the PLUGIN_BASE option to specify the namespace that you use. e.g.
39 use Template;
41 my $template = Template->new({
42 PLUGIN_BASE => 'MyOrg::Template::Plugin',
43 });
44
46 The following methods form the basic interface between the Template
47 Toolkit and plugin modules.
48 load($context)
50 This method is called by the Template Toolkit when the plugin mod‐
51 ule is first loaded. It is called as a package method and thus
52 implicitly receives the package name as the first parameter. A
53 reference to the Template::Context object loading the plugin is
54 also passed. The default behaviour for the load() method is to
55 simply return the class name. The calling context then uses this
56 class name to call the new() package method.
57 package MyPlugin;
59 sub load { # called as MyPlugin->load($context)
61 my ($class, $context) = @_;
62 return $class; # returns 'MyPlugin'
63 }
64 new($context, @params)
66 This method is called to instantiate a new plugin object for the
67 USE directive. It is called as a package method against the class
68 name returned by load(). A reference to the Template::Context
69 object creating the plugin is passed, along with any additional
70 parameters specified in the USE directive.
71 sub new { # called as MyPlugin->new($context)
73 my ($class, $context, @params) = @_;
74 bless {
75 _CONTEXT => $context,
76 }, $class; # returns blessed MyPlugin object
77 }
78 error($error)
80 This method, inherited from the Template::Base module, is used for
81 reporting and returning errors. It can be called as a package
82 method to set/return the $ERROR package variable, or as an object
83 method to set/return the object _ERROR member. When called with an
84 argument, it sets the relevant variable and returns undef. When
85 called without an argument, it returns the value of the variable.
86 sub new {
88 my ($class, $context, $dsn) = @_;
89 return $class->error('No data source specified')
91 unless $dsn;
92 bless {
94 _DSN => $dsn,
95 }, $class;
96 }
97 ...
99 my $something = MyModule->new()
101 ⎪⎪ die MyModule->error(), "\n";
102 $something->do_something()
104 ⎪⎪ die $something->error(), "\n";
105
107 The Template::Context object that handles the loading and use of plug‐
108 ins calls the new() and error() methods against the package name
109 returned by the load() method. In pseudo-code terms, it might look
110 something like this:
111 $class = MyPlugin->load($context); # returns 'MyPlugin'
113 $object = $class->new($context, @params) # MyPlugin->new(...)
115 ⎪⎪ die $class->error(); # MyPlugin->error()
116 The load() method may alterately return a blessed reference to an
118 object instance. In this case, new() and error() are then called as
119 object methods against that prototype instance.
120 package YourPlugin;
122 sub load {
124 my ($class, $context) = @_;
125 bless {
126 _CONTEXT => $context,
127 }, $class;
128 }
129 sub new {
131 my ($self, $context, @params) = @_;
132 return $self;
133 }
134 In this example, we have implemented a 'Singleton' plugin. One object
136 gets created when load() is called and this simply returns itself for
137 each call to new().
138 Another implementation might require individual objects to be created
140 for every call to new(), but with each object sharing a reference to
141 some other object to maintain cached data, database handles, etc. This
142 pseudo-code example demonstrates the principle.
143 package MyServer;
145 sub load {
147 my ($class, $context) = @_;
148 bless {
149 _CONTEXT => $context,
150 _CACHE => { },
151 }, $class;
152 }
153 sub new {
155 my ($self, $context, @params) = @_;
156 MyClient->new($self, @params);
157 }
158 sub add_to_cache { ... }
160 sub get_from_cache { ... }
162 package MyClient;
164 sub new {
166 my ($class, $server, $blah) = @_;
167 bless {
168 _SERVER => $server,
169 _BLAH => $blah,
170 }, $class;
171 }
172 sub get {
174 my $self = shift;
175 $self->{ _SERVER }->get_from_cache(@_);
176 }
177 sub put {
179 my $self = shift;
180 $self->{ _SERVER }->add_to_cache(@_);
181 }
182 When the plugin is loaded, a MyServer instance is created. The new()
184 method is called against this object which instantiates and returns a
185 MyClient object, primed to communicate with the creating MyServer.
186
188 As of version 2.01, the Template::Plugin module no longer provides an
189 AUTOLOAD method to delegate to other objects or classes. This was a
190 badly designed feature that caused more trouble than good. You can
191 easily add your own AUTOLOAD method to perform delegation if you
192 require this kind of functionality.
193
195 Andy Wardley <abw@wardley.org>
196 <http://wardley.org/⎪http://wardley.org/>
198
200 2.7, distributed as part of the Template Toolkit version 2.18, released
201 on 09 February 2007.
202
204 Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
205 This module is free software; you can redistribute it and/or modify it
207 under the same terms as Perl itself.
208
210 Template, Template::Plugins, Template::Context
211perl v5.8.8 2007-02-09 Template::Plugin(3)