← Back to branch summary

~ubuntu-branches/ubuntu/quantal/libtemplate-perl/quantal

« back to all changes in this revision

Viewing changes to html/old/modules/Template/Plugin/Table.html

  • Committer: Package Import Robot
  • Author(s): Benjamin Mako Hill
  • Date: 2012-04-08 19:06:29 UTC
  • mfrom: (0.7.1) (0.5.2) (5.1.3 sid)
  • Revision ID: package-import@ubuntu.com-20120408190629-wbcbs2ea39mex6lt
Tags: 2.24-1
http://bugs.debian.org/664561
https://launchpad.net/bugs/688836
* New upstream release (Closes: #664561)
* Bump Standards-Version to 3.9.3
* Changed to the short description to mention the term "Template
  Toolkit". (LP: #688836)

Show diffs side-by-side

added added

removed removed

Lines of Context:
html/old/modules/Template/Plugin/Table.html
 
1
 
 
2
 
 
3
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Strict//EN">
 
4
<html>
 
5
  <head>
 
6
    <title>Template::Plugin::Table</title>
 
7
    <link rel="stylesheet" type="text/css" href="../../../css/blue.css" title="Clear Blue">
 
8
    <link rel="alternate stylesheet" type="text/css" href="../../../css/orange.css" title="Clear Orange">
 
9
    <link rel="alternate stylesheet" type="text/css" href="../../../css/green.css" title="Clear Green">
 
10
    <link rel="alternate stylesheet" type="text/css" href="../../../css/purple.css" title="Clear Purple">
 
11
    <link rel="alternate stylesheet" type="text/css" href="../../../css/grey.css" title="Clear Grey">
 
12
    <!--[if IE 6]>
 
13
    <link rel="stylesheet" type="text/css" href="../../../css/ie6.css" />
 
14
    <![endif]-->
 
15
    <link rel="stylesheet" type="text/css" href="/css/print.css" media="print">
 
16
    <script type="text/javascript" src="../../../js/tt2.js"></script>
 
17
    <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
 
18
    <meta name="author" content="Andy Wardley">
 
19
  </head>
 
20
  <body id="body"> 
 
21
    <div id="layout">
 
22
        <div id="header">
 
23
          <a href="../../../index.html" id="logo" alt="" title="Click for the Home Page"><span class="alt">TT2 Home Page</span></a>
 
24
          <ul id="trail">
 
25
            <li><a href="../../../modules/index.html">Modules</a></li>
 
26
            <li><a href="../../../modules/Template/index.html">Template::*</a></li>
 
27
            <li><a href="../../../modules/Template/Plugin/index.html">Plugin::*</a></li>
 
28
            <li class="last"><a href="../../../modules/Template/Plugin/Table.html">Table.pm</a></li>
 
29
          </ul>
 
30
          <div class="controls">
 
31
            <a href="#" class="menu show" onclick="widescreen_off(); return false" title="Show Menu">
 
32
              <span class="about">Click to view the menu.  It's very nice.</span>
 
33
            </a>
 
34
            <a href="#" class="menu hide" onclick="widescreen_on();  return false" title="Hide Menu">
 
35
              <span class="about">Click to hide the menu and go all widescreen!</span>
 
36
            </a>
 
37
          
 
38
          <div class="pager">
 
39
            <a href="../../../modules/Template/Plugin/String.html" title="Template::Plugin::String" class="go back">Back<span class="about"><h4>Template::Plugin::String</h4>Object oriented interface for string manipulation</span></a>
 
40
            <a href="../../../modules/Template/Plugin/index.html" title="Template::Plugin::* Modules" class="go up">Up<span class="about"><h4>Template::Plugin::* Modules</h4></span></a>
 
41
            <a href="../../../modules/Template/Plugin/URL.html" title="Template::Plugin::URL" class="go next">Next<span class="about"><h4>Template::Plugin::URL</h4>Plugin to construct complex URLs</span></a>
 
42
          </div>
 
43
          </div>
 
44
          <h1 class="headline">Template::Plugin::Table</h1>
 
45
          <h2 class="subhead">Plugin to present data in a table</h1>
 
46
        
 
47
        </div>
 
48
        <div id="page">
 
49
          <div id="sidebar">
 
50
            <a href="../../../index.html" id="logo"></a>
 
51
            <div id="menu">
 
52
              <ul class="menu">
 
53
                <li class="l0 first"><a href="../../../manual/index.html">Manual</a></li>
 
54
                <li class="l0"><a href="../../../modules/index.html" class="warm">Modules</a></li>
 
55
                <li class="l1"><a href="../../../modules/Template.html">Template.pm</a></li>
 
56
                <li class="l1"><a href="../../../modules/Template/index.html" class="warm">Template::*</a></li>
 
57
                <li class="l2"><a href="../../../modules/Template/Base.html">Base.pm</a></li>
 
58
                <li class="l2"><a href="../../../modules/Template/Config.html">Config.pm</a></li>
 
59
                <li class="l2"><a href="../../../modules/Template/Constants.html">Constants.pm</a></li>
 
60
                <li class="l2"><a href="../../../modules/Template/Context.html">Context.pm</a></li>
 
61
                <li class="l2"><a href="../../../modules/Template/Directive.html">Directive.pm</a></li>
 
62
                <li class="l2"><a href="../../../modules/Template/Document.html">Document.pm</a></li>
 
63
                <li class="l2"><a href="../../../modules/Template/Exception.html">Exception.pm</a></li>
 
64
                <li class="l2"><a href="../../../modules/Template/Filters.html">Filters.pm</a></li>
 
65
                <li class="l2"><a href="../../../modules/Template/Grammar.html">Grammar.pm</a></li>
 
66
                <li class="l2"><a href="../../../modules/Template/Iterator.html">Iterator.pm</a></li>
 
67
                <li class="l2"><a href="../../../modules/Template/Namespace/index.html">Namespace::*</a></li>
 
68
                <li class="l2"><a href="../../../modules/Template/Parser.html">Parser.pm</a></li>
 
69
                <li class="l2"><a href="../../../modules/Template/Plugin.html">Plugin.pm</a></li>
 
70
                <li class="l2"><a href="../../../modules/Template/Plugin/index.html" class="warm">Plugin::*</a></li>
 
71
                <li class="l3"><a href="../../../modules/Template/Plugin/Autoformat.html">Autoformat.pm</a></li>
 
72
                <li class="l3"><a href="../../../modules/Template/Plugin/CGI.html">CGI.pm</a></li>
 
73
                <li class="l3"><a href="../../../modules/Template/Plugin/Datafile.html">Datafile.pm</a></li>
 
74
                <li class="l3"><a href="../../../modules/Template/Plugin/Date.html">Date.pm</a></li>
 
75
                <li class="l3"><a href="../../../modules/Template/Plugin/Directory.html">Directory.pm</a></li>
 
76
                <li class="l3"><a href="../../../modules/Template/Plugin/Dumper.html">Dumper.pm</a></li>
 
77
                <li class="l3"><a href="../../../modules/Template/Plugin/File.html">File.pm</a></li>
 
78
                <li class="l3"><a href="../../../modules/Template/Plugin/Filter.html">Filter.pm</a></li>
 
79
                <li class="l3"><a href="../../../modules/Template/Plugin/Format.html">Format.pm</a></li>
 
80
                <li class="l3"><a href="../../../modules/Template/Plugin/HTML.html">HTML.pm</a></li>
 
81
                <li class="l3"><a href="../../../modules/Template/Plugin/Image.html">Image.pm</a></li>
 
82
                <li class="l3"><a href="../../../modules/Template/Plugin/Iterator.html">Iterator.pm</a></li>
 
83
                <li class="l3"><a href="../../../modules/Template/Plugin/Math.html">Math.pm</a></li>
 
84
                <li class="l3"><a href="../../../modules/Template/Plugin/Pod.html">Pod.pm</a></li>
 
85
                <li class="l3"><a href="../../../modules/Template/Plugin/Procedural.html">Procedural.pm</a></li>
 
86
                <li class="l3"><a href="../../../modules/Template/Plugin/String.html">String.pm</a></li>
 
87
                <li class="l3"><a href="../../../modules/Template/Plugin/Table.html" class="warm">Table.pm</a></li>
 
88
                <li class="l3"><a href="../../../modules/Template/Plugin/URL.html">URL.pm</a></li>
 
89
                <li class="l3"><a href="../../../modules/Template/Plugin/View.html">View.pm</a></li>
 
90
                <li class="l3"><a href="../../../modules/Template/Plugin/Wrap.html">Wrap.pm</a></li>
 
91
                <li class="l2"><a href="../../../modules/Template/Plugins.html">Plugins.pm</a></li>
 
92
                <li class="l2"><a href="../../../modules/Template/Provider.html">Provider.pm</a></li>
 
93
                <li class="l2"><a href="../../../modules/Template/Service.html">Service.pm</a></li>
 
94
                <li class="l2"><a href="../../../modules/Template/Stash.html">Stash.pm</a></li>
 
95
                <li class="l2"><a href="../../../modules/Template/Stash/index.html">Stash::*</a></li>
 
96
                <li class="l2"><a href="../../../modules/Template/Test.html">Test.pm</a></li>
 
97
                <li class="l2"><a href="../../../modules/Template/VMethods.html">VMethods.pm</a></li>
 
98
                <li class="l2"><a href="../../../modules/Template/View.html">View.pm</a></li>
 
99
                <li class="l0"><a href="../../../tools/index.html">Tools</a></li>
 
100
                <li class="l0 last"><a href="../../../tutorial/index.html">Tutorial</a></li>
 
101
              </ul>
 
102
              <div class="foot"></div>
 
103
            </div>
 
104
          </div>
 
105
          <div id="content">
 
106
          <div class="section">
 
107
            <div class="head">
 
108
              <h1 id="contents" onclick="switch_section(this)" title="Click title to show/hide section content.">Contents</h1>
 
109
              <a href="#body" class="top" title="Back up to the top of the page" >Top</a>
 
110
            </div>
 
111
            <div class="body">
 
112
              <ul class="toc">
 
113
                  <li class=""><a href="#SYNOPSIS">SYNOPSIS</a></li>
 
114
                  <li class=""><a href="#DESCRIPTION">DESCRIPTION</a></li>
 
115
                  <li class=""><a href="#AUTHOR">AUTHOR</a></li>
 
116
                  <li class=""><a href="#COPYRIGHT">COPYRIGHT</a></li>
 
117
                  <li class=""><a href="#SEE_ALSO">SEE ALSO</a></li>
 
118
              
 
119
              </ul>
 
120
            </div>
 
121
          </div>
 
122
          
 
123
                <div class="pod">
 
124
            <div class="section">
 
125
              <div class="head">
 
126
                <h1 id="SYNOPSIS" onclick="switch_section(this)" title="Click title to show/hide section content.">SYNOPSIS</h1>
 
127
                <a href="#body" class="top" title="Back up to the top of the page" >Top</a>
 
128
              </div>
 
129
              <div class="body">
 
130
                <pre>[% USE table(list, rows=n, cols=n, overlap=n, pad=0) %]
 
131
 
 
132
[% FOREACH item IN table.row(n) %]
 
133
   [% item %]
 
134
[% END %]
 
135
 
 
136
[% FOREACH item IN table.col(n) %]
 
137
   [% item %]
 
138
[% END %]
 
139
 
 
140
[% FOREACH row IN table.rows %]
 
141
   [% FOREACH item IN row %]
 
142
      [% item %]
 
143
   [% END %]
 
144
[% END %]
 
145
 
 
146
[% FOREACH col IN table.cols %]
 
147
   [% col.first %] - [% col.last %] ([% col.size %] entries)
 
148
[% END %]</pre>
 
149
              </div>
 
150
            </div>
 
151
            <div class="section">
 
152
              <div class="head">
 
153
                <h1 id="DESCRIPTION" onclick="switch_section(this)" title="Click title to show/hide section content.">DESCRIPTION</h1>
 
154
                <a href="#body" class="top" title="Back up to the top of the page" >Top</a>
 
155
              </div>
 
156
              <div class="body">
 
157
                <p>
 
158
                      The <code>Table</code> plugin allows you to format a list of data items
 
159
                      into a virtual table. When you create a <code>Table</code> plugin via the
 
160
                      <code>USE</code> directive, simply pass a list reference as the first
 
161
                      parameter and then specify a fixed number of rows or columns.
 
162
                    </p>
 
163
                    <pre>[% USE Table(list, rows=5) %]
 
164
[% USE table(list, cols=5) %]</pre>
 
165
                    <p>
 
166
                      The <code>Table</code> plugin name can also be specified in lower case as
 
167
                      shown in the second example above. You can also specify an alternative
 
168
                      variable name for the plugin as per regular Template Toolkit syntax.
 
169
                    </p>
 
170
                    <pre>[% USE mydata = table(list, rows=5) %]</pre>
 
171
                    <p>
 
172
                      The plugin then presents a table based view on the data set. The data
 
173
                      isn't actually reorganised in any way but is available via the
 
174
                      <code>row()</code>, <code>col()</code>, <code>rows()</code> and
 
175
                      <code>cols()</code> as if formatted into a simple two dimensional table
 
176
                      of <code>n</code> rows x <code>n</code> columns.
 
177
                    </p>
 
178
                    <p>
 
179
                      So if we had a sample <code>alphabet</code> list contained the letters
 
180
                      '<code>a</code>' to '<code>z</code>', the above <code>USE</code>
 
181
                      directives would create plugins that represented the following views of
 
182
                      the alphabet.
 
183
                    </p>
 
184
                    <pre>[% USE table(alphabet, ... %]
 
185
 
 
186
rows=5                  cols=5
 
187
a  f  k  p  u  z        a  g  m  s  y
 
188
b  g  l  q  v           b  h  n  t  z
 
189
c  h  m  r  w           c  i  o  u
 
190
d  i  n  s  x           d  j  p  v
 
191
e  j  o  t  y           e  k  q  w
 
192
                        f  l  r  x</pre>
 
193
                    <p>
 
194
                      We can request a particular row or column using the <code>row()</code>
 
195
                      and <code>col()</code> methods.
 
196
                    </p>
 
197
                    <pre>[% USE table(alphabet, rows=5) %]
 
198
[% FOREACH item = table.row(0) %]
 
199
   # [% item %] set to each of [ a f k p u z ] in turn
 
200
[% END %]
 
201
 
 
202
[% FOREACH item = table.col(2) %]
 
203
   # [% item %] set to each of [ m n o p q r ] in turn
 
204
[% END %]</pre>
 
205
                    <p>
 
206
                      Data in rows is returned from left to right, columns from top to bottom.
 
207
                      The first row/column is 0. By default, rows or columns that contain empty
 
208
                      values will be padded with the undefined value to fill it to the same
 
209
                      size as all other rows or columns.
 
210
                    </p>
 
211
                    <p>
 
212
                      For example, the last row (row 4) in the first example would contain the
 
213
                      values <code>[ e j o t y undef ]</code>. The Template Toolkit will safely
 
214
                      accept these undefined values and print a empty string. You can also use
 
215
                      the IF directive to test if the value is set.
 
216
                    </p>
 
217
                    <pre> [% FOREACH item = table.row(4) %]
 
218
[% IF item %]
 
219
   Item: [% item %]
 
220
[% END %]
 
221
 [% END %]</pre>
 
222
                    <p>
 
223
                      You can explicitly disable the <code>pad</code> option when creating the
 
224
                      plugin to returned shortened rows/columns where the data is empty.
 
225
                    </p>
 
226
                    <pre> [% USE table(alphabet, cols=5, pad=0) %]
 
227
 [% FOREACH item = table.col(4) %]
 
228
# [% item %] set to each of 'y z'
 
229
 [% END %]</pre>
 
230
                    <p>
 
231
                      The <code>rows()</code> method returns all rows/columns in the table as a
 
232
                      reference to a list of rows (themselves list references). The
 
233
                      <code>row()</code> methods when called without any arguments calls
 
234
                      <code>rows()</code> to return all rows in the table.
 
235
                    </p>
 
236
                    <p>
 
237
                      Ditto for <code>cols()</code> and <code>col()</code>.
 
238
                    </p>
 
239
                    <pre>[% USE table(alphabet, cols=5) %]
 
240
[% FOREACH row = table.rows %]
 
241
   [% FOREACH item = row %]
 
242
      [% item %]
 
243
   [% END %]
 
244
[% END %]</pre>
 
245
                    <p>
 
246
                      The Template Toolkit provides the <code>first</code>, <code>last</code>
 
247
                      and <code>size</code> virtual methods that can be called on list
 
248
                      references to return the first/last entry or the number of entries in a
 
249
                      list. The following example shows how we might use this to provide an
 
250
                      alphabetical index split into 3 even parts.
 
251
                    </p>
 
252
                    <pre>[% USE table(alphabet, cols=3, pad=0) %]
 
253
[% FOREACH group = table.col %]
 
254
   [ [% group.first %] - [% group.last %] ([% group.size %] letters) ]
 
255
[% END %]</pre>
 
256
                    <p>
 
257
                      This produces the following output:
 
258
                    </p>
 
259
                    <pre>[ a - i (9 letters) ]
 
260
[ j - r (9 letters) ]
 
261
[ s - z (8 letters) ]</pre>
 
262
                    <p>
 
263
                      We can also use the general purpose <code>join</code> virtual method
 
264
                      which joins the items of the list using the connecting string specified.
 
265
                    </p>
 
266
                    <pre>[% USE table(alphabet, cols=5) %]
 
267
[% FOREACH row = table.rows %]
 
268
   [% row.join(' - ') %]
 
269
[% END %]</pre>
 
270
                    <p>
 
271
                      Data in the table is ordered downwards rather than across but can easily
 
272
                      be transformed on output. For example, to format our data in 5 columns
 
273
                      with data ordered across rather than down, we specify <code>rows=5</code>
 
274
                      to order the data as such:
 
275
                    </p>
 
276
                    <pre>a  f  .  .
 
277
b  g  .
 
278
c  h
 
279
d  i
 
280
e  j</pre>
 
281
                    <p>
 
282
                      and then iterate down through each column (a-e, f-j, etc.) printing the
 
283
                      data across.
 
284
                    </p>
 
285
                    <pre>a  b  c  d  e
 
286
f  g  h  i  j
 
287
.  .
 
288
.</pre>
 
289
                    <p>
 
290
                      Example code to do so would be much like the following:
 
291
                    </p>
 
292
                    <pre>[% USE table(alphabet, rows=3) %]
 
293
[% FOREACH cols = table.cols %]
 
294
  [% FOREACH item = cols %]
 
295
    [% item %]
 
296
  [% END %]
 
297
[% END %]</pre>
 
298
                    <p>
 
299
                      Output:
 
300
                    </p>
 
301
                    <pre>a  b  c
 
302
d  e  f
 
303
g  h  i
 
304
j  .  .
 
305
.</pre>
 
306
                    <p>
 
307
                      In addition to a list reference, the <code>Table</code> plugin
 
308
                      constructor may be passed a reference to a <a href="../../../modules/Template/Iterator.html">Template::Iterator</a> object or
 
309
                      subclass thereof. The <a href="../../../modules/Template/Iterator.html">Template::Iterator</a> <a href="../../../modules/Template/Iterator.html#method_get_all">get_all()</a> method is first called on the iterator
 
310
                      to return all remaining items. These are then available via the usual
 
311
                      Table interface.
 
312
                    </p>
 
313
                    <pre>[% USE DBI(dsn,user,pass) -%]
 
314
 
 
315
# query() returns an iterator
 
316
[% results = DBI.query('SELECT * FROM alphabet ORDER BY letter') %]</pre>
 
317
                    <pre># pass into Table plugin
 
318
[% USE table(results, rows=8 overlap=1 pad=0) -%]
 
319
 
 
320
[% FOREACH row = table.cols -%]
 
321
   [% row.first.letter %] - [% row.last.letter %]:
 
322
      [% row.join(', ') %]
 
323
[% END %]</pre>
 
324
              </div>
 
325
            </div>
 
326
            <div class="section">
 
327
              <div class="head">
 
328
                <h1 id="AUTHOR" onclick="switch_section(this)" title="Click title to show/hide section content.">AUTHOR</h1>
 
329
                <a href="#body" class="top" title="Back up to the top of the page" >Top</a>
 
330
              </div>
 
331
              <div class="body">
 
332
                <p>
 
333
                      Andy Wardley &lt;abw@wardley.org&gt; <a
 
334
                      href="http://wardley.org/">http://wardley.org/</a>
 
335
                    </p>
 
336
              </div>
 
337
            </div>
 
338
            <div class="section">
 
339
              <div class="head">
 
340
                <h1 id="COPYRIGHT" onclick="switch_section(this)" title="Click title to show/hide section content.">COPYRIGHT</h1>
 
341
                <a href="#body" class="top" title="Back up to the top of the page" >Top</a>
 
342
              </div>
 
343
              <div class="body">
 
344
                <p>
 
345
                      Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
 
346
                    </p>
 
347
                    <p>
 
348
                      This module is free software; you can redistribute it and/or modify it
 
349
                      under the same terms as Perl itself.
 
350
                    </p>
 
351
              </div>
 
352
            </div>
 
353
            <div class="section">
 
354
              <div class="head">
 
355
                <h1 id="SEE_ALSO" onclick="switch_section(this)" title="Click title to show/hide section content.">SEE ALSO</h1>
 
356
                <a href="#body" class="top" title="Back up to the top of the page" >Top</a>
 
357
              </div>
 
358
              <div class="body">
 
359
                <p>
 
360
                      <a href="../../../modules/Template/Plugin.html">Template::Plugin</a>
 
361
                    </p>
 
362
              </div>
 
363
            </div>
 
364
            
 
365
            </div></div>
 
366
          <br class="clear" />
 
367
          <div class="pageinfo">
 
368
            /modules/Template/Plugin/Table.html last modified 10:55:04 31-May-2007
 
369
          </div>
 
370
        </div>
 
371
        
 
372
        <div id="footer">
 
373
          <a href="http://opensource.org/" class="osi"></a>
 
374
          <div class="controls">
 
375
          <div class="pager">
 
376
            <a href="../../../modules/Template/Plugin/String.html" title="Template::Plugin::String" class="go back">Back<span class="about"><h4>Template::Plugin::String</h4></span></a>
 
377
            <a href="../../../modules/Template/Plugin/index.html" title="Template::Plugin::* Modules" class="go up">Up<span class="about"><h4>Template::Plugin::* Modules</h4></span></a>
 
378
            <a href="../../../modules/Template/Plugin/URL.html" title="Template::Plugin::URL" class="go next">Next<span class="about"><h4>Template::Plugin::URL</h4></span></a>
 
379
          </div>
 
380
          </div>
 
381
          <div class="copyright">
 
382
            Copyright &copy; 1996-2007 <a href="http://wardley.org/">Andy Wardley</a>.  All Rights Reserved.
 
383
          </div>
 
384
          <div class="licence">
 
385
            The <a href="http://template-toolkit.org/">Template Toolkit</a> is <a href="http://opensource.org/">Open Source</a> software.
 
386
            You can redistribute and/or modify it under the terms of the <a href="http://www.opensource.org/licenses/gpl-license.php">GNU Public Licence</a>
 
387
            or the <a href="http://www.opensource.org/licenses/artistic-license.php">Perl Artistic Licence</a>.
 
388
          </div>
 
389
        </div>
 
390
        <div id="palette">
 
391
          <ul>
 
392
            <li class="first"><a href="#" class="blue" onclick="set_style('Clear Blue')"></a></li>
 
393
            <li><a href="#" class="orange" onclick="set_style('Clear Orange')"></a></li>
 
394
            <li><a href="#" class="green" onclick="set_style('Clear Green')"></a></li>
 
395
            <li><a href="#" class="purple" onclick="set_style('Clear Purple')"></a></li>
 
396
            <li><a href="#" class="grey" onclick="set_style('Clear Grey')"></a></li>
 
397
          </ul>
 
398
        </div>
 
399
    </div>  </body>
 
400
</html>