HTML::TableTiler - easily generates complex graphic styled HTML tables

HTML-TableTiler documentation Contained in the HTML-TableTiler distribution.

Index

Code Index:

NAME

Top

HTML::TableTiler - easily generates complex graphic styled HTML tables

VERSION 1.21

Top

The latest versions changes are reported in the Changes file in this distribution.

INSTALLATION

Top

Prerequisites
    HTML::PullParser >= 1.0
    IO::Util         >= 1.2
CPAN
    perl -MCPAN -e 'install HTML::TableTiler'
Standard installation

From the directory where this file is located, type:

    perl Makefile.PL
    make
    make test
    make install

SYNOPSIS

Top

the tile
    <table border="1" cellspacing="2" cellpadding="2">
    <tr>
        <td><b><i>a optional placeholder</i></b></td>
        <td>another optional placeholder</td>
    </tr>
    </table>
the code
    $matrix=[
               [ 'Balls', 'A470', 250, 2.75 ],
               [ 'Cubes', 'A520', 378, 3.25 ],
               [ 'Cones', 'A665', 186, 2.85 ]
            ];

Object-Oriented interface:

    use HTML::TableTiler;
    $tt = HTML::TableTiler->new(\$tile);
    print $tt->tile_table($matrix);

Function-Oriented interface

    use HTML::TableTiler qw(tile_table);
    print tile_table($matrix, \$tile);
the tiled table
    <table border="1" cellspacing="2" cellpadding="2">
    <tr>
        <td><b><i>Balls</i></b></td>
        <td>A470</td>
        <td>250</td>
        <td>2.75</td>
    </tr>
    <tr>
        <td><b><i>Cubes</i></b></td>
        <td>A520</td>
        <td>378</td>
        <td>3.25</td>
    </tr>
    <tr>
        <td><b><i>Cones</i></b></td>
        <td>A665</td>
        <td>186</td>
        <td>2.85</td>
    </tr>
    </table>

DESCRIPTION

Top

HTML::TableTiler uses a minimum HTML table as a tile to generate a complete HTML table from a bidimensional array of data. It can easily produce simple or complex graphic styled tables with minimum effort and maximum speed.

Think about the table tile as a sort of tile that automatically expands itself to contain the whole data. You can control the final look of a table by choosing either the HORIZONTAL and the VERTICAL tiling mode among: PULL, TILE and TRIM.

The main advantages to use it are:

* automatic table generation

Pass only a bidimensional array of data to generate a complete HTML table. No worry to decide in advance the quantity of cells (or rows) in the table.

* complex graphic patterns generation without coding

Just prepare a simple table tile in your preferred WYSIWYG HTML editor and let the module do the job for you.

* simple to maintain

You can indipendently change the table tile or the code, and everything will go as you would expect.

HTML Examples

Top

Below this paragraph you should see several HTML examples. If you don't see any example, please take a look at the Examples.html file included in this distribution: an image is worth thousands of words (expecially with HTML)!

METHODS

Top

new ( [tile] )

The constructor method generate a HTML::TableTiler object. It accepts one optional tile parameter that can be a reference to a SCALAR content, a path to a file or a filehandle. If you don't pass any tile to the constructor method, a plain tile will be used internally to generate a plain HTML table. A tile must be a valid HTML chunk containing at least one "<tr> ... </tr>" area. See "HTML Examples" or the Examples.html file in order to know more useful details about table tiles.

Examples of constructors:

    $tt = HTML::TableTiler->new( \$tile_scalar );
    $tt = HTML::TableTiler->new( '/path/to/table_tile_file' );
    $tt = HTML::TableTiler->new( *TABLE_TILE_FILEHANDLER );
    $tt = HTML::TableTiler->new(); # default \'<table><tr><td></td></tr></table>'
is_matrix( array_reference )

This method checks if the passed array_reference is a matrix (i.e. an array of arrays). It returns 1 on success and 0 on failure. It is called automatically by the tile_table() method unless you pass a true value as tird argument.

tile_table ( matrix [, mode ] [, checked] )

This method generates a tiled table including the data contained in matrix. The matrix parameter must be a reference to a bidimensional array:

    $matrix=[
               [ 'Balls', 'A470', '250', '2.75' ],
               [ 'Cubes', 'A520', '378', '3.25' ],
               [ 'Cones', 'A665', '186', '2.85' ]
            ];

The mode parameter must be scalar containing one or two literal words representing ROW and COLUMN tiling mode. These are the accepted modes:

