NAME
PDFLib::PPS -- PDFLib Personalization Server OO InterfaceSYNOPSIS
use PDFLib::PPS;
my $search_path = "$FindBin::Bin/../data";
my $template = "boilerplate.pdf";
my %data = ("name" => "Victor Kraxi",
"business.title" => "Chief Paper Officer",
"business.address.line1" => "17, Aviation Road",
"business.address.city" => "Paperfield",
"business.telephone.voice" => "phone +1 234 567-89",
"business.telephone.fax" => "fax +1 234 567-98",
"business.email" => "victor\@kraxi.com",
"business.homepage" => "www.kraxi.com"
);
my $pdf = PDFLib::PPS->new(filename => "/tmp/business.pdf",
SearchPath => $search_path,
BlockContainer => $template,
BlockData => \%data);
$pdf->fill_in or die "unable to fill in the block container";DESCRIPTION
PDFLib::PPS is a convenience wrapper/OO interface around the PDFlib Personalization Service. See www.pdflib.com for info about the PPS.
The goal is to be able to associate some key/value pairs with a template (i.e., a "Block Container") and end up with a PDF.
BASIC METHODS
new(...)
The object creation is delegated to PDFLib; see the PDFLib perldoc for details. There are three additional parameters which might be useful: SearchPath (which is then set as the SearchPath parameter), BlockContainer (the PDF document with the named blocks defined within, maybe well thought of as a "template"), and BlockData (a hashref of block-name => block-text pairs).
NB: the block-text specified in BlockData can be text, in which case the fill_in method attempts to use a reasonable encoding, font, textsize, and so forth or it can be a hashref. If a hashref is specified, one key, "text", represents the text for the field, each of the other keys/value pairs will be passed as a key=value option to PDF_fill_textblock. If "encoding" is one of the keys, that encoding will be used instead of whichever encoding PPS.pm had magically selected. (See zapfchar() below for a brief example.)
fill_in()
Shoves BlockData into the BlockContainer specified. Returns undef on error or the string "OK" upon success.
All identically named blocks with the block property "PDFlib:field:type" set to "textflow" will be considered a single textflow block. This is experimental and fraught with peril.
zapfchar(unicode character name)
Return the ASCII character that will produce the unicode character supplied. For instance, to fill in a checkbox block named "GenderMale" with a 16 pt checkmark:
my $checkmark = PDFLib::PPS->zapfchar('CheckMark');
$pdf->block_datum(GenderMale => { text => $checkmark, fontsize => 16 });GET/SET Methods
search_path([new path])
Get/Set the SearchPath parameter.
block_data([data hashref])
Get/Set the BlockData.
block_datum(key, [new value])
Get/Set the named BlockData datum.
block_container([new block container])
Get/Set the BlockContainer.
INTERNAL METHODS
NB: "Objects" here are whatever the PDFlib bindings require in PDF_* subroutines. I suspect that these are not actual objects, but it doesn't really matter.
container([container])
Get/Set the current container "object"
current_page([page])
Get/Set the current page "object"
begin_page_ext()
Calls both PDF_being_page_ext and PDF_fit_pdi_page. The geometry will be adjusted to fit the imported block container.
end_page_ext()
Calls PDF_end_page_ext.
open_pdi_document()
Sets the SearchPath and attempts to open BlockContainer with PDF_open_pdi_document. Returns undef on failure or the container "object" upon success. This "object" is suitable for sending to container(), above.
close_pdi_document()
Calls PDF_close_pdi. Note these subroutines are not identically named.
open_pdi_page(page number)
Calls PDF_open_pdi_page. Returns undef on failure, and the page "object" upon success. This "object" is suitable for sending to current_page(), above.
close_pdi_page()
Calls PDF_close_pdi_page.
number_of_pages()
Returns the number of pages in the container (which must have been set).
block_count()
Returns the number of blocks on the container's current page. Both container and current_page must be set.
block_names()
Returns a list of the block names on the container's current page. Both container and current_page must be set.
font_for_block(block name)
Returns the text string naming the font to be used for the specified block. Block name must exist, container and current_page must be set.
encoding_for_block(block name)
A wicked hack. Returns a string suitable for the last argument in PDF_fill_textblock, so long as the font for the named block is Helvetica or ZapfDingbats. For other fonts it's a crapshoot as yet.
BUGS
No doubt, and only the text fillin method is supported as yet. I only have access to a couple of PDF BlockContainers and this code works reliably for those. Without Acrobat I'm unable to drum up more test cases.
AUTHOR
Kevin Montuori <cpan@mconsultancy.us>
August 2007