Your IP : 18.223.211.43
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Strict//EN">
<html>
<head>
<title>Template::Plugin</title>
<link rel="stylesheet" type="text/css" href="../../css/blue.css" title="Clear Blue">
<link rel="alternate stylesheet" type="text/css" href="../../css/orange.css" title="Clear Orange">
<link rel="alternate stylesheet" type="text/css" href="../../css/green.css" title="Clear Green">
<link rel="alternate stylesheet" type="text/css" href="../../css/purple.css" title="Clear Purple">
<link rel="alternate stylesheet" type="text/css" href="../../css/grey.css" title="Clear Grey">
<!--[if IE 6]>
<link rel="stylesheet" type="text/css" href="../../css/ie6.css" />
<![endif]-->
<link rel="stylesheet" type="text/css" href="/css/print.css" media="print">
<script type="text/javascript" src="../../js/tt2.js"></script>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<meta name="author" content="Andy Wardley">
</head>
<body id="body">
<div id="layout">
<div id="header">
<a href="../../index.html" id="logo" alt="" title="Click for the Home Page"><span class="alt">TT2 Home Page</span></a>
<ul id="trail">
<li><a href="../../modules/index.html">Modules</a></li>
<li><a href="../../modules/Template/index.html">Template::*</a></li>
<li class="last"><a href="../../modules/Template/Plugin.html">Plugin.pm</a></li>
</ul>
<div class="controls">
<a href="#" class="menu show" onclick="widescreen_off(); return false" title="Show Menu">
<span class="about">Click to view the menu. It's very nice.</span>
</a>
<a href="#" class="menu hide" onclick="widescreen_on(); return false" title="Hide Menu">
<span class="about">Click to hide the menu and go all widescreen!</span>
</a>
<div class="pager">
<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>
<a href="../../modules/Template/index.html" title="Template::* Modules" class="go up">Up<span class="about"><h4>Template::* Modules</h4></span></a>
<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>
</div>
</div>
<h1 class="headline">Template::Plugin</h1>
<h2 class="subhead">Base class for Template Toolkit plugins</h1>
</div>
<div id="page">
<div id="sidebar">
<a href="../../index.html" id="logo"></a>
<div id="menu">
<ul class="menu">
<li class="l0 first"><a href="../../manual/index.html">Manual</a></li>
<li class="l0"><a href="../../modules/index.html" class="warm">Modules</a></li>
<li class="l1"><a href="../../modules/Template.html">Template.pm</a></li>
<li class="l1"><a href="../../modules/Template/index.html" class="warm">Template::*</a></li>
<li class="l2"><a href="../../modules/Template/Base.html">Base.pm</a></li>
<li class="l2"><a href="../../modules/Template/Config.html">Config.pm</a></li>
<li class="l2"><a href="../../modules/Template/Constants.html">Constants.pm</a></li>
<li class="l2"><a href="../../modules/Template/Context.html">Context.pm</a></li>
<li class="l2"><a href="../../modules/Template/Directive.html">Directive.pm</a></li>
<li class="l2"><a href="../../modules/Template/Document.html">Document.pm</a></li>
<li class="l2"><a href="../../modules/Template/Exception.html">Exception.pm</a></li>
<li class="l2"><a href="../../modules/Template/Filters.html">Filters.pm</a></li>
<li class="l2"><a href="../../modules/Template/Grammar.html">Grammar.pm</a></li>
<li class="l2"><a href="../../modules/Template/Iterator.html">Iterator.pm</a></li>
<li class="l2"><a href="../../modules/Template/Namespace/index.html">Namespace::*</a></li>
<li class="l2"><a href="../../modules/Template/Parser.html">Parser.pm</a></li>
<li class="l2"><a href="../../modules/Template/Plugin.html" class="warm">Plugin.pm</a></li>
<li class="l2"><a href="../../modules/Template/Plugin/index.html">Plugin::*</a></li>
<li class="l2"><a href="../../modules/Template/Plugins.html">Plugins.pm</a></li>
<li class="l2"><a href="../../modules/Template/Provider.html">Provider.pm</a></li>
<li class="l2"><a href="../../modules/Template/Service.html">Service.pm</a></li>
<li class="l2"><a href="../../modules/Template/Stash.html">Stash.pm</a></li>
<li class="l2"><a href="../../modules/Template/Stash/index.html">Stash::*</a></li>
<li class="l2"><a href="../../modules/Template/Test.html">Test.pm</a></li>
<li class="l2"><a href="../../modules/Template/VMethods.html">VMethods.pm</a></li>
<li class="l2"><a href="../../modules/Template/View.html">View.pm</a></li>
<li class="l0"><a href="../../tools/index.html">Tools</a></li>
<li class="l0 last"><a href="../../tutorial/index.html">Tutorial</a></li>
</ul>
<div class="foot"></div>
</div>
</div>
<div id="content">
<div class="section">
<div class="head">
<h1 id="contents" onclick="switch_section(this)" title="Click title to show/hide section content.">Contents</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<ul class="toc">
<li class=""><a href="#SYNOPSIS">SYNOPSIS</a></li>
<li class=""><a href="#DESCRIPTION">DESCRIPTION</a></li>
<li class=""><a href="#METHODS">METHODS</a></li>
<li class="sub"><a href="#method_load">load($context)</a></li>
<li class="sub"><a href="#method_new">new($context, @params)</a></li>
<li class="sub"><a href="#method_error">error($error)</a></li>
<li class=""><a href="#DEEPER_MAGIC">DEEPER MAGIC</a></li>
<li class=""><a href="#AUTHOR">AUTHOR</a></li>
<li class=""><a href="#COPYRIGHT">COPYRIGHT</a></li>
<li class=""><a href="#SEE_ALSO">SEE ALSO</a></li>
</ul>
</div>
</div>
<div class="pod">
<div class="section">
<div class="head">
<h1 id="SYNOPSIS" onclick="switch_section(this)" title="Click title to show/hide section content.">SYNOPSIS</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<pre>package MyOrg::Template::Plugin::MyPlugin;
use base qw( Template::Plugin );
use Template::Plugin;
use MyModule;
sub new {
my $class = shift;
my $context = shift;
bless {
...
}, $class;
}</pre>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="DESCRIPTION" onclick="switch_section(this)" title="Click title to show/hide section content.">DESCRIPTION</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
A "plugin" for the Template Toolkit is simply a Perl module which exists
in a known package location (e.g. <code>Template::Plugin::*</code>) and
conforms to a regular standard, allowing it to be loaded and used
automatically.
</p>
<p>
The <code>Template::Plugin</code> module defines a base class from which
other plugin modules can be derived. A plugin does not have to be derived
from Template::Plugin but should at least conform to its object-oriented
interface.
</p>
<p>
It is recommended that you create plugins in your own package namespace
to avoid conflict with toolkit plugins. e.g.
</p>
<pre>package MyOrg::Template::Plugin::FooBar;</pre>
<p>
Use the <a href="../../manual/Config.html#section_PLUGIN_BASE">PLUGIN_BASE</a> option to specify the namespace
that you use. e.g.
</p>
<pre>use Template;
my $template = Template->new({
PLUGIN_BASE => 'MyOrg::Template::Plugin',
});</pre>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="METHODS" onclick="switch_section(this)" title="Click title to show/hide section content.">METHODS</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The following methods form the basic interface between the Template
Toolkit and plugin modules.
</p>
<div class="subsection">
<div class="head">
<h2 id="method_load" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">load($context)</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
This method is called by the Template Toolkit when the plugin module is
first loaded. It is called as a package method and thus implicitly
receives the package name as the first parameter. A reference to the <a
href="../../modules/Template/Context.html">Template::Context</a>
object loading the plugin is also passed. The default behaviour for the
<code>load()</code> method is to simply return the class name. The
calling context then uses this class name to call the <code>new()</code>
package method.
</p>
<pre>package MyPlugin;
sub load { # called as MyPlugin->load($context)
my ($class, $context) = @_;
return $class; # returns 'MyPlugin'
}</pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_new" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">new($context, @params)</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
This method is called to instantiate a new plugin object for the
<code>USE</code> directive. It is called as a package method against the
class name returned by <a href="#method_load">load()</a>. A reference to
the <a href="../../modules/Template/Context.html">Template::Context</a> object creating the plugin is passed, along
with any additional parameters specified in the <code>USE</code>
directive.
</p>
<pre>sub new { # called as MyPlugin->new($context)
my ($class, $context, @params) = @_;
bless {
_CONTEXT => $context,
}, $class; # returns blessed MyPlugin object
}</pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_error" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">error($error)</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
This method, inherited from the <a href="../../modules/Template/Base.html">Template::Base</a> module, is used for reporting and returning
errors. It can be called as a package method to set/return the
<code>$ERROR</code> package variable, or as an object method to
set/return the object <code>_ERROR</code> member. When called with an
argument, it sets the relevant variable and returns <code>undef.</code>
When called without an argument, it returns the value of the variable.
</p>
<pre>package MyPlugin;
use base 'Template::Plugin';
sub new {
my ($class, $context, $dsn) = @_;
return $class->error('No data source specified')
unless $dsn;
bless {
_DSN => $dsn,
}, $class;
}</pre>
<pre>package main;
my $something = MyPlugin->new()
|| die MyPlugin->error(), "\n";
$something->do_something()
|| die $something->error(), "\n";</pre>
</div>
</div>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="DEEPER_MAGIC" onclick="switch_section(this)" title="Click title to show/hide section content.">DEEPER MAGIC</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <a href="../../modules/Template/Context.html">Template::Context</a> object that handles the loading and use of
plugins calls the <a href="#method_new">new()</a> and <a
href="#method_error">error()</a> methods against the package name
returned by the <a href="#method_load">load()</a> method. In pseudo-code
terms looks something like this:
</p>
<pre>$class = MyPlugin->load($context); # returns 'MyPlugin'
$object = $class->new($context, @params) # MyPlugin->new(...)
|| die $class->error(); # MyPlugin->error()</pre>
<p>
The <a href="#method_load">load()</a> method may alterately return a
blessed reference to an object instance. In this case, <a
href="#method_new">new()</a> and <a href="#method_error">error()</a> are
then called as <i>object</i> methods against that prototype instance.
</p>
<pre>package YourPlugin;
sub load {
my ($class, $context) = @_;
bless {
_CONTEXT => $context,
}, $class;
}
sub new {
my ($self, $context, @params) = @_;
return $self;
}</pre>
<p>
In this example, we have implemented a 'Singleton' plugin. One object
gets created when <a href="#method_load">load()</a> is called and this
simply returns itself for each call to <a href="#method_new">new().</a>
</p>
<p>
Another implementation might require individual objects to be created for
every call to <a href="#method_new">new(),</a> but with each object
sharing a reference to some other object to maintain cached data,
database handles, etc. This pseudo-code example demonstrates the
principle.
</p>
<pre>package MyServer;
sub load {
my ($class, $context) = @_;
bless {
_CONTEXT => $context,
_CACHE => { },
}, $class;
}
sub new {
my ($self, $context, @params) = @_;
MyClient->new($self, @params);
}
sub add_to_cache { ... }
sub get_from_cache { ... }</pre>
<pre>package MyClient;
sub new {
my ($class, $server, $blah) = @_;
bless {
_SERVER => $server,
_BLAH => $blah,
}, $class;
}
sub get {
my $self = shift;
$self->{ _SERVER }->get_from_cache(@_);
}
sub put {
my $self = shift;
$self->{ _SERVER }->add_to_cache(@_);
}</pre>
<p>
When the plugin is loaded, a <code>MyServer</code> instance is created.
The <a href="#method_new">new()</a> method is called against this object
which instantiates and returns a <code>MyClient</code> object, primed to
communicate with the creating <code>MyServer</code>.
</p>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="AUTHOR" onclick="switch_section(this)" title="Click title to show/hide section content.">AUTHOR</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Andy Wardley <abw@wardley.org> <a
href="http://wardley.org/">http://wardley.org/</a>
</p>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="COPYRIGHT" onclick="switch_section(this)" title="Click title to show/hide section content.">COPYRIGHT</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
</p>
<p>
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
</p>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="SEE_ALSO" onclick="switch_section(this)" title="Click title to show/hide section content.">SEE ALSO</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
<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>
</p>
</div>
</div>
</div></div>
<br class="clear" />
<div class="pageinfo">
/modules/Template/Plugin.html last modified 10:55:06 31-May-2007
</div>
</div>
<div id="footer">
<a href="http://opensource.org/" class="osi"></a>
<div class="controls">
<div class="pager">
<a href="../../modules/Template/Parser.html" title="Template::Parser" class="go back">Back<span class="about"><h4>Template::Parser</h4></span></a>
<a href="../../modules/Template/index.html" title="Template::* Modules" class="go up">Up<span class="about"><h4>Template::* Modules</h4></span></a>
<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>
</div>
</div>
<div class="copyright">
Copyright © 1996-2007 <a href="http://wardley.org/">Andy Wardley</a>. All Rights Reserved.
</div>
<div class="licence">
The <a href="http://template-toolkit.org/">Template Toolkit</a> is <a href="http://opensource.org/">Open Source</a> software.
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>
or the <a href="http://www.opensource.org/licenses/artistic-license.php">Perl Artistic Licence</a>.
</div>
</div>
<div id="palette">
<ul>
<li class="first"><a href="#" class="blue" onclick="set_style('Clear Blue')"></a></li>
<li><a href="#" class="orange" onclick="set_style('Clear Orange')"></a></li>
<li><a href="#" class="green" onclick="set_style('Clear Green')"></a></li>
<li><a href="#" class="purple" onclick="set_style('Clear Purple')"></a></li>
<li><a href="#" class="grey" onclick="set_style('Clear Grey')"></a></li>
</ul>
</div>
</div> </body>
</html>