NAME

PDF::Template - PDF::Template

SYNOPSIS

  use PDF::Template

  my $pdf = PDF::Template->new(
     filename => 'some_template.xml',
  );

  $pdf->param(%my_params);

  print "Content/type: application/pdf\n\n", $pdf->get_buffer;

  $pdf->write_file('some_file.pdf');

DESCRIPTION

PDF::Template is a PDF layout system that uses the same data structures as HTML::Template.

OVERVIEW

PDF::Template is a PDF layout system that uses the same data structures as HTML::Template. Unlike HTML::Template, this is a full layout system. This means you will have to describe where each item will be on the page. (This is in contrast to HTML::Template, which adds on to HTML. The layout is determined by the HTML, not HTML::Template.)

PDF::Template uses an XML document as the template. However, the XML is not completely compliant. The only difference (that I'm aware of) is that any node can have any parameter. (This prevents the creation of a DTD.) The reason for this is to allow scoping by parents for parameters used by children. (More on this later.)

Each node in the document corresponds to an object, with each parameter mapping (mostly) 1 to 1 to an object attribute. Parent-child relationships are strictly preserved. Each parent provides a scope (similar to variable scope) to its children. (This is why any node can have any parameter.) If a child needs the value of a parameter and it doesn't have that value as an attribute, it will ask its parent for the value. If the parent doesn't have it, it will ask its parent, and so on.

USAGE

There are a few consistency rules that that every PDF::Template has to follow:

1 The root node is called PDFTEMPLATE
2 There must be at least one PAGEDEF (which does not have to be a direct child of the PDFTEMPLATE node)
3 All rendering elements (include FONT tags) must be within a PAGEDEF node
4 There must be a FONT tag as an ancestor of every TEXTBOX node
5 Within a PAGEDEF, there can only be on HEADER node and one FOOTER node

For more information about each node, please see the POD for that class.

WWW CAVEATS

When taking an HTML page and adding a PDF option, there are a few differences totake into account. The primary one is the idea of pagebreaks. HTML is displayed as a single page, with scrolling. Paper doesn't scroll, so when there should be a new page is something PDF::Template works very hard at determining. It will take into account any header and footer information you've provided, as well as page sizes.

The second is that you have to determine how wide you want your text to be. One of the most common activities is to take a tabular report and covert it to a PDF. In HTML, the browser handles text width for you. Right now, there isn't a TABLE tag (though work is being done on it). So, you have to layout out your TEXTBOX nodes by hand. (See the EXAMPLES for some ideas on this.) That said, it really isn't that hard. TR/TH tags convert to ROW tags easily, and TD tags are basically TEXTBOX tags. Add a few width="20%" (or whatever) and you're fine.

BUGS

None, that I'm aware of.

LIMITATIONS

Currently, the only PDF rendered PDF::Template supports is PDFLib (available at www.pdflib.com). An upcoming release of PDF::Template will also support PDF::API2. Unless you need Unicode support, PDFLib Lite is sufficient (and free). Please see www.pdflib.com for more details.

I am aware that PDFLib will not compile under AIX or Cygwin. These are problems that PDFLib has acknowledged to me.

AUTHOR

Originally written by Dave Ferrance (dave@ferrance.org) Taken over after v0.05 by Rob Kinyon (rob.kinyon@gmail.com)

CONTRIBUTORS

Patches and ideas provided by:

Michael Kiwala
Nathan Byrd

Additionally, there is a mailing list at http://groups-beta.google.com/group/PDFTemplate

COPYRIGHT

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

The full text of the license can be found in the LICENSE file included with this module.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 346:: =back doesn't take any parameters, but you said =back 4
Around line 395:: =back doesn't take any parameters, but you said =back 4