diff options
Diffstat (limited to 'lib/Template/Manual/Plugins.pod')
| -rw-r--r-- | lib/Template/Manual/Plugins.pod | 552 |
1 files changed, 0 insertions, 552 deletions
diff --git a/lib/Template/Manual/Plugins.pod b/lib/Template/Manual/Plugins.pod deleted file mode 100644 index 7955640..0000000 --- a/lib/Template/Manual/Plugins.pod +++ /dev/null @@ -1,552 +0,0 @@ -#============================================================= -*-perl-*- -# -# Template::Manual::Plugins -# -# DESCRIPTION -# This section lists the standard plugins which can be used to extend -# the runtime functionality of the Template Toolkit. The plugins are -# distributed with the Template Toolkit but may required additional -# modules from CPAN. -# -# AUTHOR -# Andy Wardley <abw@andywardley.com> -# -# COPYRIGHT -# Copyright (C) 1996-2001 Andy Wardley. All Rights Reserved. -# Copyright (C) 1998-2001 Canon Research Centre Europe Ltd. -# -# This module is free software; you can redistribute it and/or -# modify it under the same terms as Perl itself. -# -# REVISION -# -# -#======================================================================== - - -#------------------------------------------------------------------------ -# IMPORTANT NOTE -# This documentation is generated automatically from source -# templates. Any changes you make here may be lost. -# -# The 'docsrc' documentation source bundle is available for download -# from http://www.template-toolkit.org/docs.html and contains all -# the source templates, XML files, scripts, etc., from which the -# documentation for the Template Toolkit is built. -#------------------------------------------------------------------------ - -=head1 NAME - -Template::Manual::Plugins - Standard plugins - -=head1 DESCRIPTION - -This section lists the standard plugins which can be used to extend the -runtime functionality of the Template Toolkit. The plugins are -distributed with the Template Toolkit but may required additional -modules from CPAN. - - - -=head1 TEMPLATE TOOLKIT PLUGINS - -The following plugin modules are distributed with the Template -Toolkit. Some of the plugins interface to external modules (detailed -below) which should be downloaded from any CPAN site and installed -before using the plugin. - -=head2 Autoformat - -The Autoformat plugin is an interface to Damian Conway's Text::Autoformat -Perl module which provides advanced text wrapping and formatting. See -L<Template::Plugin::Autoformat> and L<Text::Autoformat> for further -details. - - [% USE autoformat(left=10, right=20) %] - [% autoformat(mytext) %] # call autoformat sub - [% mytext FILTER autoformat %] # or use autoformat filter - -The Text::Autoformat module is available from CPAN: - - http://www.cpan.org/modules/by-module/Text/ - -=head2 CGI - -The CGI plugin is a wrapper around Lincoln Stein's -E<lt>lstein@genome.wi.mit.eduE<gt> CGI.pm module. The plugin is -distributed with the Template Toolkit (see L<Template::Plugin::CGI>) -and the CGI module itself is distributed with recent versions Perl, -or is available from CPAN. - - [% USE CGI %] - [% CGI.param('param_name') %] - [% CGI.start_form %] - [% CGI.popup_menu( Name => 'color', - Values => [ 'Green', 'Brown' ] ) %] - [% CGI.end_form %] - -=head2 Datafile - -Provides an interface to data stored in a plain text file in a simple -delimited format. The first line in the file specifies field names -which should be delimiter by any non-word character sequence. -Subsequent lines define data using the same delimiter as int he first -line. Blank lines and comments (lines starting '#') are ignored. See -L<Template::Plugin::Datafile> for further details. - -/tmp/mydata: - - # define names for each field - id : email : name : tel - # here's the data - fred : fred@here.com : Fred Smith : 555-1234 - bill : bill@here.com : Bill White : 555-5678 - -example: - - [% USE userlist = datafile('/tmp/mydata') %] - - [% FOREACH user = userlist %] - [% user.name %] ([% user.id %]) - [% END %] - -=head2 Date - -The Date plugin provides an easy way to generate formatted time and date -strings by delegating to the POSIX strftime() routine. See -L<Template::Plugin::Date> and L<POSIX> for further details. - - [% USE date %] - [% date.format %] # current time/date - - File last modified: [% date.format(template.modtime) %] - -=head2 Directory - -The Directory plugin provides a simple interface to a directory and -the files within it. See L<Template::Plugin::Directory> for further -details. - - [% USE dir = Directory('/tmp') %] - [% FOREACH file = dir.files %] - # all the plain files in the directory - [% END %] - [% FOREACH file = dir.dirs %] - # all the sub-directories - [% END %] - -=head2 DBI - -The DBI plugin, developed by Simon Matthews -E<lt>sam@knowledgepool.comE<gt>, brings the full power of Tim Bunce's -E<lt>Tim.Bunce@ig.co.ukE<gt> database interface module (DBI) to your -templates. See L<Template::Plugin::DBI> and L<DBI> for further details. - - [% USE DBI('dbi:driver:database', 'user', 'pass') %] - - [% FOREACH user = DBI.query( 'SELECT * FROM users' ) %] - [% user.id %] [% user.name %] - [% END %] - -The DBI and relevant DBD modules are available from CPAN: - - http://www.cpan.org/modules/by-module/DBI/ - -=head2 Dumper - -The Dumper plugin provides an interface to the Data::Dumper module. See -L<Template::Plugin::Dumper> and L<Data::Dumper> for futher details. - - [% USE dumper(indent=0, pad="<br>") %] - [% dumper.dump(myvar, yourvar) %] - -=head2 File - -The File plugin provides a general abstraction for files and can be -used to fetch information about specific files within a filesystem. -See L<Template::Plugin::File> for further details. - - [% USE File('/tmp/foo.html') %] - [% File.name %] # foo.html - [% File.dir %] # /tmp - [% File.mtime %] # modification time - -=head2 Filter - -This module implements a base class plugin which can be subclassed -to easily create your own modules that define and install new filters. - - package MyOrg::Template::Plugin::MyFilter; - - use Template::Plugin::Filter; - use base qw( Template::Plugin::Filter ); - - sub filter { - my ($self, $text) = @_; - - # ...mungify $text... - - return $text; - } - - # now load it... - [% USE MyFilter %] - - # ...and use the returned object as a filter - [% FILTER $MyFilter %] - ... - [% END %] - -See L<Template::Plugin::Filter> for further details. - -=head2 Format - -The Format plugin provides a simple way to format text according to a -printf()-like format. See L<Template::Plugin::Format> for further -details. - - [% USE bold = format('<b>%s</b>') %] - [% bold('Hello') %] - -=head2 GD::Image, GD::Polygon, GD::Constants - -These plugins provide access to the GD graphics library via Lincoln -D. Stein's GD.pm interface. These plugins allow PNG, JPEG and other -graphical formats to be generated. - - [% FILTER null; - USE im = GD.Image(100,100); - # allocate some colors - black = im.colorAllocate(0, 0, 0); - red = im.colorAllocate(255,0, 0); - blue = im.colorAllocate(0, 0, 255); - # Draw a blue oval - im.arc(50,50,95,75,0,360,blue); - # And fill it with red - im.fill(50,50,red); - # Output image in PNG format - im.png | stdout(1); - END; - -%] - -See L<Template::Plugin::GD::Image> for further details. - -=head2 GD::Text, GD::Text::Align, GD::Text::Wrap - -These plugins provide access to Martien Verbruggen's GD::Text, -GD::Text::Align and GD::Text::Wrap modules. These plugins allow the -layout, alignment and wrapping of text when drawing text in GD images. - - [% FILTER null; - USE gd = GD.Image(200,400); - USE gdc = GD.Constants; - black = gd.colorAllocate(0, 0, 0); - green = gd.colorAllocate(0, 255, 0); - txt = "This is some long text. " | repeat(10); - USE wrapbox = GD.Text.Wrap(gd, - line_space => 4, - color => green, - text => txt, - ); - wrapbox.set_font(gdc.gdMediumBoldFont); - wrapbox.set(align => 'center', width => 160); - wrapbox.draw(20, 20); - gd.png | stdout(1); - END; - -%] - -See L<Template::Plugin::GD::Text>, L<Template::Plugin::GD::Text::Align> -and L<Template::Plugin::GD::Text::Wrap> for further details. - -=head2 GD::Graph::lines, GD::Graph::bars, GD::Graph::points, GD::Graph::linespoin -ts, GD::Graph::area, GD::Graph::mixed, GD::Graph::pie - -These plugins provide access to Martien Verbruggen's GD::Graph module -that allows graphs, plots and charts to be created. These plugins allow -graphs, plots and charts to be generated in PNG, JPEG and other -graphical formats. - - [% FILTER null; - data = [ - ["1st","2nd","3rd","4th","5th","6th"], - [ 4, 2, 3, 4, 3, 3.5] - ]; - USE my_graph = GD.Graph.pie(250, 200); - my_graph.set( - title => 'A Pie Chart', - label => 'Label', - axislabelclr => 'black', - pie_height => 36, - transparent => 0, - ); - my_graph.plot(data).png | stdout(1); - END; - -%] - -See -L<Template::Plugin::GD::Graph::lines>, -L<Template::Plugin::GD::Graph::bars>, -L<Template::Plugin::GD::Graph::points>, -L<Template::Plugin::GD::Graph::linespoints>, -L<Template::Plugin::GD::Graph::area>, -L<Template::Plugin::GD::Graph::mixed>, -L<Template::Plugin::GD::Graph::pie>, and -L<GD::Graph>, -for more details. - -=head2 GD::Graph::bars3d, GD::Graph::lines3d, GD::Graph::pie3d - -These plugins provide access to Jeremy Wadsack's GD::Graph3d -module. This allows 3D bar charts and 3D lines plots to -be generated. - - [% FILTER null; - data = [ - ["1st","2nd","3rd","4th","5th","6th","7th", "8th", "9th"], - [ 1, 2, 5, 6, 3, 1.5, 1, 3, 4], - ]; - USE my_graph = GD.Graph.bars3d(); - my_graph.set( - x_label => 'X Label', - y_label => 'Y label', - title => 'A 3d Bar Chart', - y_max_value => 8, - y_tick_number => 8, - y_label_skip => 2, - # shadows - bar_spacing => 8, - shadow_depth => 4, - shadowclr => 'dred', - transparent => 0, - my_graph.plot(data).png | stdout(1); - END; - -%] - -See -L<Template::Plugin::GD::Graph::lines3d>, -L<Template::Plugin::GD::Graph::bars3d>, and -L<Template::Plugin::GD::Graph::pie3d> -for more details. - -=head2 HTML - -The HTML plugin is very new and very basic, implementing a few useful -methods for generating HTML. It is likely to be extended in the future -or integrated with a larger project to generate HTML elements in a generic -way (as discussed recently on the mod_perl mailing list). - - [% USE HTML %] - [% HTML.escape("if (a < b && c > d) ..." %] - [% HTML.attributes(border => 1, cellpadding => 2) %] - [% HTML.element(table => { border => 1, cellpadding => 2 }) %] - -See L<Template::Plugin::HTML> for further details. - -=head2 Iterator - -The Iterator plugin provides a way to create a Template::Iterator -object to iterate over a data set. An iterator is created -automatically by the FOREACH directive and is aliased to the 'loop' -variable. This plugin allows an iterator to be explicitly created -with a given name, or the default plugin name, 'iterator'. See -L<Template::Plugin::Iterator> for further details. - - [% USE iterator(list, args) %] - - [% FOREACH item = iterator %] - [% '<ul>' IF iterator.first %] - <li>[% item %] - [% '</ul>' IF iterator.last %] - [% END %] - -=head2 Pod - -This plugin provides an interface to the L<Pod::POM|Pod::POM> module -which parses POD documents into an internal object model which can -then be traversed and presented through the Template Toolkit. - - [% USE Pod(podfile) %] - - [% FOREACH head1 = Pod.head1; - FOREACH head2 = head1/head2; - ... - END; - END - %] - -=head2 String - -The String plugin implements an object-oriented interface for -manipulating strings. See L<Template::Plugin::String> for further -details. - - [% USE String 'Hello' %] - [% String.append(' World') %] - - [% msg = String.new('Another string') %] - [% msg.replace('string', 'text') %] - - The string "[% msg %]" is [% msg.length %] characters long. - -=head2 Table - -The Table plugin allows you to format a list of data items into a -virtual table by specifying a fixed number of rows or columns, with -an optional overlap. See L<Template::Plugin::Table> for further -details. - - [% USE table(list, rows=10, overlap=1) %] - - [% FOREACH item = table.col(3) %] - [% item %] - [% END %] - -=head2 URL - -The URL plugin provides a simple way of contructing URLs from a base -part and a variable set of parameters. See L<Template::Plugin::URL> -for further details. - - [% USE mycgi = url('/cgi-bin/bar.pl', debug=1) %] - - [% mycgi %] - # ==> /cgi/bin/bar.pl?debug=1 - - [% mycgi(mode='submit') %] - # ==> /cgi/bin/bar.pl?mode=submit&debug=1 - -=head2 Wrap - -The Wrap plugin uses the Text::Wrap module by David Muir Sharnoff -E<lt>muir@idiom.comE<gt> (with help from Tim Pierce and many many others) -to provide simple paragraph formatting. See L<Template::Plugin::Wrap> -and L<Text::Wrap> for further details. - - [% USE wrap %] - [% wrap(mytext, 40, '* ', ' ') %] # use wrap sub - [% mytext FILTER wrap(40) -%] # or wrap FILTER - -The Text::Wrap module is available from CPAN: - - http://www.cpan.org/modules/by-module/Text/ - -=head2 XML::DOM - -The XML::DOM plugin gives access to the XML Document Object Module via -Clark Cooper E<lt>cooper@sch.ge.comE<gt> and Enno Derksen's -E<lt>enno@att.comE<gt> XML::DOM module. See L<Template::Plugin::XML::DOM> -and L<XML::DOM> for further details. - - [% USE dom = XML.DOM %] - [% doc = dom.parse(filename) %] - - [% FOREACH node = doc.getElementsByTagName('CODEBASE') %] - * [% node.getAttribute('href') %] - [% END %] - -The plugin requires the XML::DOM module, available from CPAN: - - http://www.cpan.org/modules/by-module/XML/ - -=head2 XML::RSS - -The XML::RSS plugin is a simple interface to Jonathan Eisenzopf's -E<lt>eisen@pobox.comE<gt> XML::RSS module. A RSS (Rich Site Summary) -file is typically used to store short news 'headlines' describing -different links within a site. This plugin allows you to parse RSS -files and format the contents accordingly using templates. -See L<Template::Plugin::XML::RSS> and L<XML::RSS> for further details. - - [% USE news = XML.RSS(filename) %] - - [% FOREACH item = news.items %] - <a href="[% item.link %]">[% item.title %]</a> - [% END %] - -The XML::RSS module is available from CPAN: - - http://www.cpan.org/modules/by-module/XML/ - -=head2 XML::Simple - -This plugin implements an interface to the L<XML::Simple|XML::Simple> -module. - - [% USE xml = XML.Simple(xml_file_or_text) %] - - [% xml.head.title %] - -See L<Template::Plugin::XML::Simple> for further details. - -=head2 XML::Style - -This plugin defines a filter for performing simple stylesheet based -transformations of XML text. - - [% USE xmlstyle - table = { - attributes = { - border = 0 - cellpadding = 4 - cellspacing = 1 - } - } - %] - - [% FILTER xmlstyle %] - <table> - <tr> - <td>Foo</td> <td>Bar</td> <td>Baz</td> - </tr> - </table> - [% END %] - -See L<Template::Plugin::XML::Style> for further details. - -=head2 XML::XPath - -The XML::XPath plugin provides an interface to Matt Sergeant's -E<lt>matt@sergeant.orgE<gt> XML::XPath module. See -L<Template::Plugin::XML::XPath> and L<XML::XPath> for further details. - - [% USE xpath = XML.XPath(xmlfile) %] - [% FOREACH page = xpath.findnodes('/html/body/page') %] - [% page.getAttribute('title') %] - [% END %] - -The plugin requires the XML::XPath module, available from CPAN: - - http://www.cpan.org/modules/by-module/XML/ - -=head1 AUTHOR - -Andy Wardley E<lt>abw@andywardley.comE<gt> - -L<http://www.andywardley.com/|http://www.andywardley.com/> - - - - -=head1 VERSION - -Template Toolkit version 2.13, released on 30 January 2004. - -=head1 COPYRIGHT - - Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved. - Copyright (C) 1998-2002 Canon Research Centre Europe Ltd. - -This module is free software; you can redistribute it and/or -modify it under the same terms as Perl itself. - - - -=cut - -# Local Variables: -# mode: perl -# perl-indent-level: 4 -# indent-tabs-mode: nil -# End: -# -# vim: expandtab shiftwidth=4: |