H_PULL

The grafic style of each rightmost CELL in the tile will be rightward replicated. This is the default HORIZONTAL tiling mode, so if you don't explicitly assign any other H_* mode, this mode will be used by default.

H_TILE

The grafic style of each ROW in the tile will be rightward replicated.

H_TRIM

The table ROW will be trimmed to the tile ROW, and the surplus data in matrix will be ignored.

V_PULL

The grafic style of each bottommost CELL in the tile will be downward replicated. This is the default VERTICAL tiling mode, so if you don't explicitly assign any other V_* mode, this mode will be used by default.

V_TILE

The grafic style of each COLUMN in the tile will be downward replicated.

V_TRIM

The table COLUMN will be trimmed to the tile COLUMN, and the surplus data in matrix will be ignored.

Examples:

    $tt->TableTiler( \@matrix, "V_TRIM H_TILE" );
    $tt->TableTiler( \@matrix, "V_TILE" ); # default "H_PULL"
    $tt->TableTiler( \@matrix );             # default "H_PULL V_PULL"

Different combinations of tiling modes and tiles can easily produce complex tiled tables. (See "HTML Examples" or the Examples.html file for details.)

A true checked argument avoid the is_matrix method to be internally called.

FUNCTIONS

Top

tile_table ( matrix [, tile [, mode ]] )

If you prefer a function-oriented programming style, you can import or directly use the tile_table() function:

    use HTML::TableTiler qw( tile_table );
    print tile_table( \@matrix, \$tile, "V_TILE" );
    print tile_table( \@matrix );

    # or
    use HTML::TableTiler;
    print HTML::TableTiler::tile_table( \@matrix, \$tile, "V_TILE" );
    print HTML::TableTiler::tile_table( \@matrix);

Note that you have to pass the tile as the optional second parameter, and the mode as the optional third parameter. (See method tile_table() for details).

SEE ALSO

Top

Template::Magic::HTML, that supplies an extended and transparent interface to this module.

SUPPORT and FEEDBACK

Top

If you need support or if you want just to send me some feedback or request, please use this link: http://perl.4pro.net/?HTML::TableTiler.

AUTHOR and COPYRIGHT

Top

© 2002-2004 by Domizio Demichelis.

All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as perl itself.

HTML-TableTiler documentation Contained in the HTML-TableTiler distribution. 
package HTML::TableTiler ;
$VERSION = 1.21 ;
use strict ;

# This file uses the "Perlish" coding style
# please read http://perl.4pro.net/perlish_coding_style.html

; use 5.005
; use Carp
; use HTML::PullParser 1.0
; use IO::Util 1.2
; require Exporter 
; @HTML::TableTiler::ISA = qw| Exporter |
; @HTML::TableTiler::EXPORT_OK = qw| tile_table |

; BEGIN
   { *PULL  = sub () { 'PULL' }
   ; *TILE  = sub () { 'TILE' }
   ; *TRIM  = sub () { 'TRIM' }
   ; *TRUE  = sub () { 1 }
   ; *FALSE = sub () { 0 }
   ; *RESET = sub () { 0 }
   }

; sub new
   { my $c = shift
   ; my $t = shift || \ '<table><tr><td></td></tr></table>'
   ; $t = IO::Util::slurp($t)
          unless ref $t eq 'SCALAR'
   ; $$t or  croak 'The tile content is empty'
   ; my $s = _parse_table($t)
   ; bless $s, $c
   }

