Dashboard
PHP:
8.3.33
OS:
Linux
User:
letter7
/
/
usr
/
share
/
doc
/
perl-Template-Toolkit
/
modules
/
Template
📤 Upload
📝 New File
📁 New Folder
Close
Editing: Plugin.html
<!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"> <link rel="alternate stylesheet" type="text/css" href="../../css/print.css" title="Print"> <!--[if IE 6]> <link rel="stylesheet" type="text/css" href="../../css/ie6.css" /> <![endif]--> <!--[if IE 7]> <link rel="stylesheet" type="text/css" href="../../css/ie7.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"><a href="../../tutorial/index.html">Tutorial</a></li> <li class="l0 last"><a href="../../faq/index.html">FAQ</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; } 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 { ... } 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"> <a href="http://template-toolkit.org/docs/modules/Template/Plugin.html">http://template-toolkit.org/docs/modules/Template/Plugin.html</a> </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-2012 <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>
Save
Cancel