1Template::Plugin::TableU(s3e)r Contributed Perl DocumentaTteimopnlate::Plugin::Table(3)
2
6 Template::Plugin::Table - Plugin to present data in a table
7
9 [% USE table(list, rows=n, cols=n, overlap=n, pad=0) %]
10 [% FOREACH item = table.row(n) %]
12 [% item %]
13 [% END %]
14 [% FOREACH item = table.col(n) %]
16 [% item %]
17 [% END %]
18 [% FOREACH row = table.rows %]
20 [% FOREACH item = row %]
21 [% item %]
22 [% END %]
23 [% END %]
24 [% FOREACH col = table.cols %]
26 [% col.first %] - [% col.last %] ([% col.size %] entries)
27 [% END %]
28
30 The Table plugin allows you to format a list of data items into a vir‐
31 tual table. When you create a Table plugin via the USE directive, sim‐
32 ply pass a list reference as the first parameter and then specify a
33 fixed number of rows or columns.
34 [% USE Table(list, rows=5) %]
36 [% USE table(list, cols=5) %]
37 The 'Table' plugin name can also be specified in lower case as shown in
39 the second example above. You can also specify an alternative variable
40 name for the plugin as per regular Template Toolkit syntax.
41 [% USE mydata = table(list, rows=5) %]
43 The plugin then presents a table based view on the data set. The data
45 isn't actually reorganised in any way but is available via the row(),
46 col(), rows() and cols() as if formatted into a simple two dimensional
47 table of n rows x n columns. Thus, if our sample 'alphabet' list con‐
48 tained the letters 'a' to 'z', the above USE directives would create
49 plugins that represented the following views of the alphabet.
50 [% USE table(alphabet, ... %]
52 rows=5 cols=5
54 a f k p u z a g m s y
55 b g l q v b h n t z
56 c h m r w c i o u
57 d i n s x d j p v
58 e j o t y e k q w
59 f l r x
60 We can request a particular row or column using the row() and col()
62 methods.
63 [% USE table(alphabet, rows=5) %]
65 [% FOREACH item = table.row(0) %]
66 # [% item %] set to each of [ a f k p u z ] in turn
67 [% END %]
68 [% FOREACH item = table.col(2) %]
70 # [% item %] set to each of [ m n o p q r ] in turn
71 [% END %]
72 Data in rows is returned from left to right, columns from top to bot‐
74 tom. The first row/column is 0. By default, rows or columns that con‐
75 tain empty values will be padded with the undefined value to fill it to
76 the same size as all other rows or columns. For example, the last row
77 (row 4) in the first example would contain the values [ e j o t y undef
78 ]. The Template Toolkit will safely accept these undefined values and
79 print a empty string. You can also use the IF directive to test if the
80 value is set.
81 [% FOREACH item = table.row(4) %]
83 [% IF item %]
84 Item: [% item %]
85 [% END %]
86 [% END %]
87 You can explicitly disable the 'pad' option when creating the plugin to
89 returned shortened rows/columns where the data is empty.
90 [% USE table(alphabet, cols=5, pad=0) %]
92 [% FOREACH item = table.col(4) %]
93 # [% item %] set to each of 'y z'
94 [% END %]
95 The rows() method returns all rows/columns in the table as a reference
97 to a list of rows (themselves list references). The row() methods when
98 called without any arguments calls rows() to return all rows in the ta‐
99 ble.
100 Ditto for cols() and col().
102 [% USE table(alphabet, cols=5) %]
104 [% FOREACH row = table.rows %]
105 [% FOREACH item = row %]
106 [% item %]
107 [% END %]
108 [% END %]
109 The Template Toolkit provides the first(), last() and size() methods
111 that can be called on list references to return the first/last entry or
112 the number of entried. The following example shows how we might use
113 this to provide an alphabetical index split into 3 even parts.
114 [% USE table(alphabet, cols=3, pad=0) %]
116 [% FOREACH group = table.col %]
117 [ [% group.first %] - [% group.last %] ([% group.size %] letters) ]
118 [% END %]
119 This produces the following output:
121 [ a - i (9 letters) ]
123 [ j - r (9 letters) ]
124 [ s - z (8 letters) ]
125 We can also use the general purpose join() list method which joins the
127 items of the list using the connecting string specified.
128 [% USE table(alphabet, cols=5) %]
130 [% FOREACH row = table.rows %]
131 [% row.join(' - ') %]
132 [% END %]
133 Data in the table is ordered downwards rather than across but can eas‐
135 ily be transformed on output. For example, to format our data in 5
136 columns with data ordered across rather than down, we specify 'rows=5'
137 to order the data as such:
138 a f . .
140 b g .
141 c h
142 d i
143 e j
144 and then iterate down through each column (a-e, f-j, etc.) printing the
146 data across.
147 a b c d e
149 f g h i j
150 . .
151 .
152 Example code to do so would be much like the following:
154 [% USE table(alphabet, rows=3) %]
156 [% FOREACH cols = table.cols %]
157 [% FOREACH item = cols %]
158 [% item %]
159 [% END %]
160 [% END %]
161 a b c
163 d e f
164 g h i
165 j . .
166 .
167 In addition to a list reference, the Table plugin constructor may be
169 passed a reference to a Template::Iterator object or subclass thereof.
170 The get_all() method is first called on the iterator to return all
171 remaining items. These are then available via the usual Table inter‐
172 face.
173 [% USE DBI(dsn,user,pass) -%]
175 # query() returns an iterator
177 [% results = DBI.query('SELECT * FROM alphabet ORDER BY letter') %]
178 # pass into Table plugin
180 [% USE table(results, rows=8 overlap=1 pad=0) -%]
181 [% FOREACH row = table.cols -%]
183 [% row.first.letter %] - [% row.last.letter %]:
184 [% row.join(', ') %]
185 [% END %]
186
188 Andy Wardley <abw@wardley.org>
189 <http://wardley.org/⎪http://wardley.org/>
191
193 2.71, distributed as part of the Template Toolkit version 2.18,
194 released on 09 February 2007.
195
197 Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
198 This module is free software; you can redistribute it and/or modify it
200 under the same terms as Perl itself.
201
203 Template::Plugin
204perl v5.8.8 2007-02-09 Template::Plugin::Table(3)