1#============================================================= -*-Perl-*- 2# 3# Template::Plugin::Table 4# 5# DESCRIPTION 6# Plugin to order a linear data set into a virtual 2-dimensional table 7# from which row and column permutations can be fetched. 8# 9# AUTHOR 10# Andy Wardley <abw@wardley.org> 11# 12# COPYRIGHT 13# Copyright (C) 2000-2007 Andy Wardley. All Rights Reserved. 14# 15# This module is free software; you can redistribute it and/or 16# modify it under the same terms as Perl itself. 17# 18#============================================================================ 19 20package Template::Plugin::Table; 21 22use strict; 23use warnings; 24use base 'Template::Plugin'; 25use Scalar::Util 'blessed'; 26 27our $VERSION = '3.010'; 28our $AUTOLOAD; 29 30 31#------------------------------------------------------------------------ 32# new($context, \@data, \%args) 33# 34# This constructor method initialises the object to iterate through 35# the data set passed by reference to a list as the first parameter. 36# It calculates the shape of the permutation table based on the ROWS 37# or COLS parameters specified in the $args hash reference. The 38# OVERLAP parameter may be provided to specify the number of common 39# items that should be shared between subsequent columns. 40#------------------------------------------------------------------------ 41 42sub new { 43 my ($class, $context, $data, $params) = @_; 44 my ($size, $rows, $cols, $coloff, $overlap, $error); 45 46 # if the data item is a reference to a Template::Iterator object, 47 # or subclass thereof, we call its get_all() method to extract all 48 # the data it contains 49 if (blessed($data) && $data->isa('Template::Iterator')) { 50 ($data, $error) = $data->get_all(); 51 return $class->error("iterator failed to provide data for table: ", 52 $error) 53 if $error; 54 } 55 56 return $class->error('invalid table data, expecting a list') 57 unless ref $data eq 'ARRAY'; 58 59 $params ||= { }; 60 return $class->error('invalid table parameters, expecting a hash') 61 unless ref $params eq 'HASH'; 62 63 # ensure keys are folded to upper case 64 @$params{ map { uc } keys %$params } = values %$params; 65 66 $size = scalar @$data; 67 $overlap = $params->{ OVERLAP } || 0; 68 69 # calculate number of columns based on a specified number of rows 70 if ($rows = $params->{ ROWS }) { 71 if ($size < $rows) { 72 $rows = $size; # pad? 73 $cols = 1; 74 $coloff = 0; 75 } 76 else { 77 $coloff = $rows - $overlap; 78 $cols = int ($size / $coloff) 79 + ($size % $coloff > $overlap ? 1 : 0) 80 } 81 } 82 # calculate number of rows based on a specified number of columns 83 elsif ($cols = $params->{ COLS }) { 84 if ($size < $cols) { 85 $cols = $size; 86 $rows = 1; 87 $coloff = 1; 88 } 89 else { 90 $coloff = int ($size / $cols) 91 + ($size % $cols > $overlap ? 1 : 0); 92 $rows = $coloff + $overlap; 93 } 94 } 95 else { 96 $rows = $size; 97 $cols = 1; 98 $coloff = 0; 99 } 100 101 bless { 102 _DATA => $data, 103 _SIZE => $size, 104 _NROWS => $rows, 105 _NCOLS => $cols, 106 _COLOFF => $coloff, 107 _OVERLAP => $overlap, 108 _PAD => defined $params->{ PAD } ? $params->{ PAD } : 1, 109 }, $class; 110} 111 112 113#------------------------------------------------------------------------ 114# row($n) 115# 116# Returns a reference to a list containing the items in the row whose 117# number is specified by parameter. If the row number is undefined, 118# it calls rows() to return a list of all rows. 119#------------------------------------------------------------------------ 120 121sub row { 122 my ($self, $row) = @_; 123 my ($data, $cols, $offset, $size, $pad) 124 = @$self{ qw( _DATA _NCOLS _COLOFF _SIZE _PAD) }; 125 my @set; 126 127 # return all rows if row number not specified 128 return $self->rows() 129 unless defined $row; 130 131 return () if $row >= $self->{ _NROWS } || $row < 0; 132 133 my $index = $row; 134 135 for (my $c = 0; $c < $cols; $c++) { 136 push(@set, $index < $size 137 ? $data->[$index] 138 : ($pad ? undef : ())); 139 $index += $offset; 140 } 141 return \@set; 142} 143 144 145#------------------------------------------------------------------------ 146# col($n) 147# 148# Returns a reference to a list containing the items in the column whose 149# number is specified by parameter. If the column number is undefined, 150# it calls cols() to return a list of all columns. 151#------------------------------------------------------------------------ 152 153sub col { 154 my ($self, $col) = @_; 155 my ($data, $size) = @$self{ qw( _DATA _SIZE ) }; 156 my ($start, $end); 157 my $blanks = 0; 158 159 # return all cols if row number not specified 160 return $self->cols() 161 unless defined $col; 162 163 return () if $col >= $self->{ _NCOLS } || $col < 0; 164 165 $start = $self->{ _COLOFF } * $col; 166 $end = $start + $self->{ _NROWS } - 1; 167 $end = $start if $end < $start; 168 if ($end >= $size) { 169 $blanks = ($end - $size) + 1; 170 $end = $size - 1; 171 } 172 return () if $start >= $size; 173 return [ @$data[$start..$end], 174 $self->{ _PAD } ? ((undef) x $blanks) : () ]; 175} 176 177 178#------------------------------------------------------------------------ 179# rows() 180# 181# Returns all rows as a reference to a list of rows. 182#------------------------------------------------------------------------ 183 184sub rows { 185 my $self = shift; 186 return [ map { $self->row($_) } (0..$self->{ _NROWS }-1) ]; 187} 188 189 190#------------------------------------------------------------------------ 191# cols() 192# 193# Returns all rows as a reference to a list of rows. 194#------------------------------------------------------------------------ 195 196sub cols { 197 my $self = shift; 198 return [ map { $self->col($_) } (0..$self->{ _NCOLS }-1) ]; 199} 200 201 202#------------------------------------------------------------------------ 203# AUTOLOAD 204# 205# Provides read access to various internal data members. 206#------------------------------------------------------------------------ 207 208sub AUTOLOAD { 209 my $self = shift; 210 my $item = $AUTOLOAD; 211 $item =~ s/.*:://; 212 return if $item eq 'DESTROY'; 213 214 if ($item =~ /^(?:data|size|nrows|ncols|overlap|pad)$/) { 215 return $self->{ $item }; 216 } 217 else { 218 return (undef, "no such table method: $item"); 219 } 220} 221 222 223 2241; 225 226__END__ 227 228=head1 NAME 229 230Template::Plugin::Table - Plugin to present data in a table 231 232=head1 SYNOPSIS 233 234 [% USE table(list, rows=n, cols=n, overlap=n, pad=0) %] 235 236 [% FOREACH item IN table.row(n) %] 237 [% item %] 238 [% END %] 239 240 [% FOREACH item IN table.col(n) %] 241 [% item %] 242 [% END %] 243 244 [% FOREACH row IN table.rows %] 245 [% FOREACH item IN row %] 246 [% item %] 247 [% END %] 248 [% END %] 249 250 [% FOREACH col IN table.cols %] 251 [% col.first %] - [% col.last %] ([% col.size %] entries) 252 [% END %] 253 254=head1 DESCRIPTION 255 256The C<Table> plugin allows you to format a list of data items into a 257virtual table. When you create a C<Table> plugin via the C<USE> directive, 258simply pass a list reference as the first parameter and then specify 259a fixed number of rows or columns. 260 261 [% USE Table(list, rows=5) %] 262 [% USE table(list, cols=5) %] 263 264The C<Table> plugin name can also be specified in lower case as shown 265in the second example above. You can also specify an alternative variable 266name for the plugin as per regular Template Toolkit syntax. 267 268 [% USE mydata = table(list, rows=5) %] 269 270The plugin then presents a table based view on the data set. The data 271isn't actually reorganised in any way but is available via the C<row()>, 272C<col()>, C<rows()> and C<cols()> as if formatted into a simple two dimensional 273table of C<n> rows x C<n> columns. 274 275So if we had a sample C<alphabet> list contained the letters 'C<a>' to 'C<z>', 276the above C<USE> directives would create plugins that represented the following 277views of the alphabet. 278 279 [% USE table(alphabet, ... %] 280 281 rows=5 cols=5 282 a f k p u z a g m s y 283 b g l q v b h n t z 284 c h m r w c i o u 285 d i n s x d j p v 286 e j o t y e k q w 287 f l r x 288 289We can request a particular row or column using the C<row()> and C<col()> 290methods. 291 292 [% USE table(alphabet, rows=5) %] 293 [% FOREACH item = table.row(0) %] 294 # [% item %] set to each of [ a f k p u z ] in turn 295 [% END %] 296 297 [% FOREACH item = table.col(2) %] 298 # [% item %] set to each of [ m n o p q r ] in turn 299 [% END %] 300 301Data in rows is returned from left to right, columns from top to 302bottom. The first row/column is 0. By default, rows or columns that 303contain empty values will be padded with the undefined value to fill 304it to the same size as all other rows or columns. 305 306For example, the last row (row 4) in the first example would contain the 307values C<[ e j o t y undef ]>. The Template Toolkit will safely accept these 308undefined values and print a empty string. You can also use the IF directive 309to test if the value is set. 310 311 [% FOREACH item = table.row(4) %] 312 [% IF item %] 313 Item: [% item %] 314 [% END %] 315 [% END %] 316 317You can explicitly disable the C<pad> option when creating the plugin to 318returned shortened rows/columns where the data is empty. 319 320 [% USE table(alphabet, cols=5, pad=0) %] 321 [% FOREACH item = table.col(4) %] 322 # [% item %] set to each of 'y z' 323 [% END %] 324 325The C<rows()> method returns all rows/columns in the table as a reference 326to a list of rows (themselves list references). The C<row()> methods 327when called without any arguments calls C<rows()> to return all rows in 328the table. 329 330Ditto for C<cols()> and C<col()>. 331 332 [% USE table(alphabet, cols=5) %] 333 [% FOREACH row = table.rows %] 334 [% FOREACH item = row %] 335 [% item %] 336 [% END %] 337 [% END %] 338 339The Template Toolkit provides the C<first>, C<last> and C<size> virtual 340methods that can be called on list references to return the first/last entry 341or the number of entries in a list. The following example shows how we might 342use this to provide an alphabetical index split into 3 even parts. 343 344 [% USE table(alphabet, cols=3, pad=0) %] 345 [% FOREACH group = table.col %] 346 [ [% group.first %] - [% group.last %] ([% group.size %] letters) ] 347 [% END %] 348 349This produces the following output: 350 351 [ a - i (9 letters) ] 352 [ j - r (9 letters) ] 353 [ s - z (8 letters) ] 354 355We can also use the general purpose C<join> virtual method which joins 356the items of the list using the connecting string specified. 357 358 [% USE table(alphabet, cols=5) %] 359 [% FOREACH row = table.rows %] 360 [% row.join(' - ') %] 361 [% END %] 362 363Data in the table is ordered downwards rather than across but can easily 364be transformed on output. For example, to format our data in 5 columns 365with data ordered across rather than down, we specify C<rows=5> to order 366the data as such: 367 368 a f . . 369 b g . 370 c h 371 d i 372 e j 373 374and then iterate down through each column (a-e, f-j, etc.) printing 375the data across. 376 377 a b c d e 378 f g h i j 379 . . 380 . 381 382Example code to do so would be much like the following: 383 384 [% USE table(alphabet, rows=3) %] 385 [% FOREACH cols = table.cols %] 386 [% FOREACH item = cols %] 387 [% item %] 388 [% END %] 389 [% END %] 390 391Output: 392 393 a b c 394 d e f 395 g h i 396 j . . 397 . 398 399In addition to a list reference, the C<Table> plugin constructor may be passed 400a reference to a L<Template::Iterator> object or subclass thereof. The 401L<Template::Iterator> L<get_all()|Template::Iterator#get_all()> method is 402first called on the iterator to return all remaining items. These are then 403available via the usual Table interface. 404 405 [% USE DBI(dsn,user,pass) -%] 406 407 # query() returns an iterator 408 [% results = DBI.query('SELECT * FROM alphabet ORDER BY letter') %] 409 410 # pass into Table plugin 411 [% USE table(results, rows=8 overlap=1 pad=0) -%] 412 413 [% FOREACH row = table.cols -%] 414 [% row.first.letter %] - [% row.last.letter %]: 415 [% row.join(', ') %] 416 [% END %] 417 418=head1 AUTHOR 419 420Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> 421 422=head1 COPYRIGHT 423 424Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. 425 426This module is free software; you can redistribute it and/or 427modify it under the same terms as Perl itself. 428 429=head1 SEE ALSO 430 431L<Template::Plugin> 432 433=cut 434 435# Local Variables: 436# mode: perl 437# perl-indent-level: 4 438# indent-tabs-mode: nil 439# End: 440# 441# vim: expandtab shiftwidth=4: 442