/ 
PostScript-Report-0.13
River stage zero No dependents
/ PostScript::Report::Builder

NAME

PostScript::Report::Builder - Build a PostScript::Report object

VERSION

This document describes version 0.13 of PostScript::Report::Builder, released November 30, 2013 as part of PostScript-Report version 0.13.

SYNOPSIS

use PostScript::Report ();

my $rpt = PostScript::Report->build(\%report_description);

DESCRIPTION

Because a PostScript::Report involves constructing a number of related objects, it's usually more convenient to pass a description of the report to a builder object.

You can find example reports in the examples directory of this distribution.

The %report_description is a hash with keys as follows:

Report Attributes

Any of the Report attributes listed under "Report Formatting" in PostScript::Report or "Component Formatting" in PostScript::Report may be set by the report description.

Builder Attributes

Any of the attributes listed in "ATTRIBUTES" may be set by the report description when build is called as a class method.

Font Specifications

All fonts used in a report must be defined in a hashref under the fonts key (unless you only want to use the report's default fonts). The keys in this hashref are arbitrary strings, and the values are strings in the form FONTNAME-SIZE.

If you use the same value more than once, then both keys will refer to the same font object. This allows you to use the same font for different purposes, while retaining the ability to substitute a different font for one of those purposes just by changing the fonts hash.

When you set a font or label_font attribute, its value must be one of the keys in the fonts hash.

Example:

fonts => {
  label    => 'Helvetica-6',
  text     => 'Helvetica-9',
},

font       => 'text',
label_font => 'label',

Report Sections

Any of the sections listed under "Report Sections" in PostScript::Report may be defined by the report description. The value is interpreted as follows:

Components are created by hashrefs. Containers are created by arrayrefs.

If the section is a container, the initial container type is chosen like this: If the first value in the arrayref is a hashref, you get an HBox. Otherwise, you get a VBox.

After that, the box types alternate. If you place an arrayref in an HBox, it becomes a VBox. An arrayref in a VBox becomes an HBox.

You can override the box type (or pass parameters to its constructor), by making the first entry in the arrayref a string (the container type) and the second entry a hashref to pass to its constructor. If that hashref contains a _default key, its value becomes the default component class inside this container.

The hashref that represents a Component is simply passed to its constructor, with one exception. If the hash contains the _class key, that value is removed and used as the class name.

Constant Values

As a special case, you can pass a scalar reference as the value for a Component. This creates a constant value. That is,

value => \'Label:',

is equivalent to

value => { _class => 'Constant',  value => 'Label:' },

A Note on Class Names

Anywhere you specify a class name, PostScript::Report:: is automatically prepended to the name you give. To use a class outside that namespace, prefix the class name with =.

There are two exceptions to this:

  1. When you give a hashref as the value of a value attribute, the prefix is PostScript::Report::Value:: instead of just PostScript::Report::.

  2. The report_class is always a complete class name.

Report Columns

The columns key is provided as a shortcut for the common case of a report with column headers and a single-row detail section.

The value should be a hashref with the following keys:

A hashref of parameters to pass to the constructor of the HBox that holds the column headers. Optional.

detail

A hashref of parameters to pass to the constructor of the HBox that forms the detail section. Optional.

data

An arrayref of arrayrefs, one per column. Required. Each arrayref has 4 elements. The first two are the column title and the column width. The third is an optional hashref of parameters for the header component, and the fourth is an optional hashref of parameters for the detail component.

If you don't specify a _class for the header component, it defaults to "default_column_header", and if you don't specify a _class for the detail component, it defaults to "default_column_type".

If you don't specify a value for the header component, it defaults to the column title (as a Constant).

If you don't specify a value for the detail component, it defaults to the next column number. (If you do specify a value, the column number is not incremented.)

This assumes that the page_header is a VBox (or that there is no page_header aside from the column headers).

If you need a more complex layout than this, don't use columns. Instead, define the detail and page_header sections as needed.

Zebra Striping

The stripe and stripe_page keys are provided as a shortcut for the common case of a report with a detail section that cycles through a pattern of background colors.

The value should be a arrayref of colors. The first row uses the first color, the second row uses the second color, and so on (wrapping around to the beginning of the array).

Use stripe_page if you want the pattern to start over on every page, or stripe if you want it to continue from where the previous page left off.

For example,

stripe => [ 1, 0.85 ],

will give every other row a light grey background.

If you need a more complex color scheme, set "detail_background" in PostScript::Report directly.

Note that stripe and stripe_page are not placed inside the columns hash, because they can be used even if you define the detail section manually.

ATTRIBUTES

default_column_header

This is the default component class used for column headers. It defaults to Field.

default_column_type

This is the default component class used for column fields. It defaults to Field.

default_field_type

This is the default component class used when building the report sections. It defaults to Field.

You can temporarily override this by specifying the _default key as a container's parameter.

report_class

This is the class of object that will be constructed. It defaults to PostScript::Report. This must always be a full class name.

METHODS

build

$rpt = $builder->build(\%report_description)
$rpt = PostScript::Report::Builder->build(\%report_description)

This can be called as either an object or class method. When called as a class method, it constructs a temporary object by passing the description to new.

CONFIGURATION AND ENVIRONMENT

PostScript::Report::Builder requires no configuration files or environment variables.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

AUTHOR

Christopher J. Madsen <perl AT cjmweb.net>

Please report any bugs or feature requests to <bug-PostScript-Report AT rt.cpan.org> or through the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=PostScript-Report.

You can follow or contribute to PostScript-Report's development at https://github.com/madsen/postscript-report.

ACKNOWLEDGMENTS

I'd like to thank Micro Technology Services, Inc. http://www.mitsi.com, who sponsored development of PostScript-Report, and fREW Schmidt, who recommended me for the job. It wouldn't have happened without them.

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Christopher J. Madsen.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.