PDF::Table

Hello,
I have written a module, tenatively called PDF::Table, for creating
tabular reports in PDF format. It is essentially a utility class for
use with the PDF::API2 module. This module has one core method that
takes a 2D array of data and creates a table layout. You can specify
formatting parameters - things such as font, font color and background
color per column and/or per even/odd row. By default, it also handles
some tedious things automatically, like determining column widths based
on the content of each column and adding as many pages to the pdf as
needed. Any comments are welcome.

Here is the pod:

* NAME
* SYNOPSIS
* DESCRIPTION
* METHODS
o new
o table($pdf, $page_obj, $data, %opts)
o text_block($txtobj,$string,-x => $x, -y => $y, -w =>
$width, -h => $height)
* AUTHOR
* VERSION
* LICENSE
* PLUGS
* SEE ALSO

NAME

PDF::Table -- A utility class for building table layouts in a PDF::API2
object.

SYNOPSIS

use PDF::API2;
use PDF::Table;

my $pdftable = new PDF::Table;
my $pdf = new PDF::API2(-file => "table_of_lorem.pdf");
my $page = $pdf->page;

# some data to layout
my $some_data =[
["1 Lorem ipsum dolor",
"Donec odio neque, faucibus vel",
"consequat quis, tincidunt vel, felis."],
["Nulla euismod sem eget neque.",
"Donec odio neque",
"Sed eu velit."],
... and so on
];

# build the table layout
$pdftable->table(
# required params
$pdf,
$page,
$some_data,
-x => $left_edge_of_table,
-start_y => 500,
-next_y => 700,
-start_h => 300,
-next_h => 500,
# some optional params
-w => 570,
-padding => 5,
-padding_right => 10,
-background_color_odd => "gray",
-background_color_even => "lightblue", #cell background color
for even rows
);

# do other stuff with $pdf
....

DESCRIPTION

This class is a utility for use with the PDF::API2 module from CPAN. It
can be used to display text data in a table layout within the PDF. The
text data must be in a 2d array (such as returned by a DBI statement
handle fetchall_arrayref() call). The PDF::Table will automatically add
as many new pages as necessary to display all of the data. Various
layout properties, such as font, font size, and cell padding and
background color can be specified for each column and/or for even/odd
rows. See the METHODS section.

METHODS

new

Returns an instance of the class. There are no parameters.

table($pdf, $page_obj, $data, %opts)

The main method of this class. Takes a PDF::API2 instance, a page
instance, some data to build the table and formatting options. The
formatting options should be passed as named parameters. This method
will add more pages to the pdf instance as required based on the
formatting options and the amount of data.

The return value is a 3 item list where the first item is the
PDF::API2::Page instance that the table ends on, the second item is the
count of pages that the table spans, and the third item is the y
position of the table bottom.

Example:

($end_page,$pages_spanned, $table_bot_y) = $pdftable->table(
$pdf, # A PDF::API2 instance
$page_to_start_on, # A PDF::API2::Page instance that the
table will start on. Should be a child of the $pdf instance
$data, # 2D arrayref of text strings
-x => $left_edge_of_table,
-start_y => $baseline_of_first_line_on_first_page,
-next_y => $baseline_of_first_line_on_succeeding_pages,
-start_h => $height_on_first_page,
-next_h => $height_on_succeeding_pages,
[-w => 570,] # width of table. technically optional, but
almost always a good idea to use
[-padding => "5",] # cell padding
[-padding_top => "10",] #top cell padding, overides -pad
[-padding_right => "10",] #right cell padding, overides -pad
[-padding_left => "10",] #left padding padding, overides -pad

[-padding_bottom => "10",] #bottom padding, overides -pad
[-border => 1,] # border width, default 1, use 0 for no
border
[-border_color => "red",] # default black
[-font => $pdf->corefont("Helvetica", -encoding =>
"latin1"),] # default font
[-font_size => 12,]
[-font_color_odd => "purple",]
[-font_color_even => "black",]
[-background_color_odd => "gray",] #cell background color for
odd rows
[-background_color_even => "lightblue",] #cell background
color for even rows
[-column_props => $col_props] # see below
)

If the -column_props parameter is used, it should be an arrayref of
hashrefs, with one hashref for each column of the table. Each hashref
can contain any of keys shown here:

$col_props = [
{
width => 100,
justify => "[left|right|center]",
font => $pdf->corefont("Times", -encoding => "latin1"),
font_size => 10
font_color=> "red"
background_color => "yellow",
},
# etc.
];

If the "width" parameter is used for -col_props, it should be
specified for every column and the sum of these should be exacty equal
to the -w parameter, otherwise Bad Things may happen. In cases of a
conflict between column formatting and odd/even row formatting, the
former will oeverride the latter.

text_block($txtobj,$string,-x => $x, -y => $y, -w => $width, -h =>
$height)

Utility method to create a block of text. The block may contain
multiple paragraphs.

Example:

# PDF::API2 objects
my $page = $pdf->page;
my $txt = $page->text;


($width_of_last_line, $ypos_of_last_line, $left_over_text) =
$pdftable->text_block(
$txt,
$text_to_place,
-x => $left_edge_of_block,
-y => $baseline_of_first_line,
-w => $width_of_block,
-h => $height_of_block,
[-lead => $font_size * 1.2 | $distance_between_lines,]
[-parspace => 0 | $extra_distance_between_paragraphs,]
[-align => "left|right|center|justify|fulljustify",]
[-hang => $optional_hanging_indent,]
);


AUTHOR

Daemmon Hughes

VERSION

0.01

LICENSE

Copyright 2005 Daemmon Hughes, portions Copyright 2004 Stone
Environmental Inc. (www.stone-env.com) All Rights Reserved. You may use
and distribute PDF::Table under the same terms as perl itself.

PLUGS

Much of the work on this module was sponsered by Stone Environmental
Inc. (www.stone-env.com).

The text_block() method is a slightly modified copy of the one from
Rick Measham's PDF::API2 tutorial at
http://pdfapi2.sourceforge.net/cgi-bin/view/Main/YourFirstDo cument

SEE ALSO

the PDF::API2 manpage