NAME

  PDFLib::PPS -- PDFLib Personalization Server OO Interface

SYNOPSIS

  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

cpanm PDFLib::PPS

perl -MCPAN -e shell
install PDFLib::PPS