NAME

       PDF::FromHTML::Template - PDF::FromHTML::Template

SYNOPSIS

         use PDF::FromHTML::Template;

         my $pdf = PDF::FromHTML::Template->new({
            file => 'some_template.xml',
         });

         $pdf->param(%my_params);

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

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

DESCRIPTION

       NOTE: This is a fork of PDF::Template 0.30, originally released by Rob Kinyon, but (as of
       September 11, 2006) currently not available on CPAN.  Use of this module outside
       PDF::FromHTML is not advised.

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

OVERVIEW

       PDF::FromHTML::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::Templateut is determined by the HTML, not
       HTML::Template.)

       PDF::FromHTML::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.

METHODS

       •   "new( [$opts] )"

           This will create a new instance of PDF::FromHTML::Template. $opts is an optional
           hashref that can contain the following parameters:

           •   file

               This is either the name of the file or the filehandle of the open file. If it is
               present, "parse()" will be called upon that filename/filehandle. Otherwise, after
               new() is called, you will have to call "parse()" yourself.

               filename is a synonym for file.

           •   openaction

               This is the action that the PDF reader will take when it opens this file. The
               valid values are:

               •   fitbox

               •   fitheight

               •   fitpage (default)

               •   fitwidth

               •   retain

           •   openmode

               This is the mode that the PDF reader will use when it opens this file. The valid
               values are:

               •   bookmarks

               •   fullscreen

               •   none (default)

               •   thumbnails

           •   info

               This is a hashref of information that you wish to have the PDF retain as metadata.
               If this is not present, both Author and Creator will be set to
               PDF::FromHTML::Template.

               The following keys are not supported:

               •   CreationDate

               •   Producer

               •   ModDate

               •   Trapped

           •   pdf_encoding

               This is the encoding that the template is in. It defaults to the host encoding.
               This is different from the encoding parameter for the pdftemplate tag.

       •   "parse( $file )"

           This will parse the XML template into the appropriate datastructure(s) needed for
           PDF::FromHTML::Template to function.

       •   "parse_xml( $file )"

           This is a deprecated synonym for "parse()".

       •   "param( key =" value, [ key => value, ... ] )>

           This will set the parameters that PDF::FromHTML::Template will use to merge the
           template with. This method is identical to the HTML::Template or Template Toolkit
           method of the same name.

       •   "write_file( $filename )"

           This will write the rendered PDF to the file specified in $filename.

       •   "get_buffer()"

           This will return the rendered PDF stringified in a form appropriate for returning over
           an HTTP connection.

       •   "output()"

           This is a synonym for "get_buffer()" provided for HTML::Template compatibility.

       •   "register( ... )"

           XXX

USAGE

       There are a few consistency rules that that every PDF::FromHTML::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 one 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 to take 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::FromHTML::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 renderer PDF::FromHTML::Template supports is PDFlib (available at
       www.pdflib.com). The next release of PDF::FromHTML::Template will also support PDF::API2.
       Unless you need Unicode support, PDFlib Lite is sufficient (and free). Please see
       <http://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/MAINTAINER

       Originally written by Dave Ferrance (dave@ferrance.org)

       Taken over after v0.05 by Rob Kinyon (rob.kinyon@iinteractive.com)

CONTRIBUTORS

       Patches and ideas provided by:

       •   Audrey Tang

           Provided the impetus to move to PDF::Writer (which she also wrote).

       •   Michael Kiwala

           Aided in the design and testing of the transition from Dave Ferrance's version.

       •   Nathan Byrd

           Provided nearly all the initial doublebyte expertise.

       Additionally, there is a mailing list at <http://groups.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.

SEE ALSO

       perl(1).