[Templates-cvs] cvs commit: Template2/docsrc/lib/dir use
cvs@template-toolkit.org
cvs@template-toolkit.org
cvs 06/01/30 10:32:14
Modified: docsrc/lib/dir use
Log:
* updated docs to better describe how plugins get locked and loaded
Revision Changes Path
1.3 +57 -24 Template2/docsrc/lib/dir/use
Index: use
===================================================================
RCS file: /template-toolkit/Template2/docsrc/lib/dir/use,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- use 2006/01/30 09:56:25 1.2
+++ use 2006/01/30 10:32:14 1.3
@@ -11,24 +11,64 @@
automatically by the Template Toolkit. For details of this interface
and information on writing plugins, consult L<Template::Plugin>.
-The plugin name is case-sensitive and will be appended to the
-PLUGIN_BASE value (default: 'Template::Plugin') to construct a full
-module name. Any periods, '.', in the name will be converted to '::'.
+A number of standard plugins are included with the Template Toolkit
+(see below and L<Template::Manual::Plugins>). The names of these
+standard plugins are case insensitive.
+ [% USE CGI %] # => Template::Plugin::CGI
+ [% USE Cgi %] # => Template::Plugin::CGI
+ [% USE cgi %] # => Template::Plugin::CGI
+
+You can also define further plugins using the PLUGINS option.
+
+ my $tt = Template->new({
+ PLUGINS => {
+ foo => 'My::Plugin::Foo',
+ bar => 'My::Plugin::Bar',
+ },
+ });
+
+The recommended convention is to specify these plugin names in lower
+case. The Template Toolkit first looks for an exact case-sensitive
+match and then tries the lower case conversion of the name specified.
+
+ [% USE Foo %] # look for 'Foo' then 'foo'
+
+If you define all your PLUGINS with lower case names then they will be
+located regardless of how the user specifies the name in the USE
+directive. If, on the other hand, you define your PLUGINS with upper
+or mixed case names then the name specified in the USE directive must
+match the case exactly.
+
+If the plugin isn't defined in either the standard plugins
+($Template::Plugins::STD_PLUGINS) or via the PLUGINS option, then
+the PLUGIN_BASE is searched.
+
+In this case the plugin name I<is> case-sensitive. It is appended to
+each of the PLUGIN_BASE module namespaces in turn (default:
+'Template::Plugin') to construct a full module name which it attempts
+to locate and load. Any periods, '.', in the name will be converted
+to '::'.
+
[% USE MyPlugin %] # => Template::Plugin::MyPlugin
[% USE Foo.Bar %] # => Template::Plugin::Foo::Bar
-Various standard plugins are included with the Template Toolkit (see
-below and L<Template::Manual::Plugins>). The names of these standard
-plugins are case insensitive.
+The LOAD_PERL option (disabled by default) provides a further way by
+which external Perl modules may be loaded. If a regular Perl module
+(i.e. not a Template::Plugin::* or other module relative to some
+PLUGIN_BASE) supports an object-oriented interface and a new()
+constructor then it can be loaded and instantiated automatically. The
+following trivial example shows how the IO::File module might be used.
- [% USE CGI %] # => Template::Plugin::CGI
- [% USE Cgi %] # => Template::Plugin::CGI
- [% USE cgi %] # => Template::Plugin::CGI
+ [% USE file = IO.File('/tmp/mydata') %]
+ [% WHILE (line = file.getline) %]
+ <!-- [% line %] -->
+ [% END %]
+
Any additional parameters supplied in parenthesis after the plugin
name will be also be passed to the new() constructor. A reference to
-the current Template::Context object is always passed as the first
+the current Template::Context object is passed as the first
parameter.
[% USE MyPlugin('foo', 123) %]
@@ -37,6 +77,13 @@
Template::Plugin::MyPlugin->new($context, 'foo', 123);
+The only exception to this is when a module is loaded via the
+LOAD_PERL option. In this case the $context reference is I<not>
+passed to the new() constructor. This is based on the assumption that
+the module is a regular Perl module rather than a Template Toolkit
+plugin so isn't expecting a context reference and wouldn't know what
+to do with it anyway.
+
Named parameters may also be specified. These are collated into a
hash which is passed by reference as the last parameter to the
constructor, as per the general code calling interface.
@@ -130,19 +177,5 @@
See L<Template::Manual::Plugins> for more information on the plugins
distributed with the toolkit or available from CPAN.
-
-The LOAD_PERL option (disabled by default) provides a further way by
-which external Perl modules may be loaded. If a regular Perl module
-(i.e. not a Template::Plugin::* or other module relative to some
-PLUGIN_BASE) supports an object-oriented interface and a new()
-constructor then it can be loaded and instantiated automatically. The
-following trivial example shows how the IO::File module might be used.
-
- [% USE file = IO.File('/tmp/mydata') %]
-
- [% WHILE (line = file.getline) %]
- <!-- [% line %] -->
- [% END %]
-