Template::Plugin::Table(3pm)

1Template::Plugin::TableU(s3e)r Contributed Perl DocumentaTteimopnlate::Plugin::Table(3)
2
3
4

NAME

6       Template::Plugin::Table - Plugin to present data in a table
7

SYNOPSIS

9           [% USE table(list, rows=n, cols=n, overlap=n, pad=0) %]
10
11           [% FOREACH item IN table.row(n) %]
12              [% item %]
13           [% END %]
14
15           [% FOREACH item IN table.col(n) %]
16              [% item %]
17           [% END %]
18
19           [% FOREACH row IN table.rows %]
20              [% FOREACH item IN row %]
21                 [% item %]
22              [% END %]
23           [% END %]
24
25           [% FOREACH col IN table.cols %]
26              [% col.first %] - [% col.last %] ([% col.size %] entries)
27           [% END %]
28

DESCRIPTION

30       The "Table" plugin allows you to format a list of data items into a
31       virtual table.  When you create a "Table" plugin via the "USE"
32       directive, simply pass a list reference as the first parameter and then
33       specify a fixed number of rows or columns.
34
35           [% USE Table(list, rows=5) %]
36           [% USE table(list, cols=5) %]
37
38       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
42           [% USE mydata = table(list, rows=5) %]
43
44       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
47       dimensional table of "n" rows x "n" columns.
48
49       So if we had a sample "alphabet" list contained the letters '"a"' to
50       '"z"', the above "USE" directives would create plugins that represented
51       the following views of the alphabet.
52
53           [% USE table(alphabet, ... %]
54
55           rows=5                  cols=5
56           a  f  k  p  u  z        a  g  m  s  y
57           b  g  l  q  v           b  h  n  t  z
58           c  h  m  r  w           c  i  o  u
59           d  i  n  s  x           d  j  p  v
60           e  j  o  t  y           e  k  q  w
61                                   f  l  r  x
62
63       We can request a particular row or column using the "row()" and "col()"
64       methods.
65
66           [% USE table(alphabet, rows=5) %]
67           [% FOREACH item = table.row(0) %]
68              # [% item %] set to each of [ a f k p u z ] in turn
69           [% END %]
70
71           [% FOREACH item = table.col(2) %]
72              # [% item %] set to each of [ m n o p q r ] in turn
73           [% END %]
74
75       Data in rows is returned from left to right, columns from top to
76       bottom.  The first row/column is 0.  By default, rows or columns that
77       contain empty values will be padded with the undefined value to fill it
78       to the same size as all other rows or columns.
79
80       For example, the last row (row 4) in the first example would contain
81       the values "[ e j o t y undef ]". The Template Toolkit will safely
82       accept these undefined values and print a empty string. You can also
83       use the IF directive to test if the value is set.
84
85          [% FOREACH item = table.row(4) %]
86             [% IF item %]
87                Item: [% item %]
88             [% END %]
89          [% END %]
90
91       You can explicitly disable the "pad" option when creating the plugin to
92       returned shortened rows/columns where the data is empty.
93
94          [% USE table(alphabet, cols=5, pad=0) %]
95          [% FOREACH item = table.col(4) %]
96             # [% item %] set to each of 'y z'
97          [% END %]
98
99       The "rows()" method returns all rows/columns in the table as a
100       reference to a list of rows (themselves list references).  The "row()"
101       methods when called without any arguments calls "rows()" to return all
102       rows in the table.
103
104       Ditto for "cols()" and "col()".
105
106           [% USE table(alphabet, cols=5) %]
107           [% FOREACH row = table.rows %]
108              [% FOREACH item = row %]
109                 [% item %]
110              [% END %]
111           [% END %]
112
113       The Template Toolkit provides the "first", "last" and "size" virtual
114       methods that can be called on list references to return the first/last
115       entry or the number of entries in a list. The following example shows
116       how we might use this to provide an alphabetical index split into 3
117       even parts.
118
119           [% USE table(alphabet, cols=3, pad=0) %]
120           [% FOREACH group = table.col %]
121              [ [% group.first %] - [% group.last %] ([% group.size %] letters) ]
122           [% END %]
123
124       This produces the following output:
125
126           [ a - i (9 letters) ]
127           [ j - r (9 letters) ]
128           [ s - z (8 letters) ]
129
130       We can also use the general purpose "join" virtual method which joins
131       the items of the list using the connecting string specified.
132
133           [% USE table(alphabet, cols=5) %]
134           [% FOREACH row = table.rows %]
135              [% row.join(' - ') %]
136           [% END %]
137
138       Data in the table is ordered downwards rather than across but can
139       easily be transformed on output.  For example, to format our data in 5
140       columns with data ordered across rather than down, we specify "rows=5"
141       to order the data as such:
142
143           a  f  .  .
144           b  g  .
145           c  h
146           d  i
147           e  j
148
149       and then iterate down through each column (a-e, f-j, etc.) printing the
150       data across.
151
152           a  b  c  d  e
153           f  g  h  i  j
154           .  .
155           .
156
157       Example code to do so would be much like the following:
158
159           [% USE table(alphabet, rows=3) %]
160           [% FOREACH cols = table.cols %]
161             [% FOREACH item = cols %]
162               [% item %]
163             [% END %]
164           [% END %]
165
166       Output:
167
168           a  b  c
169           d  e  f
170           g  h  i
171           j  .  .
172           .
173
174       In addition to a list reference, the "Table" plugin constructor may be
175       passed a reference to a Template::Iterator object or subclass thereof.
176       The Template::Iterator get_all() method is first called on the iterator
177       to return all remaining items. These are then available via the usual
178       Table interface.
179
180           [% USE DBI(dsn,user,pass) -%]
181
182           # query() returns an iterator
183           [% results = DBI.query('SELECT * FROM alphabet ORDER BY letter') %]
184
185           # pass into Table plugin
186           [% USE table(results, rows=8 overlap=1 pad=0) -%]
187
188           [% FOREACH row = table.cols -%]
189              [% row.first.letter %] - [% row.last.letter %]:
190                 [% row.join(', ') %]
191           [% END %]
192

AUTHOR

194       Andy Wardley <abw@wardley.org> <http://wardley.org/>
195

COPYRIGHT

197       Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
198
199       This module is free software; you can redistribute it and/or modify it
200       under the same terms as Perl itself.
201

NAME

SYNOPSIS

DESCRIPTION

AUTHOR

COPYRIGHT

SEE ALSO