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