NAME

PDF::Boxer - Create PDFs from a simple box markup language.

VERSION

version 0.004

SYNOPSIS

$pdfml = <<'__EOP__';
<column max_width="595" max_height="842">
  <column border_color="blue" border="2">
    <row>
      <image src="t/lecstor.gif" align="center" valign="center" padding="10" scale="60" />
      <column grow="1" padding="10 10 10 0">
        <text padding="3" align="right" size="20">
          Lecstor Pty Ltd
        </text>
        <text padding="3" align="right" size="14">
          123 Example St, Somewhere, Qld 4879
        </text>
      </column>
    </row>
    <row padding="15 0">
      <text padding="20" size="14">
        Mr G Client
        Shop 2 Some Centre, Retail Rd
        Somewhere, NSW 2000
      </text>
      <column padding="20" border_color="red" grow="1">
        <text size="16" align="right" font="Helvetica-Bold">
          Tax Invoice No. 123
        </text>
        <text size="14" align="right">
          Issued 01/01/2011
        </text>
        <text size="14" align="right" font="Helvetica-Bold">
          Due 14/01/2011
        </text>
      </column>
    </row>
  </column>
  <grid padding="10">
    <row font="Helvetica-Bold" padding="0">
      <text align="center" padding="0 10">Name</text>
      <text grow="1" align="center" padding="0 10">Description</text>
      <text padding="0 10" align="center">GST Amount</text>
      <text padding="0 10" align="center">Payable Amount</text>
    </row>
    <row margin="10 0 0 0">
      <text padding="0 5">Web Services</text>
      <text name="ItemText2" grow="1" padding="0 5">
        a long description which needs to be wrapped to fit in the box
      </text>
      <text padding="0 5" align="right">$9999.99</text>
      <text padding="0 5" align="right">$99999.99</text>
    </row>
  </grid>
</column>
__EOP__

$parser = PDF::Boxer::SpecParser->new;
$spec = $parser->parse($pdfml);

$boxer = PDF::Boxer->new( doc => { file => 'test_invoice.pdf' } );

$boxer->add_to_pdf($spec);
$boxer->finish;

DESCRIPTION

PDF::Boxer enables the creation of pdf documents using rows, columns, and grids for layout. An xml styled document is used to specify the contents of the document and is parsed into a block of data by PDF::Boxer::SpecParser and passed to PDF::Boxer

Suggestion: Use Template to dynamically create your PDFML template.

METHODS

add_to_pdf

$boxer->add_to_pdf($spec);

Coverts markup to PDF.

finish

Writes the generated PDF to the file specified in the call to new.

register_box

each named element is added to an internal register upon creation.

box_lookup

$boxer->box_lookup('elementName');

get an element from the register.

MARKUP

For a single page document the parent element may be a row, column, or grid. Multiple pages can be generated by wrapping more than one of these elements with a doc element.

ELEMENTS

column

a column stacks elements vertically. Each element will be as wide as the column's content space. If one or more children have the "grow" attribute set then they will be stretched vertically to fill the column.

row

a row places it's children horizontally. If one or more children have the "grow" attribute set then they will be stretched horizontally to fill the row.

grid

a grid is a column with rows for children. The width of the rows' child elements are locked vertically (like an html table).

You can now set the hborder and/or vborder attributes an a grid to display gridlines.

eg <grid hborder="1" vborder="1">

text

the text element contains.. text! Text is wrapped to fith the width of it's container if necessary.

image

the image element places an image in the PDF.. whoda thunkit, eh? the image can be scaled to a percentage of it's original size.

ATTRIBUTES

align

align="right"

align right or center instead of the default left.

background

background="#FF0000"

background is set as a hexadecimal color.

border_color

border_color="#FF0000"

border_color is set as a hexadecimal color.

font

grow

when set to true, the element will expand to take up any available space.

margin, padding, border

size set in pixels as a string for top, right, bottom, left. eg: margin="5 10 15 20"; top = 5, right = 10, bottom = 15, left = 20. margin="5 10"; top = 5, right = 10, bottom = 5, left = 10.

margin is space outside the border. padding is space inside the border. border IS the border..

name

I use this for debugging mostly. It can be used to get an element object via the box_lookup method.

BUGS

positioning of elements not pixel perfect. eg. in a column the bottom of one child overlaps the top of the next by 1 pixel.

TODO

paging

- enable a single element to be nominated for paging so if it's content is too large to fit on a page it is continued on the next page.

- enable elements to be marked as first or last page only.

SEE ALSO

• PDF::Boxer::Content::Box

• PDF::Boxer::Content::Row

• PDF::Boxer::Content::Column

• PDF::Boxer::Content::Grid

• PDF::Boxer::Content::Text

• PDF::Boxer::Content::Image

AUTHOR

Jason Galea <lecstor@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Jason Galea.

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

cpanm PDF::Boxer

perl -MCPAN -e shell
install PDF::Boxer