Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Template::Plugin::TablUser Contributed Perl DocumentTemplate::Plugin::Table(3)

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

	   [% 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 %]

       The "Table" plugin allows you to	format a list of data items into a
       virtual table.  When you	create a "Table" plugin	via the	"USE"
       directive, simply pass a	list reference as the first parameter and then
       specify a fixed number of rows or columns.

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

       The "Table" plugin name can also	be specified in	lower case as shown in
       the second example above.  You can also specify an alternative variable
       name for	the plugin as per regular Template Toolkit syntax.

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

       The plugin then presents	a table	based view on the data set.  The data
       isn't actually reorganised in any way but is available via the "row()",
       "col()",	"rows()" and "cols()" as if formatted into a simple two
       dimensional table of "n"	rows x "n" columns.

       So if we	had a sample "alphabet"	list contained the letters '"a"' to
       '"z"', the above	"USE" directives would create plugins that represented
       the following 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	particular row or column using the "row()" and "col()"

	   [% 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 is returned	from left to right, columns from top to
       bottom.	The first row/column is	0.  By default,	rows or	columns	that
       contain empty values will be padded with	the undefined value to fill it
       to the same size	as all other rows or columns.

       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 these undefined values and print a empty string. You can also
       use the IF directive to test if 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 to
       returned	shortened rows/columns where the data is empty.

	  [% 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).  The "row()"
       methods when called without any arguments 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. The following example shows
       how we might use	this 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 specified.

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

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

	   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 so would be much like	the following:

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


	   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 subclass thereof.
       The Template::Iterator get_all()	method is first	called on the iterator
       to return all remaining items. These are	then available via the usual
       Table interface.

	   [% 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 %]

       Andy Wardley <> <>

       Copyright (C) 1996-2007 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.


perl v5.32.1			  2020-07-13	    Template::Plugin::Table(3)


Want to link to this manual page? Use this URL:

home | help