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
25 conforms to a regular standard, allowing it to be loaded and used
26 automatically.
27 The "Template::Plugin" module defines a base class from which other
29 plugin modules can be derived. A plugin does not have to be derived
30 from Template::Plugin but should at least conform to its object-
31 oriented 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 module is
51 first loaded. It is called as a package method and thus implicitly
52 receives the package name as the first parameter. A reference to the
53 Template::Context object loading the plugin is also passed. The
54 default behaviour for the "load()" method is to simply return the class
55 name. The calling context then uses this class name to call the
56 "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 "USE"
67 directive. It is called as a package method against the class name
68 returned by load(). A reference to the Template::Context object
69 creating the plugin is passed, along with any additional parameters
70 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 method
82 to set/return the $ERROR package variable, or as an object method to
83 set/return the object "_ERROR" member. When called with an argument,
84 it sets the relevant variable and returns "undef." When called without
85 an argument, it returns the value of the variable.
86 package MyPlugin;
88 use base 'Template::Plugin';
89 sub new {
91 my ($class, $context, $dsn) = @_;
92 return $class->error('No data source specified')
94 unless $dsn;
95 bless {
97 _DSN => $dsn,
98 }, $class;
99 }
100 package main;
102 my $something = MyPlugin->new()
104 || die MyPlugin->error(), "\n";
105 $something->do_something()
107 || die $something->error(), "\n";
108
110 The Template::Context object that handles the loading and use of
111 plugins calls the new() and error() methods against the package name
112 returned by the load() method. In pseudo-code terms looks something
113 like this:
114 $class = MyPlugin->load($context); # returns 'MyPlugin'
116 $object = $class->new($context, @params) # MyPlugin->new(...)
118 || die $class->error(); # MyPlugin->error()
119 The load() method may alterately return a blessed reference to an
121 object instance. In this case, new() and error() are then called as
122 object methods against that prototype instance.
123 package YourPlugin;
125 sub load {
127 my ($class, $context) = @_;
128 bless {
129 _CONTEXT => $context,
130 }, $class;
131 }
132 sub new {
134 my ($self, $context, @params) = @_;
135 return $self;
136 }
137 In this example, we have implemented a 'Singleton' plugin. One object
139 gets created when load() is called and this simply returns itself for
140 each call to new().
141 Another implementation might require individual objects to be created
143 for every call to new(), but with each object sharing a reference to
144 some other object to maintain cached data, database handles, etc. This
145 pseudo-code example demonstrates the principle.
146 package MyServer;
148 sub load {
150 my ($class, $context) = @_;
151 bless {
152 _CONTEXT => $context,
153 _CACHE => { },
154 }, $class;
155 }
156 sub new {
158 my ($self, $context, @params) = @_;
159 MyClient->new($self, @params);
160 }
161 sub add_to_cache { ... }
163 sub get_from_cache { ... }
165 package MyClient;
167 sub new {
169 my ($class, $server, $blah) = @_;
170 bless {
171 _SERVER => $server,
172 _BLAH => $blah,
173 }, $class;
174 }
175 sub get {
177 my $self = shift;
178 $self->{ _SERVER }->get_from_cache(@_);
179 }
180 sub put {
182 my $self = shift;
183 $self->{ _SERVER }->add_to_cache(@_);
184 }
185 When the plugin is loaded, a "MyServer" instance is created. The new()
187 method is called against this object which instantiates and returns a
188 "MyClient" object, primed to communicate with the creating "MyServer".
189
191 Andy Wardley <abw@wardley.org> <http://wardley.org/>
192
194 Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
195 This module is free software; you can redistribute it and/or modify it
197 under the same terms as Perl itself.
198
200 Template, Template::Plugins, Template::Context
201perl v5.16.3 2011-12-20 Template::Plugin(3)