NAME

PDF::ReportWriter::Datasource

DESCRIPTION

PDF::ReportWriter::Datasource is a PDF::ReportWriter class that represents a (mmh) data source. Every Datasource class provides all needed information to extract data to be used in the report. The interface it exposes, that obviously can be overloaded with subclasses, is composed of several methods. The most important is the get_data() method.

This class is designed in a way that should be simple to be overloaded, and thus provide alternative classes that provide data for the report in a totally different way.

An example of this concept is given in the PDF::Report::Datasource::DBI class.

USAGE

There is really no usage for this class, because it is autoloaded and invoked automatically by PDF::ReportWriter::Report object when needed. If you really want an example of usage, here it is:

# Create a datasource object
my $my_ds = PDF::ReportWriter::Datasource->new({
	type => 'DBI',
	dsn  => 'DBI:Pg:dbname=pdfrwtest',
	user => 'postgres',
	pass => 'postgres',
});

$my_ds->get_data();

METHODS

new( options )

Creates a new PDF::ReportWriter::Datasource object. options is a hash reference. Its only required key is type, which identifies the correct subclass name (for example, DBI). Every subclass can have its own options that you need to pass in order to make everything work as expected. Typical usage of Datasource class is not through new() constructor, but through xml report definition. Including the following fragment of code in your xml report in the data section, automatically creates needed objects and uses them:

	<report>
	...
	   <data>
	   ...
	   	<datasource name="customer">
			<type>DBI</type>
			<dsn>DBI:Pg:dbname=accounting</dsn>
			<user>postgres</user>
			<pass>postgres</pass>
			<sql>SELECT * FROM customers WHERE id=?</sql>
			<attr>
				<ChopBlanks>1</ChopBlanks>
				<PrintError>1</PrintError>
				<RaiseError>1</RaiseError>
			</attr>
		</datasource>
	   </data>
        ...
	</report>

get_data()

Should be used to provide all actual data records to the report. You can do anything you want with this. A typical use is to connect to a DBI data source and return the result of selectall_arrayref(). Check PDF::ReportWriter::Datasource::DBI for actual code that does this.

The default implementation returns no record. If no datasource is defined in your report, you can directly supply the optional data_records parameter to render_report() method. See PDF::ReportWriter::render_report().

process_data()

It is called automatically just after get_data(), to make additional processing over raw data returned by Datasource. It is meant to allow easy overloading of classes without rewriting of get_data() method. Example: converting all dates to a custom format not supported by underlying database.

Default implementation does nothing.

replace_input_values()

Allows to replace placeholders. Check PDF::ReportWriter::Datasource::DBI.

CUSTOM DATASOURCE CLASSES

The design of PDF::ReportWriter::Datasource allows one to build a custom class that provides alternative behavior for get_data() method.

TODO

Document the replace_input_values() mechanism.

AUTHORS

Cosimo Streppone <cosimo@cpan.org>