Templat...n::Table(3)

💖 Template::Plugin::Table(3) — User Contributed Perl Documentation 💖

okay bestie, welcome to the manual page for Template::Plugin::Table. The header shortens the name to Templat...n::Table(3) (truncation vibes, but we move 💅), and it's filed under the User Contributed Perl Documentation. This plugin is here to help you present a list of data items as a virtual table. Slay.

🌸 NAME 🌸

Template::Plugin::Table — Plugin to present data in a table. periodt.

✨ SYNOPSIS ✨

Here's the whole vibe in Template Toolkit code:

[% USE table(list, rows=n, cols=n, overlap=n, pad=0) %]

[% FOREACH item IN table.row(n) %]
   [% item %]
[% END]

[% FOREACH item IN table.col(n) %]
   [% item %]
[% END]

[% FOREACH row IN table.rows %]
   [% FOREACH item IN row %]
      [% item %]
   [% END]
[% END]

[% FOREACH col IN table.cols %]
   [% col.first %] - [% col.last %] ([% col.size %] entries)
[% END]

🦋 DESCRIPTION 🦋

The Table plugin lets you format a list of data items into a virtual table. When you create a Table plugin with the USE directive, you just pass a list reference as the first parameter, then specify a fixed number of rows or columns. No cap, that's the whole setup.

[% USE Table(list, rows=5) %]
[% USE table(list, cols=5) %]

You can write the Table plugin name in lowercase too, like in the second example above. You can also give the plugin an alternative variable name using regular Template Toolkit syntax.

[% USE mydata = table(list, rows=5) %]

Then the plugin gives you a table-based view of the data set. The data is not actually reorganised in any way — it's just available through row(), col(), rows() and cols() as if it were formatted into a simple two-dimensional table of n rows x n columns. It's giving illusion of structure, honestly.

So if we had a sample alphabet list containing the letters "a" to "z", those USE directives above would create plugins representing these views of the alphabet:

[% USE table(alphabet, ... %]

rows=5                  cols=5
a  f  k  p  u  z        a  g  m  s  y
b  g  l  q  v           b  h  n  t  z
c  h  m  r  w           c  i  o  u
d  i  n  s  x           d  j  p  v
e  j  o  t  y           e  k  q  w
                        f  l  r  x

We can request a specific row or column with the row() and col() methods. Pick your fighter:

[% USE table(alphabet, rows=5) %]
[% FOREACH item = table.row(0) %]
   # [% item %] set to each of [ a f k p u z ] in turn
[% END]

[% FOREACH item = table.col(2) %]
   # [% item %] set to each of [ m n o p q r ] in turn
[% END]

Data in rows comes back from left to right, and columns come back from top to bottom. The first row/column is 0. By default, rows or columns that contain empty values get padded with the undefined value so they fill to the same size as all other rows or columns. Consistency queen.

For example, the last row (row 4) in the first example would contain the values [ e j o t y undef ]. The Template Toolkit will safely accept those undefined values and print an empty string. You can also use the IF directive to test whether the value is set.

[% FOREACH item = table.row(4) %]
   [% IF item %]
      Item: [% item %]
   [% END]
[% END]

You can explicitly disable the pad option when creating the plugin if you want shortened rows/columns where the data is empty. Bye-bye padding, hello tiny columns.

[% USE table(alphabet, cols=5, pad=0) %]
[% FOREACH item = table.col(4) %]
   # [% item %] set to each of 'y z'
[% END]

The rows() method returns all rows/columns in the table as a reference to a list of rows (themselves list references). When row() is called without any arguments, it calls rows() to return all rows in the table. Ditto for cols() and col().

[% USE table(alphabet, cols=5) %]
[% FOREACH row = table.rows %]
   [% FOREACH item = row %]
      [% item %]
   [% END]
[% END]

The Template Toolkit provides the first, last and size virtual methods that can be called on list references to return the first/last entry or the number of entries in a list. Here's how we might use that to provide an alphabetical index split into 3 even parts:

[% USE table(alphabet, cols=3, pad=0) %]
[% FOREACH group = table.col %]
   [ [% group.first %] - [% group.last %] ([% group.size %] letters) ]
[% END]

This produces the following output:

[ a - i (9 letters) ]
[ j - r (9 letters) ]
[ s - z (8 letters) ]

We can also use the general-purpose join virtual method, which joins the items of the list using the connecting string you specify. String glue, but make it fashion.

[% USE table(alphabet, cols=5) %]
[% FOREACH row = table.rows %]
   [% row.join(' - ') %]
[% END]

Data in the table is ordered downwards rather than across, but it can easily be transformed on output. For example, to format our data in 5 columns with the data ordered across rather than down, we specify rows=5 to order the data like this:

a  f  .  .
b  g  .
c  h
d  i
e  j

and then iterate down through each column (a-e, f-j, etc.), printing the data across.

a  b  c  d  e
f  g  h  i  j
.  .
.

Example code to do that would look much like this:

[% USE table(alphabet, rows=3) %]
[% FOREACH cols = table.cols %]
  [% FOREACH item = cols %]
    [% item %]
  [% END]
[% END]

Output:

a  b  c
d  e  f
g  h  i
j  .  .
.

In addition to a list reference, the Table plugin constructor may be passed a reference to a Template::Iterator object or a subclass of it. The Template::Iterator get_all() method is called first on the iterator to return all remaining items. Those are then available through the usual Table interface. Iterator girlies, this one's for you.

[% USE DBI(dsn,user,pass) -%]

# query() returns an iterator
[% results = DBI.query('SELECT * FROM alphabet ORDER BY letter') %]

# pass into Table plugin
[% USE table(results, rows=8 overlap=1 pad=0) -%]

[% FOREACH row = table.cols -%]
   [% row.first.letter %] - [% row.last.letter %]:
      [% row.join(', ') %]
[% END]

👑 AUTHOR 👑

Andy Wardley <abw@wardley.org> <http://wardley.org/> — yes, that's the icon. Author credit served.

🎀 COPYRIGHT 🎀

Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Free software bestie, we love to see it.

🦋 SEE ALSO 🦋

• Template::Plugin

---

okay that's the whole page, bestie 🫶 this one came from perl v5.42.0, dated 2024-06-23, and the page label at the bottom is Templat...n::Table(3). go forth and table-ify your data, periodt. 💅✨