Commit | Line | Data |
3fea05b9 |
1 | #============================================================= -*-Perl-*- |
2 | # |
3 | # Template::Plugin |
4 | # |
5 | # DESCRIPTION |
6 | # |
7 | # Module defining a base class for a plugin object which can be loaded |
8 | # and instantiated via the USE directive. |
9 | # |
10 | # AUTHOR |
11 | # Andy Wardley <abw@wardley.org> |
12 | # |
13 | # COPYRIGHT |
14 | # Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. |
15 | # |
16 | # This module is free software; you can redistribute it an/or |
17 | # modify it under the same terms as Perl itself. |
18 | # |
19 | #============================================================================ |
20 | |
21 | package Template::Plugin; |
22 | |
23 | use strict; |
24 | use warnings; |
25 | use base 'Template::Base'; |
26 | |
27 | our $VERSION = 2.70; |
28 | our $DEBUG = 0 unless defined $DEBUG; |
29 | our $ERROR = ''; |
30 | our $AUTOLOAD; |
31 | |
32 | |
33 | #======================================================================== |
34 | # ----- CLASS METHODS ----- |
35 | #======================================================================== |
36 | |
37 | #------------------------------------------------------------------------ |
38 | # load() |
39 | # |
40 | # Class method called when the plugin module is first loaded. It |
41 | # returns the name of a class (by default, its own class) or a prototype |
42 | # object which will be used to instantiate new objects. The new() |
43 | # method is then called against the class name (class method) or |
44 | # prototype object (object method) to create a new instances of the |
45 | # object. |
46 | #------------------------------------------------------------------------ |
47 | |
48 | sub load { |
49 | return $_[0]; |
50 | } |
51 | |
52 | |
53 | #------------------------------------------------------------------------ |
54 | # new($context, $delegate, @params) |
55 | # |
56 | # Object constructor which is called by the Template::Context to |
57 | # instantiate a new Plugin object. This base class constructor is |
58 | # used as a general mechanism to load and delegate to other Perl |
59 | # modules. The context is passed as the first parameter, followed by |
60 | # a reference to a delegate object or the name of the module which |
61 | # should be loaded and instantiated. Any additional parameters passed |
62 | # to the USE directive are forwarded to the new() constructor. |
63 | # |
64 | # A plugin object is returned which has an AUTOLOAD method to delegate |
65 | # requests to the underlying object. |
66 | #------------------------------------------------------------------------ |
67 | |
68 | sub new { |
69 | my $class = shift; |
70 | bless { |
71 | }, $class; |
72 | } |
73 | |
74 | sub old_new { |
75 | my ($class, $context, $delclass, @params) = @_; |
76 | my ($delegate, $delmod); |
77 | |
78 | return $class->error("no context passed to $class constructor\n") |
79 | unless defined $context; |
80 | |
81 | if (ref $delclass) { |
82 | # $delclass contains a reference to a delegate object |
83 | $delegate = $delclass; |
84 | } |
85 | else { |
86 | # delclass is the name of a module to load and instantiate |
87 | ($delmod = $delclass) =~ s|::|/|g; |
88 | |
89 | eval { |
90 | require "$delmod.pm"; |
91 | $delegate = $delclass->new(@params) |
92 | || die "failed to instantiate $delclass object\n"; |
93 | }; |
94 | return $class->error($@) if $@; |
95 | } |
96 | |
97 | bless { |
98 | _CONTEXT => $context, |
99 | _DELEGATE => $delegate, |
100 | _PARAMS => \@params, |
101 | }, $class; |
102 | } |
103 | |
104 | |
105 | #------------------------------------------------------------------------ |
106 | # fail($error) |
107 | # |
108 | # Version 1 error reporting function, now replaced by error() inherited |
109 | # from Template::Base. Raises a "deprecated function" warning and then |
110 | # calls error(). |
111 | #------------------------------------------------------------------------ |
112 | |
113 | sub fail { |
114 | my $class = shift; |
115 | my ($pkg, $file, $line) = caller(); |
116 | warn "Template::Plugin::fail() is deprecated at $file line $line. Please use error()\n"; |
117 | $class->error(@_); |
118 | } |
119 | |
120 | |
121 | #======================================================================== |
122 | # ----- OBJECT METHODS ----- |
123 | #======================================================================== |
124 | |
125 | #------------------------------------------------------------------------ |
126 | # AUTOLOAD |
127 | # |
128 | # General catch-all method which delegates all calls to the _DELEGATE |
129 | # object. |
130 | #------------------------------------------------------------------------ |
131 | |
132 | sub OLD_AUTOLOAD { |
133 | my $self = shift; |
134 | my $method = $AUTOLOAD; |
135 | |
136 | $method =~ s/.*:://; |
137 | return if $method eq 'DESTROY'; |
138 | |
139 | if (ref $self eq 'HASH') { |
140 | my $delegate = $self->{ _DELEGATE } || return; |
141 | return $delegate->$method(@_); |
142 | } |
143 | my ($pkg, $file, $line) = caller(); |
144 | # warn "no such '$method' method called on $self at $file line $line\n"; |
145 | return undef; |
146 | } |
147 | |
148 | |
149 | 1; |
150 | |
151 | __END__ |
152 | |
153 | =head1 NAME |
154 | |
155 | Template::Plugin - Base class for Template Toolkit plugins |
156 | |
157 | =head1 SYNOPSIS |
158 | |
159 | package MyOrg::Template::Plugin::MyPlugin; |
160 | use base qw( Template::Plugin ); |
161 | use Template::Plugin; |
162 | use MyModule; |
163 | |
164 | sub new { |
165 | my $class = shift; |
166 | my $context = shift; |
167 | bless { |
168 | ... |
169 | }, $class; |
170 | } |
171 | |
172 | =head1 DESCRIPTION |
173 | |
174 | A "plugin" for the Template Toolkit is simply a Perl module which |
175 | exists in a known package location (e.g. C<Template::Plugin::*>) and |
176 | conforms to a regular standard, allowing it to be loaded and used |
177 | automatically. |
178 | |
179 | The C<Template::Plugin> module defines a base class from which other |
180 | plugin modules can be derived. A plugin does not have to be derived |
181 | from Template::Plugin but should at least conform to its object-oriented |
182 | interface. |
183 | |
184 | It is recommended that you create plugins in your own package namespace |
185 | to avoid conflict with toolkit plugins. e.g. |
186 | |
187 | package MyOrg::Template::Plugin::FooBar; |
188 | |
189 | Use the L<PLUGIN_BASE|Template::Manual::Config#PLUGIN_BASE> option to specify |
190 | the namespace that you use. e.g. |
191 | |
192 | use Template; |
193 | my $template = Template->new({ |
194 | PLUGIN_BASE => 'MyOrg::Template::Plugin', |
195 | }); |
196 | |
197 | =head1 METHODS |
198 | |
199 | The following methods form the basic interface between the Template |
200 | Toolkit and plugin modules. |
201 | |
202 | =head2 load($context) |
203 | |
204 | This method is called by the Template Toolkit when the plugin module |
205 | is first loaded. It is called as a package method and thus implicitly |
206 | receives the package name as the first parameter. A reference to the |
207 | L<Template::Context> object loading the plugin is also passed. The |
208 | default behaviour for the C<load()> method is to simply return the class |
209 | name. The calling context then uses this class name to call the C<new()> |
210 | package method. |
211 | |
212 | package MyPlugin; |
213 | |
214 | sub load { # called as MyPlugin->load($context) |
215 | my ($class, $context) = @_; |
216 | return $class; # returns 'MyPlugin' |
217 | } |
218 | |
219 | =head2 new($context, @params) |
220 | |
221 | This method is called to instantiate a new plugin object for the C<USE> |
222 | directive. It is called as a package method against the class name returned by |
223 | L<load()>. A reference to the L<Template::Context> object creating the plugin |
224 | is passed, along with any additional parameters specified in the C<USE> |
225 | directive. |
226 | |
227 | sub new { # called as MyPlugin->new($context) |
228 | my ($class, $context, @params) = @_; |
229 | bless { |
230 | _CONTEXT => $context, |
231 | }, $class; # returns blessed MyPlugin object |
232 | } |
233 | |
234 | =head2 error($error) |
235 | |
236 | This method, inherited from the L<Template::Base> module, is used for |
237 | reporting and returning errors. It can be called as a package method |
238 | to set/return the C<$ERROR> package variable, or as an object method to |
239 | set/return the object C<_ERROR> member. When called with an argument, it |
240 | sets the relevant variable and returns C<undef.> When called without an |
241 | argument, it returns the value of the variable. |
242 | |
243 | package MyPlugin; |
244 | use base 'Template::Plugin'; |
245 | |
246 | sub new { |
247 | my ($class, $context, $dsn) = @_; |
248 | |
249 | return $class->error('No data source specified') |
250 | unless $dsn; |
251 | |
252 | bless { |
253 | _DSN => $dsn, |
254 | }, $class; |
255 | } |
256 | |
257 | package main; |
258 | |
259 | my $something = MyPlugin->new() |
260 | || die MyPlugin->error(), "\n"; |
261 | |
262 | $something->do_something() |
263 | || die $something->error(), "\n"; |
264 | |
265 | =head1 DEEPER MAGIC |
266 | |
267 | The L<Template::Context> object that handles the loading and use of plugins |
268 | calls the L<new()> and L<error()> methods against the package name returned by |
269 | the L<load()> method. In pseudo-code terms looks something like this: |
270 | |
271 | $class = MyPlugin->load($context); # returns 'MyPlugin' |
272 | |
273 | $object = $class->new($context, @params) # MyPlugin->new(...) |
274 | || die $class->error(); # MyPlugin->error() |
275 | |
276 | The L<load()> method may alterately return a blessed reference to an |
277 | object instance. In this case, L<new()> and L<error()> are then called as |
278 | I<object> methods against that prototype instance. |
279 | |
280 | package YourPlugin; |
281 | |
282 | sub load { |
283 | my ($class, $context) = @_; |
284 | bless { |
285 | _CONTEXT => $context, |
286 | }, $class; |
287 | } |
288 | |
289 | sub new { |
290 | my ($self, $context, @params) = @_; |
291 | return $self; |
292 | } |
293 | |
294 | In this example, we have implemented a 'Singleton' plugin. One object |
295 | gets created when L<load()> is called and this simply returns itself for |
296 | each call to L<new().> |
297 | |
298 | Another implementation might require individual objects to be created |
299 | for every call to L<new(),> but with each object sharing a reference to |
300 | some other object to maintain cached data, database handles, etc. |
301 | This pseudo-code example demonstrates the principle. |
302 | |
303 | package MyServer; |
304 | |
305 | sub load { |
306 | my ($class, $context) = @_; |
307 | bless { |
308 | _CONTEXT => $context, |
309 | _CACHE => { }, |
310 | }, $class; |
311 | } |
312 | |
313 | sub new { |
314 | my ($self, $context, @params) = @_; |
315 | MyClient->new($self, @params); |
316 | } |
317 | |
318 | sub add_to_cache { ... } |
319 | |
320 | sub get_from_cache { ... } |
321 | |
322 | package MyClient; |
323 | |
324 | sub new { |
325 | my ($class, $server, $blah) = @_; |
326 | bless { |
327 | _SERVER => $server, |
328 | _BLAH => $blah, |
329 | }, $class; |
330 | } |
331 | |
332 | sub get { |
333 | my $self = shift; |
334 | $self->{ _SERVER }->get_from_cache(@_); |
335 | } |
336 | |
337 | sub put { |
338 | my $self = shift; |
339 | $self->{ _SERVER }->add_to_cache(@_); |
340 | } |
341 | |
342 | When the plugin is loaded, a C<MyServer> instance is created. The L<new()> |
343 | method is called against this object which instantiates and returns a C<MyClient> |
344 | object, primed to communicate with the creating C<MyServer>. |
345 | |
346 | =head1 AUTHOR |
347 | |
348 | Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> |
349 | |
350 | =head1 COPYRIGHT |
351 | |
352 | Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. |
353 | |
354 | This module is free software; you can redistribute it and/or |
355 | modify it under the same terms as Perl itself. |
356 | |
357 | =head1 SEE ALSO |
358 | |
359 | L<Template>, L<Template::Plugins>, L<Template::Context> |
360 | |
361 | =cut |
362 | |
363 | # Local Variables: |
364 | # mode: perl |
365 | # perl-indent-level: 4 |
366 | # indent-tabs-mode: nil |
367 | # End: |
368 | # |
369 | # vim: expandtab shiftwidth=4: |