Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PDF::FromHTML::TemplatUser Contributed Perl DocumentPDF::FromHTML::Template(3)

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
       o   "new( [$opts] )"

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

	   o   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.

	   o   openaction

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

	       o   fitbox

	       o   fitheight

	       o   fitpage (default)

	       o   fitwidth

	       o   retain

	   o   openmode

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

	       o   bookmarks

	       o   fullscreen

	       o   none	(default)

	       o   thumbnails

	   o   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:

	       o   CreationDate

	       o   Producer

	       o   ModDate

	       o   Trapped

	   o   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.

       o   "parse( $file )"

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

       o   "parse_xml( $file )"

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

       o   "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.

       o   "write_file(	$filename )"

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

       o   "get_buffer()"

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

       o   "output()"

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

       o   "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:

       o   Audrey Tang

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

       o   Michael Kiwala

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

       o   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).

perl v5.32.1			  2019-10-23	    PDF::FromHTML::Template(3)

NAME | SYNOPSIS | DESCRIPTION | OVERVIEW | METHODS | USAGE | WWW CAVEATS | BUGS | LIMITATIONS | AUTHOR/MAINTAINER | CONTRIBUTORS | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=PDF::FromHTML::Template&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help