NAME

PDF::ReportWriter::Report

DESCRIPTION

PDF::ReportWriter::Report is a PDF::ReportWriter class that represents a single report. It handles the conversions from/to XML to PDF::ReportWriter correct data structures, and can provide the data to be used in the report. XML::Simple module is used for data structures serialization to XML and restore.

This class is designed in a way that should be simple to be overloaded, and thus provide alternative classes that load reports in a totally different way, or supply data connecting automatically to a DBI DSN, or who knows...

USAGE

The most useful usage for this class is through the PDF::ReportWriter::render_report() call. If you really want an example of usage of standalone Report object, here it is:

        # Create a blank report object
        my $report = PDF::ReportWriter::Report->new();
        my $config;

        # Load XML report definition
        eval { $config = $report->load('/home/cosimo/myreport.xml') };
        if( $@ ) {
            # Incorrect xml file!
            print 'Error in XML report:', $@, "\n";
        }

        # Now save the report object to xml file
        my $ok = $report->save($config);
        my $ok = $report->save($config, 'Copy of report.xml');

METHODS

new( options )

Creates a new PDF::ReportWriter::Report object. options is a hash reference. Its only required key is report, which is the xml filename of the report definition. It is stored inside the object, allowing to later save your report in that filename.

get_data( ds_name )

The only parameter required is the datasource name ds_name. If no data is supplied to the PDF::ReportWriter::render_report() call, this method checks for all available data sources defined in your xml report. They must be included in the data section. Check out the examples.

The main data source that provides the data for report main table must be called detail, or you get an empty report. Additional data sources can be defined, as in the following (fake) example:

    <report>
        ...
        <data>
            ...
            <datasource name="ldapdirectory">
                <hostname>192.168.0.1</hostname>
                <port>389</port>
                <rootdn>o=Users,dc=domain,dc=com</rootdn>
                <binddn>cn=DirectoryManager,dc=domain,dc=com</binddn>
                <password>secret</password>
            </datasource>
            ...
        </data>
        ...
    </report>

get_macros()

Should be used to return all text macros that must be searched and replaced inside the XML content before converting it into the PDF::ReportWriter profile. Example:

    ...
    <!-- Xml report -->
    <report>
        <definition>
            <name>My Report</name>
            <info>
                <Author>${AUTHOR}</Author>
                ...

A corresponding get_macros method should return:

    sub get_macros {
        return { 'AUTHOR' => 'Isaac Asimov' };
    }

The default implementation returns no macro.

load( [xml_file] )

Loads the report definition from xml_file. No, don't be afraid! This is a friendly and nice xml file, not those ugly monsters that populate JavaLand. :-) Return value is an hashref with complete report profile.

        my $report  = PDF::ReportWriter::Report->new();
        my $profile = $report->load('myreport.xml');
        if( ! $profile ) {
                print "Something wrong in the XML?";
        }

save( config [, xml_file ] )

Saves the report profile passed in config parameter (as a hashref) to the file defined in new() or to xml_file if supplied.

The result won't be exactly equal to the source xml file, but should be equivalent when loading the data structures to build your final report.

CUSTOM REPORT CLASSES

The design of PDF::ReportWriter::Report allows one to build a custom class that provides alternative behavior for load() and get_data() methods.

load() method can do anything, but it must return a complete report data structure to be fed into PDF::ReportWriter object. That consists into several hashrefs:

definition

All high-level report properties, such as paper, destination, ...

page

Page header and footer list of cells. See xml report samples in the examples folder.

data

The main section which defines fields and groups. Check out the examples and use Data::Dumper on results of load() method. Sorry. :-)

TODO

Complete documentation?

AUTHORS

Dan <dan@entropy.homelinux.org>

Cosimo Streppone <cosimo@cpan.org>

Other cool things you should know about:

This module is part of an umbrella project, 'Axis Not Evil', which aims to make Rapid Application Development of database apps using open-source tools a reality. The project includes:

Gtk2::Ex::DBI - forms

Gtk2::Ex::Datasheet::DBI - datasheets

PDF::ReportWriter - reports

All the above modules are available via cpan, or for more information, screenshots, etc, see: http://entropy.homelinux.org/axis_not_evil

cpanm PDF::ReportWriter

perl -MCPAN -e shell
install PDF::ReportWriter