NAME

Report::Porf::Framework

Framework to create/configure Reports for any output format.

Part of Perl Open Report Framework (Porf).

VERSION

This documentation refers to version 2.001 of Report::Porf::Framework

All subs are no longer camel cased, so update your scripts, please. A list for conversion can be find in Report/Porf/rename_list.pl

SYNOPSIS

Structure Of A Report

Report
  Table
    Line (Conatining data of data row)
      Cell

*============+============+============*  # Bold separator line
|   Prename  |   Surname  |     Age    |  # The header line
*------------+------------+------------*  # Separator line
| Vorname 1  | <a cell>   | 7.69230769 |  # A data line with <cell>s
| Vorname 2  | Name 2     | 15.3846153 |
| Vorname 3  | Name 3     | 23.0769230 |
| Vorname 4  | Name 4     | 30.7692307 |
*============+============+============*

Using Auto Configure

use Report::Porf qw(:all);

auto_report(\@data);        # prints to STDOUT
auto_report(\@data, $file); # writes into $file

auto_report(\@data, $file, -format => 'html');
auto_report(\@data, -file => $file, -format => 'html', -max_rows => 13);

\@data has to be a list of hashes or arrays. If $file is a filename (as string), then ending of filename defines format of created table.

Filehandles don't know the filename, so format has to be select explicit in this case.

-max_rows defines maximum rows to print out. In case of printing out at STDOUT there is a default max_rows as set to 10 rows. That makes live easy for debugging.

create And Configure Report Explicit

my $report_frame_work = Report::Porf::Framework::get();
my $report            = $report_frame_work->create_report($format);

# $report->set_verbose(3); # uncomment to see infos about configuring phase

Current supported formats:

HTML
Text
Csv

Configure Report

After creation a report has to be configured.

Call configure_column(%options) to configure a report. Following options are available:

Layout

-header  -h   constant: Text
-align   -a   constant: (left|center|right)
                        (l   |   c  |    r)
-width   -w   constant: integer
-format  -f   constant: string for sprintf
-color   -c   constant / sub {...}

The sub {...} makes conditional coloring easy possible.

Value Manipulation

-default_value        -def_val      -dv   constant: default value
-escape_special_chars -esc_spec_chr -esc  constant: 1 or 0

Use default_cell_value if value is undef or ''.

To switch off special value escaping use

escape_special_chars => 0

As next, access to the value has to be defined. There are 4 alternatives to get the value of a cell depending of type (array, hash, object).

GetValue Alternative 1 --- ARRAY

my $prename = 1;
my $surname = 2;
my $age     = 3;

$report->configure_column(-header => 'Prename', -value_indexed => $prename ); # long
$report->conf_col        (-h      => 'Surname', -val_idx       => $surname ); # short
$report->cc             (-h      => 'Age',     -vi            => $age     ); # minimal

GetValue Alternative 2 --- HASH

$report->configure_column(-header => 'Prename', -value_named => 'Prename' ); # long
$report->conf_col        (-h      => 'Surname', -val_nam     => 'Surname' ); # short
$report->cc             (-h      => 'Age',     -vn          => 'Age'     ); # minimal

GetValue Alternative 3 --- OBJECT

$report->configure_column(-header => 'Prename', -value_object => 'get_prename()'); # long
$report->conf_col        (-h      => 'Surname', -val_obj      => 'get_surname()'); # short
$report->cc             (-h      => 'Age',     -vo           => 'get_age()'    ); # minimal

GetValue Alternative 4 --- Free

$report->configure_column(-h => 'Prename',  -value =>    '"Dr. " . $_[0]->{Surname}'    );
$report->conf_col        (-h => 'Surname',    -val => sub { return $_[0]->{Prename}; }; );
$report->cc             (-h => 'Age (Months)', -v =>     '(12.0 * $_[0]->get_age())'    );

When All Columns Are Configured

$report->configure_complete(); 

Write Table Out Into File

$report->write_all($person_rows, $out_file_name);

You can also put out single rows or single cells or start actions to do that. [Needs to be explained more]

In "Report/Porf/examples" subdir you can find more examples.

Details

Here are the details for those, who want to modify an existing or create a new ReportConfigurator. It's actually not complete. See *ReportConfigurator.pm for more.

Report Attributes

There a following attributes of report, that can used by get*/Set*

FileStart
  PageStart
    TableStart
      *============+====  # BoldSeparatorLine
      |   Prename  | ...  # HeaderRowStart HeaderStart <HeaderText> HeaderEnd ... HeaderRowEnd
      *------------+----  # SeparatorLine
      | Vorname 1  | ...  # RowStart       CellStart   <CellValue>  CellEnd   ... RowEnd
      | ...        | ...  # ...
      *============+====  # BoldSeparatorLine
    TableEnd
  PageEnd
FileEnd

To be continued...

LICENSE AND COPYRIGHT

Copyright (c) 2014 by Ralf Peine, Germany. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.6.0 or, at your option, any later version of Perl 5 you may have available.

DISCLAIMER OF WARRANTY

This library is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

cpanm Report::Porf

perl -MCPAN -e shell
install Report::Porf