| Current File : //proc/self/root/usr/share/doc/perl-Template-Toolkit-2.24/modules/Template/Plugins.html |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Strict//EN">
<html>
<head>
<title>Template::Plugins</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/Plugins.html">Plugins.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/Plugin/index.html" title="Template::Plugin::* Modules" class="go back">Back<span class="about"><h4>Template::Plugin::* Modules</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/Provider.html" title="Template::Provider" class="go next">Next<span class="about"><h4>Template::Provider</h4>Provider module for loading/compiling templates</span></a>
</div>
</div>
<h1 class="headline">Template::Plugins</h1>
<h2 class="subhead">Plugin provider module</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">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" class="warm">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_new">new(\%params)</a></li>
<li class="sub"><a href="#method_fetch">fetch($name, @args)</a></li>
<li class=""><a href="#CONFIGURATION_OPTIONS">CONFIGURATION OPTIONS</a></li>
<li class="sub"><a href="#section_PLUGINS">PLUGINS</a></li>
<li class="sub"><a href="#section_PLUGIN_BASE">PLUGIN_BASE</a></li>
<li class="sub"><a href="#section_LOAD_PERL">LOAD_PERL</a></li>
<li class="sub"><a href="#section_TOLERANT">TOLERANT</a></li>
<li class="sub"><a href="#section_DEBUG">DEBUG</a></li>
<li class=""><a href="#TEMPLATE_TOOLKIT_PLUGINS">TEMPLATE TOOLKIT PLUGINS</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>use Template::Plugins;
$plugin_provider = Template::Plugins->new(\%options);
($plugin, $error) = $plugin_provider->fetch($name, @args);</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>
The <code>Template::Plugins</code> module defines a provider class which
can be used to load and instantiate Template Toolkit plugin modules.
</p>
</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">
<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(\%params)</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Constructor method which instantiates and returns a reference to a
<code>Template::Plugins</code> object. A reference to a hash array of
configuration items may be passed as a parameter. These are described
below.
</p>
<p>
Note that the <a href="../../modules/Template.html">Template</a>
front-end module creates a <code>Template::Plugins</code> provider,
passing all configuration items. Thus, the examples shown below in the
form:
</p>
<pre>$plugprov = Template::Plugins->new({
PLUGIN_BASE => 'MyTemplate::Plugin',
LOAD_PERL => 1,
...
});</pre>
<p>
can also be used via the <a href="../../modules/Template.html">Template</a> module as:
</p>
<pre>$ttengine = Template->new({
PLUGIN_BASE => 'MyTemplate::Plugin',
LOAD_PERL => 1,
...
});</pre>
<p>
as well as the more explicit form of:
</p>
<pre>$plugprov = Template::Plugins->new({
PLUGIN_BASE => 'MyTemplate::Plugin',
LOAD_PERL => 1,
...
});
$ttengine = Template->new({
LOAD_PLUGINS => [ $plugprov ],
});</pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_fetch" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">fetch($name, @args)</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Called to request that a plugin of a given name be provided. The relevant
module is first loaded (if necessary) and the <a href="../../modules/Template/Plugin.html#method_load">load()</a> class method
called to return the factory class name (usually the same package name)
or a factory object (a prototype). The <a href="../../modules/Template/Plugin.html#method_new">new()</a> method is then
called as a class or object method against the factory, passing all
remaining parameters.
</p>
<p>
Returns a reference to a new plugin object or <code>($error,
STATUS_ERROR)</code> on error. May also return <code>(undef,
STATUS_DECLINED)</code> to decline to serve the request. If
<code>TOLERANT</code> is set then all errors will be returned as
declines.
</p>
</div>
</div>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="CONFIGURATION_OPTIONS" onclick="switch_section(this)" title="Click title to show/hide section content.">CONFIGURATION OPTIONS</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The following list summarises the configuration options that can be
provided to the <code>Template::Plugins</code> <a
href="#method_new">new()</a> constructor. Please consult <a href="../../manual/Config.html">Template::Manual::Config</a>
for further details and examples of each configuration option in use.
</p>
<div class="subsection">
<div class="head">
<h2 id="section_PLUGINS" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">PLUGINS</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <a href="../../manual/Config.html#section_PLUGINS">PLUGINS</a> option can be used to provide a
reference to a hash array that maps plugin names to Perl module names.
</p>
<pre>my $plugins = Template::Plugins->new({
PLUGINS => {
cgi => 'MyOrg::Template::Plugin::CGI',
foo => 'MyOrg::Template::Plugin::Foo',
bar => 'MyOrg::Template::Plugin::Bar',
},
});</pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_PLUGIN_BASE" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">PLUGIN_BASE</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
If a plugin is not defined in the <a href="../../manual/Config.html#section_PLUGINS">PLUGINS</a>
hash then the <a href="../../manual/Config.html#section_PLUGIN_BASE">PLUGIN_BASE</a> is used to attempt to construct
a correct Perl module name which can be successfully loaded.
</p>
<pre># single value PLUGIN_BASE
my $plugins = Template::Plugins->new({
PLUGIN_BASE => 'MyOrg::Template::Plugin',
});
# multiple value PLUGIN_BASE
my $plugins = Template::Plugins->new({
PLUGIN_BASE => [ 'MyOrg::Template::Plugin',
'YourOrg::Template::Plugin' ],
});</pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_LOAD_PERL" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">LOAD_PERL</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <a href="../../manual/Config.html#section_LOAD_PERL">LOAD_PERL</a> option can be set to allow you to
load regular Perl modules (i.e. those that don't reside in the
<code>Template::Plugin</code> or another user-defined namespace) as
plugins.
</p>
<p>
If a plugin cannot be loaded using the <a href="../../manual/Config.html#section_PLUGINS">PLUGINS</a> or
<a href="../../manual/Config.html#section_PLUGIN_BASE">PLUGIN_BASE</a> approaches then, if the <a
href="../../manual/Config.html#section_LOAD_PERL">LOAD_PERL</a> is set, the provider will make a
final attempt to load the module without prepending any prefix to the
module path.
</p>
<p>
Unlike regular plugins, modules loaded using <a href="../../manual/Config.html#section_LOAD_PERL">LOAD_PERL</a> do not receive a <a href="../../modules/Template/Context.html">Template::Context</a> reference as
the first argument to the <code>new()</code> constructor method.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_TOLERANT" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">TOLERANT</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <a href="../../manual/Config.html#section_TOLERANT">TOLERANT</a> flag can be set to indicate that the
<code>Template::Plugins</code> module should ignore any errors
encountered while loading a plugin and instead return
<code>STATUS_DECLINED</code>.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="section_DEBUG" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">DEBUG</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <a href="../../manual/Config.html#section_DEBUG">DEBUG</a> option can be used to enable debugging
messages for the <code>Template::Plugins</code> module by setting it to
include the <code>DEBUG_PLUGINS</code> value.
</p>
<pre>use Template::Constants qw( :debug );
my $template = Template->new({
DEBUG => DEBUG_FILTERS | DEBUG_PLUGINS,
});</pre>
</div>
</div>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="TEMPLATE_TOOLKIT_PLUGINS" onclick="switch_section(this)" title="Click title to show/hide section content.">TEMPLATE TOOLKIT PLUGINS</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Please see <a href="../../manual/Plugins.html">Template::Manual::Plugins</a> For a complete list of all the plugin
modules distributed with the Template Toolkit.
</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="../../manual/Plugins.html">Template::Manual::Plugins</a>, <a href="../../modules/Template/Plugin.html">Template::Plugin</a>, <a href="../../modules/Template/Context.html">Template::Context</a>, <a href="../../modules/Template.html">Template</a>.
</p>
</div>
</div>
</div></div>
<br class="clear" />
<div class="pageinfo">
<a href="http://template-toolkit.org/docs/modules/Template/Plugins.html">http://template-toolkit.org/docs/modules/Template/Plugins.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/Plugin/index.html" title="Template::Plugin::* Modules" class="go back">Back<span class="about"><h4>Template::Plugin::* Modules</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/Provider.html" title="Template::Provider" class="go next">Next<span class="about"><h4>Template::Provider</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>