; sub _parse_table
   { my ( $content ) = shift
   ; my ( $start
        , $Hrows
        , $end
        )
        = $$content =~ m| ^
                                                  (.*?)                    # start
                                                  ( <TR[^>]*?> .* </TR> )  # Hrows
                                                  (.*)                     # end
                                                  $
                                              |xsi
   ; my ( $p
        , $rows
        , $ignore
        )
   ; $Hrows or croak 'The tile does not contain any "<tr>...</tr>" area'
   ; eval
      { local $SIG{__DIE__}
      ; $p = HTML::PullParser->new( doc   => $Hrows
                                  , start => 'tag, text',
                                  , end   => 'tag, text'
                                  )
      }
   ; if ($@)
      { croak "Problem with the HTML parser: $@"
      }
   ; ( my $ri
     = my $di
     = my $td
     = my $in_tr
     = my $in_td
     = RESET
     )
   ; my $err = sub
                { croak "Unespected HTML tag $_[0] found in the tile"
                }
   ; while ( my $tok = $p->get_token )
      { my ( $tag, $text ) = @$tok
      ; if ( $tag eq 'tr' )
         { ( not $in_tr and not $in_td ) or $err->($text)
         ; $$rows[$ri]{Srow} = $text
         ; $in_tr = TRUE
         }
        elsif ( $tag eq '/tr')
         { ( $in_tr and not $in_td) or $err->($text)
         ; $$rows[$ri++]{Erow} = $text
         ; $in_tr = FALSE
         ; $di    = FALSE
         }
        elsif ( $tag eq 'td' )
         { ($in_tr and not $in_td) or $err->($text)
         ; $$rows[$ri]{cells}[$di]{Scell} = $text
         ; $in_td = TRUE
         }
        elsif ( $tag eq '/td' )
         { ($in_tr and $in_td) or $err->($text)
         ; $$rows[$ri]{cells}[$di++]{Ecell} .= $text
         ; $in_td = FALSE
         ; $td++
         }
        elsif ( $tag !~ m|^/| )
         { ($in_tr and $in_td) or $err->($text)
         ; $$rows[$ri]{cells}[$di]{Scell} .= $text if $in_td
         }
        elsif ( $tag =~ m|^/| )
         { ( $in_tr and $in_td ) or $err->($text)
         ; $$rows[$ri]{cells}[$di]{Ecell} .= $text if $in_td
         }
      }
   ; $td or croak 'The tile does not contain any "<td>...</td>" area'
   ; return { start => $start
            , rows  => $rows
            , end   => $end
            }
   }

; sub is_matrix
   { my ($data_matrix) = shift
   # bi-dimensional array check
   ; foreach my $dr ( @$data_matrix )
     { if ( ref $dr eq 'ARRAY' )
        { foreach my $d ( @$dr )
           { return 0 if ref $d
           }
        }
       else
        { return 0
        }
     }
   ; return 1
   }
   
; sub tile_table
   { my ( $s
        , $data_matrix
        , $tile
        , $mode
        , $checked
        )
   ; if (  length(ref $_[0])             # blessed obj
        && eval { $_[0]->isa(ref $_[0]) }
        )
      { ( $s, $data_matrix, $mode, $checked) = @_
      }
     else
      { ( $data_matrix, $tile, $mode, $checked ) = @_
      ; $s = __PACKAGE__->new($tile)
      ; undef $tile
      }
   
   ; $mode ||= 'H_PULL V_PULL'

   ; $checked
     || is_matrix($data_matrix)
     || croak 'Wrong data matrix content'
   
   # set Hmode and Vmode
   ; my $m = qr/(PULL|TILE|TRIM)/
   ; my ($Hmode) = $mode =~ /\b H_ $m \b/x ; $Hmode ||= PULL
   ; my ($Vmode) = $mode =~ /\b V_ $m \b/x ; $Vmode ||= PULL

   # spread table
   ; my $out = "\n"
   
   ; ROW:
     for ( ( my $dmi
           = my $tmi
           = RESET
           )
         ; $dmi <= $#$data_matrix 
         ; ( $dmi ++
           , $tmi ++
           )
         )
      { if ( $tmi > $#{$s->{rows}} )
         {
           if    ( $Vmode eq PULL )
            { $tmi = $#{$s->{rows}}
            }
           elsif ( $Vmode eq TILE )
            { $tmi = RESET
            }
           elsif ( $Vmode eq TRIM )
           { last ROW
           }
         }
      ; $out .= $s->{rows}[$tmi]{Srow}
              . "\n"
      ; my $data_cells = $$data_matrix[$dmi]
      ; my $html_cells = $$s{rows}[$tmi]{cells}
      
      ; CELL:
        for ( ( my $di
              = my $ti
              = RESET
              )
            ; $di <= $#$data_cells
            ; ( $di ++
              , $ti ++
              )
            )
         { if ( $ti > $#$html_cells )
            {
              if    ( $Hmode eq PULL )
               { $ti = $#$html_cells
               }
              elsif ( $Hmode eq TILE )
               { $ti = RESET
               }
              elsif ( $Hmode eq TRIM )
               { last CELL
               }
            }
         ; $out .= "\t"
                 . $$html_cells[$ti]{Scell}
                 . $$data_cells[$di]
                 . $$html_cells[$ti]{Ecell}
                 . "\n"
         }
      ; $out .= $$s{rows}[$tmi]{Erow}
              . "\n"
      }
   ; return $$s{start}
          . $out
          . $$s{end}
   }

; 1

__END__