NAME
PDF::ReportWriter
SYNOPSIS
use PDF::ReportWriter;
my $fields = [ { name => "Company", percent => 85, font_size => 12, align => "left" }, { name => "Amount", percent => 15, font_size => 12, align => "right", aggregate_function => "sum", type => "currency" } ];
my $group = [ { name => "WeekOfMonth", data_column => 2, header => [ percent => 100, font_size => 12, align => "right", text => "Payments for week ?" ] footer => [ percent => 85, font_size => 12, align => "right", text => "Total for week ?" ], [ percent => 15, font_size => 12, align => "right", aggregate_source => 1, text => "WeekOfMonth", type => "currency" ] } ];
my $report_def = { destination => "cheques.pdf", paper => "A4", orientation => "portrait", font_list => [ "Times", "Courier" ], default_font => "Times", default_font_size => 12, x_margin => 100 * mm, y_margin => 100 * mm };
my $report = PDF::ReportWriter->new($report_def);
my $records = $dbh->selectall_arrayref( "select Company, round(Amount, 2) as Amount, case when date_format(DateReceived, '%d') between 1 and 7 then 1 when date_format(DateReceived, '%d') between 8 and 14 then 2 when date_format(DateReceived, '%d') between 15 and 21 then 3 when date_format(DateReceived, '%d') between 22 and 28 then 4 else 5 end as WeekOfMonth, date_format(DateReceived, '%W, %e %b %Y') as FullDate, 1 as LotOfOnes from Cheques where ( DateReceived between '$lower_date' and '$upper_date' ) and ( Amount is not null and Amount!=0 ) order by DateReceived");
my $data = { max_font_size => 12, cell_borders => 1, no_field_headers => 1, fields => $fields, groups => $groups, data_array => $records };
$report->render_data($data);
$report->save;
system("gpdf cheques.pdf &");
DESCRIPTION
PDF::ReportWriter is designed to simplify the task of creating high-quality business reports, for archiving or printing.
All objects are rendered in cells which are defined as a percentage of the available width ( ie similar to HTML tables ).
FIELD DEFINITIONS
A field definition can have the following attributes
name
The 'name' is used when rendering field headers, which happens whenever a new group or page is started. You can disable rendering of field headers by setting no_field_headers in your data definition ( see above example ).
percent
The width of the field, as a percentage of the total available width. The actual width will depend on the paper definition ( size and orientation ) and the x_margin in your report_definition.
font
The font to use. In most cases, you would set up a report-wide default_font. Only use this setting to override the default.
font_size
The font size. Nothing special here...
align
Possible values are "left", "right" and "centre". Note the spelling of "centre". I'm Australian.
aggregate_function
Possible values are "sum" and "count". Setting this attribute will make PDF::ReportWriter carry out the selected function and store the results ( attached to the field ) for later use in group footers.
type
The only possible value currrently is "currency".
GROUP DEFINITIONS
Groups have the following attributes:
name
The name is used to identify which value to use in rendering aggregate functions ( see aggregate_source, below ). Also, a special name, "GrandTotals" will cause PDF::ReportWriter to fetch *Grand* totals instead of group totals. This negates the need to have an extra column of data in your data_array with all the same value ... which is the only other way I can see of 'cleanly' getting GrandTotal functionality.
data_column
The data_column refers to the column ( starting at 0 ) of the data_array that you want to group on.
header / footer
Group headers and footers are defined in a similar way to field definitions ( and rendered by the same code ). The difference is that the cell definition is contained in the 'header' and 'footer' hashes, ie the header and footer hashes resemble a field hash. Consequently, most attributes that work for field cells also work for group cells. Additional attributes in the header and footer hashes are:
aggregate_source
This is used to retrieve the results of an aggregate_function ( see above ). *** NOTE *** You MUST ( currently ) define the 'text' of a cell as the group's *name* for this to work properly. I'm working on removing thie requirement.
REPORT DEFINITION
Possible attributes for the report defintion are:
destination
The path to the destination ( the pdf that you want to create ).
paper
The only paper types currently supported are A4 and Letter. And I haven't tested Letter...
orientation
portrait or landscape
font_list
An array of font names ( from the corefonts supported by PDF::API2 ) to set up. When you include a font 'family', a range of fonts ( roman, italic, bold, etc ) are created.
default_font
The name of the font type ( from the above list ) to use as a default ( ie if one isn't set up for a cell ).
default_font_size
The default font size to use if one isn't set up for a cell.
x_margin
The amount of space ( left and right ) to leave as a margin for the report.
y_margin
The amount of space ( top and bottom ) to leave as a margin for the report.
DATA DEFINITION
The data definition wraps up most of the previous definitions, apart from the report definition. My goal ( with a future release ) is to support unlimited 'sections', which you'll be able to achieve by passing new data definitions and calling the 'render' method. Currently this does not work, but should not take too much to get it going.
Attributes for the data definition:
max_font_size
This is used to calculate the required height of each row. I'm considering writing something to figure this out automatically, but for now you'll have to set this value.
cell_borders
Whether to render cell borders or not.
no_field_headers
Set to disable rendering field headers when beginning a new page or group.
fields
This is your field definition hash, from above.
groups
This is your group definition hash, from above.
data_array
This is the data to render.
METHODS
new ( report_definition )
Object constructor. Pass the report definition in.
render_data ( data_definition )
Renders the data passed in. Currently I've only tested with a single data_definition being passed and rendered, but the goal ( with a future release ) is to support rendering multiple data definitions in a single report.
save
Saves the pdf file ( in the location specified in the report definition ).
AUTHORS
Dan <dan@entropy.homelinux.org>