Commit | Line | Data |
3fea05b9 |
1 | #============================================================= -*-perl-*- |
2 | # |
3 | # Template::Manual::Plugins |
4 | # |
5 | # AUTHOR |
6 | # Andy Wardley <abw@wardley.org> |
7 | # |
8 | # COPYRIGHT |
9 | # Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. |
10 | # |
11 | # This module is free software; you can redistribute it and/or |
12 | # modify it under the same terms as Perl itself. |
13 | # |
14 | #======================================================================== |
15 | |
16 | =head1 NAME |
17 | |
18 | Template::Manual::Plugins - Standard plugins |
19 | |
20 | =head1 TEMPLATE TOOLKIT PLUGINS |
21 | |
22 | The following plugin modules are distributed with the Template |
23 | Toolkit. Some of the plugins interface to external modules (detailed |
24 | below) which should be downloaded from any CPAN site and installed |
25 | before using the plugin. |
26 | |
27 | =head2 Assert |
28 | |
29 | New in 2.20! The L<Assert|Template::Plugin::Assert> plugin adds an |
30 | C<assert> virtual method that you can use to catch undefined values. |
31 | |
32 | For example, consider this dotop: |
33 | |
34 | [% user.name %] |
35 | |
36 | If C<user.name> is an undefined value then TT will silently ignore the |
37 | fact and print nothing. If you C<USE> the C<assert> plugin then you |
38 | can add the C<assert> vmethod between the C<user> and C<name> elements, |
39 | like so: |
40 | |
41 | [% user.assert.name %] |
42 | |
43 | Now, if C<user.name> is an undefined value, an exception will be thrown: |
44 | |
45 | assert error - undefined value for name |
46 | |
47 | =head2 Autoformat |
48 | |
49 | The L<Autoformat|Template::Plugin::Autoformat> plugin is an interface to |
50 | Damian Conway's L<Text::Autoformat> Perl module which provides advanced text |
51 | wrapping and formatting. See L<Template::Plugin::Autoformat> and |
52 | L<Text::Autoformat> for further details. |
53 | |
54 | [% USE autoformat(left=10, right=20) %] |
55 | [% autoformat(mytext) %] # call autoformat sub |
56 | [% mytext FILTER autoformat %] # or use autoformat filter |
57 | |
58 | The L<Text::Autoformat> module is available from CPAN: |
59 | |
60 | L<http://www.cpan.org/modules/by-module/Text/> |
61 | |
62 | =head2 CGI |
63 | |
64 | The L<CGI|Template::Plugin::CGI> plugin is a wrapper around Lincoln Stein's |
65 | CGI.pm module. The plugin is distributed with the Template Toolkit (see |
66 | L<Template::Plugin::CGI>) and the L<CGI> module itself is distributed with |
67 | recent versions Perl, or is available from CPAN. |
68 | |
69 | [% USE CGI %] |
70 | [% CGI.param('param_name') %] |
71 | [% CGI.start_form %] |
72 | [% CGI.popup_menu( Name => 'color', |
73 | Values => [ 'Green', 'Brown' ] ) %] |
74 | [% CGI.end_form %] |
75 | |
76 | =head2 Datafile |
77 | |
78 | Provides an interface to data stored in a plain text file in a simple |
79 | delimited format. The first line in the file specifies field names |
80 | which should be delimiter by any non-word character sequence. |
81 | Subsequent lines define data using the same delimiter as in the first |
82 | line. Blank lines and comments (lines starting '#') are ignored. See |
83 | L<Template::Plugin::Datafile> for further details. |
84 | |
85 | /tmp/mydata: |
86 | |
87 | # define names for each field |
88 | id : email : name : tel |
89 | # here's the data |
90 | fred : fred@here.com : Fred Smith : 555-1234 |
91 | bill : bill@here.com : Bill White : 555-5678 |
92 | |
93 | example: |
94 | |
95 | [% USE userlist = datafile('/tmp/mydata') %] |
96 | |
97 | [% FOREACH user = userlist %] |
98 | [% user.name %] ([% user.id %]) |
99 | [% END %] |
100 | |
101 | =head2 Date |
102 | |
103 | The L<Date|Template::Plugin::Date> plugin provides an easy way to generate |
104 | formatted time and date strings by delegating to the L<POSIX> C<strftime()> |
105 | routine. See L<Template::Plugin::Date> and L<POSIX> for further details. |
106 | |
107 | [% USE date %] |
108 | [% date.format %] # current time/date |
109 | |
110 | File last modified: [% date.format(template.modtime) %] |
111 | |
112 | =head2 Directory |
113 | |
114 | The L<Directory|Template::Plugin::Directory> plugin provides a simple |
115 | interface to a directory and the files within it. See |
116 | L<Template::Plugin::Directory> for further details. |
117 | |
118 | [% USE dir = Directory('/tmp') %] |
119 | [% FOREACH file = dir.files %] |
120 | # all the plain files in the directory |
121 | [% END %] |
122 | [% FOREACH file = dir.dirs %] |
123 | # all the sub-directories |
124 | [% END %] |
125 | |
126 | =head2 DBI |
127 | |
128 | The C<DBI> plugin is no longer distributed as part of the Template Toolkit |
129 | (as of version 2.15). It is now available as a separate L<Template::DBI> |
130 | distribution from CPAN. |
131 | |
132 | =head2 Dumper |
133 | |
134 | The L<Dumper|Template::Plugin::Dumper> plugin provides an interface to the |
135 | Data::Dumper module. See L<Template::Plugin::Dumper> and L<Data::Dumper> for |
136 | futher details. |
137 | |
138 | [% USE dumper(indent=0, pad="<br>") %] |
139 | [% dumper.dump(myvar, yourvar) %] |
140 | |
141 | =head2 File |
142 | |
143 | The L<File|Template::Plugin::File> plugin provides a general abstraction for |
144 | files and can be used to fetch information about specific files within a |
145 | filesystem. See L<Template::Plugin::File> for further details. |
146 | |
147 | [% USE File('/tmp/foo.html') %] |
148 | [% File.name %] # foo.html |
149 | [% File.dir %] # /tmp |
150 | [% File.mtime %] # modification time |
151 | |
152 | =head2 Filter |
153 | |
154 | This module implements a base class plugin which can be subclassed |
155 | to easily create your own modules that define and install new filters. |
156 | |
157 | package MyOrg::Template::Plugin::MyFilter; |
158 | |
159 | use Template::Plugin::Filter; |
160 | use base qw( Template::Plugin::Filter ); |
161 | |
162 | sub filter { |
163 | my ($self, $text) = @_; |
164 | # ...mungify $text... |
165 | return $text; |
166 | } |
167 | |
168 | Example of use: |
169 | |
170 | # now load it... |
171 | [% USE MyFilter %] |
172 | |
173 | # ...and use the returned object as a filter |
174 | [% FILTER $MyFilter %] |
175 | ... |
176 | [% END %] |
177 | |
178 | See L<Template::Plugin::Filter> for further details. |
179 | |
180 | =head2 Format |
181 | |
182 | The L<Format|Template::Plugin::Format> plugin provides a simple way to format |
183 | text according to a C<printf()>-like format. See L<Template::Plugin::Format> for |
184 | further details. |
185 | |
186 | [% USE bold = format('<b>%s</b>') %] |
187 | [% bold('Hello') %] |
188 | |
189 | =head2 GD |
190 | |
191 | The C<GD> plugins are no longer part of the core Template Toolkit distribution. |
192 | They are now available from CPAN in a separate L<Template::GD> distribution. |
193 | |
194 | =head2 HTML |
195 | |
196 | The L<HTML|Template::Plugin::HTML> plugin is very basic, implementing a few |
197 | useful methods for generating HTML. It is likely to be extended in the future |
198 | or integrated with a larger project to generate HTML elements in a generic way. |
199 | |
200 | [% USE HTML %] |
201 | [% HTML.escape("if (a < b && c > d) ..." %] |
202 | [% HTML.attributes(border => 1, cellpadding => 2) %] |
203 | [% HTML.element(table => { border => 1, cellpadding => 2 }) %] |
204 | |
205 | See L<Template::Plugin::HTML> for further details. |
206 | |
207 | =head2 Iterator |
208 | |
209 | The L<Iterator|Template::Plugin::Iterator> plugin provides a way to create a |
210 | L<Template::Iterator> object to iterate over a data set. An iterator is |
211 | created automatically by the C<FOREACH> directive and is aliased to the C<loop> |
212 | variable. This plugin allows an iterator to be explicitly created with a given |
213 | name, or the default plugin name, C<iterator>. See |
214 | L<Template::Plugin::Iterator> for further details. |
215 | |
216 | [% USE iterator(list, args) %] |
217 | |
218 | [% FOREACH item = iterator %] |
219 | [% '<ul>' IF iterator.first %] |
220 | <li>[% item %] |
221 | [% '</ul>' IF iterator.last %] |
222 | [% END %] |
223 | |
224 | =head2 Pod |
225 | |
226 | This plugin provides an interface to the L<Pod::POM|Pod::POM> module |
227 | which parses POD documents into an internal object model which can |
228 | then be traversed and presented through the Template Toolkit. |
229 | |
230 | [% USE Pod(podfile) %] |
231 | |
232 | [% FOREACH head1 = Pod.head1; |
233 | FOREACH head2 = head1/head2; |
234 | ... |
235 | END; |
236 | END |
237 | %] |
238 | |
239 | =head2 Scalar |
240 | |
241 | The Template Toolkit calls user-defined subroutines and object methods |
242 | using Perl's array context by default. |
243 | |
244 | # TT2 calls object methods in array context by default |
245 | [% object.method %] |
246 | |
247 | This plugin module provides a way for you to call subroutines and methods |
248 | in scalar context. |
249 | |
250 | [% USE scalar %] |
251 | |
252 | # force it to use scalar context |
253 | [% object.scalar.method %] |
254 | |
255 | # also works with subroutine references |
256 | [% scalar.my_sub_ref %] |
257 | |
258 | =head2 String |
259 | |
260 | The L<String|Template::Plugin::String> plugin implements an object-oriented |
261 | interface for manipulating strings. See L<Template::Plugin::String> for |
262 | further details. |
263 | |
264 | [% USE String 'Hello' %] |
265 | [% String.append(' World') %] |
266 | |
267 | [% msg = String.new('Another string') %] |
268 | [% msg.replace('string', 'text') %] |
269 | |
270 | The string "[% msg %]" is [% msg.length %] characters long. |
271 | |
272 | =head2 Table |
273 | |
274 | The L<Table|Template::Plugin::Table> plugin allows you to format a list of |
275 | data items into a virtual table by specifying a fixed number of rows or |
276 | columns, with an optional overlap. See L<Template::Plugin::Table> for further |
277 | details. |
278 | |
279 | [% USE table(list, rows=10, overlap=1) %] |
280 | |
281 | [% FOREACH item = table.col(3) %] |
282 | [% item %] |
283 | [% END %] |
284 | |
285 | =head2 URL |
286 | |
287 | The L<URL|Template::Plugin::URL> plugin provides a simple way of contructing |
288 | URLs from a base part and a variable set of parameters. See |
289 | L<Template::Plugin::URL> for further details. |
290 | |
291 | [% USE mycgi = url('/cgi-bin/bar.pl', debug=1) %] |
292 | |
293 | [% mycgi %] |
294 | # ==> /cgi/bin/bar.pl?debug=1 |
295 | |
296 | [% mycgi(mode='submit') %] |
297 | # ==> /cgi/bin/bar.pl?mode=submit&debug=1 |
298 | |
299 | =head2 Wrap |
300 | |
301 | The L<Wrap|Template::Plugin::Wrap> plugin uses the L<Text::Wrap> module to |
302 | provide simple paragraph formatting. See L<Template::Plugin::Wrap> and |
303 | L<Text::Wrap> for further details. |
304 | |
305 | [% USE wrap %] |
306 | [% wrap(mytext, 40, '* ', ' ') %] # use wrap sub |
307 | [% mytext FILTER wrap(40) -%] # or wrap FILTER |
308 | |
309 | The C<Text::Wrap> module is available from CPAN: |
310 | |
311 | http://www.cpan.org/modules/by-module/Text/ |
312 | |
313 | =head2 XML |
314 | |
315 | The C<XML::DOM>, C<XML::RSS>, C<XML::Simple> and C<XML::XPath> plugins are no |
316 | longer distributed with the Template Toolkit as of version 2.15 |
317 | |
318 | They are now available in a separate L<Template::XML> distribution. |
319 | |
320 | =cut |
321 | |
322 | # Local Variables: |
323 | # mode: perl |
324 | # perl-indent-level: 4 |
325 | # indent-tabs-mode: nil |
326 | # End: |
327 | # |
328 | # vim: expandtab shiftwidth=4: |