45
232
Chapter 10: Variable Data and Blocks
next step other objects which are partially contained in the detected rectangle will be
added to the selected area, and so on. The final area will be used as the basis for the gen-
erated block rectangle. The end result is that the Click Object feature will try to select
complete graphics, and not only individual lines.
The Click Object feature isn’t perfect: it will not always select what you want, depend-
ing on the nature of the page content. Keep in mind that this feature is only intended as
a positioning aid for quickly creating block rectangles.
Automatically detecting font properties. The PDFlib Block plugin can analyze the un-
derlying font which is present at the location where a block is positioned, and can auto-
matically fill in the corresponding properties of the block:
fontname, fontsize, fillcolor, charspacing, horizscaling, wordspacing,
textrendering, textrise
Since automatic detection of font properties can result in undesired behavior when the
background shall be ignored, it can be activated or deactivated using PDFlib Blocks, Detect
underlying font and color. By default this feature is turned off.
Locking blocks. Blocks can be locked to protect them against accidentally moving, re-
sizing, or deleting them. With the block tool active, select the block and choose Lock
from its context menu. While a block is locked you cannot move, resize, or delete it, nor
display its properties dialog.
10.3.2 Editing Block Properties
When you create a new block, double-click an existing one, or choose Properties from a
block’s context menu, the properties dialog will appear where you can edit all settings
related to the selected block (see Figure 10.1). As detailed in Section 10.5, »Standard Prop-
erties for Automated Processing«, page 240, there are several types of properties:
>Name, type, description, and the properties in the General tab apply to all blocks.
>Properties in the Text, Image, and PDF tabs apply only to the respective block type.
Only the tab corresponding to the block’s type will be active, while the other tabs are
inactive.
>If a block of type Text has the textflow property set to true, another tab called Textflow
will appear with Textflow-related settings.
>If a block of type Text has the textflow property set to true, and the hortabmethod
property in the Textflow tab is set to ruler, still another panel called Tabs will appear
where you can edit tabulator settings.
>Properties in the Custom tab can be defined by the user, and apply to any block type.
To change a property’s value enter the desired number or string in the property’s input
area (e.g. linewidth), choose a value from a drop-down list (e.g. fontname, fitmethod), or
select a color value or file name by clicking the »...« button at the right-hand side of the
dialog (e.g. backgroundcolor). For the fontname property you can either choose from the
list of fonts installed on the system, or type a custom font name. Regardless of the
method for entering a font name, the font must be available on the system where the
blocks will be filled with the PDFlib Personalization Server.
When you are done editing properties, click OK to close the properties dialog. The
properties just defined will be stored in the PDF file as part of the block definition.
44
10.3 Using the PDFlib Block Plugin to create Blocks 233
Stacked blocks. Overlapping blocks can be difficult to select since clicking an area with
the mouse will always select the topmost block. In such a situation the Choose Block en-
try in the context menu can be used to select one of the blocks by name. As soon as a
block has been selected the next action (e.g. double-click) within its area will not affect
other blocks, but only the selected one. This way block properties can easily be edited
even for blocks which are partially or completely covered by other blocks.
Using and restoring default properties. In order to save some amount of typing and
clicking, the block tool will remember the property values which have been entered into
the previous block’s properties dialog. These values will be reused when you create a
new block. Of course you can override these values with different ones at any time.
Pressing the Reset All button in the properties dialog will reset most block properties
to their respective defaults. However, the following items will remain unmodified:
>the Name, Type, Rect, and Description properties
>all custom properties.
Shared properties. By holding the Shift key and using the block tool to select multiple
blocks you can select an arbitrary number of blocks on a page. Double-clicking one of
the selected blocks or pressing the Enter key will display the properties dialog which
now applies to all selected blocks. However, since not all properties can be shared
among multiple blocks, only a subset of all properties will be available for editing. Sec-
tion 10.5, »Standard Properties for Automated Processing«, page 240, details which
properties can be shared among multiple blocks. Custom properties cannot be shared.
10.3.3 Copying Blocks between Pages and Documents
The Block plugin offers several methods for moving and copying blocks within the cur-
rent page, the current document, or other documents:
>move or copy blocks by dragging them with the mouse, or pasting blocks to another
page or open document
>duplicate blocks on one or more pages of the same document
>export blocks to a new file (with empty pages) or to an existing document (apply the
blocks to existing pages)
>import blocks from other documents
In order to update the page contents while maintaining block definitions you can re-
place the underlying page(s) while keeping the blocks. Use Document, Replace Pages... .
Moving and copying blocks. You can relocate blocks or create copies of blocks by se-
lecting one or more blocks and dragging them to a new location while pressing the Ctrl
key (on Windows) or Alt key (on the Mac). The mouse cursor will change while the key is
pressed. A copied block will have the same properties as the original block, with the ex-
ception of its name and position which will automatically be changed.
You can also use copy/paste to copy blocks to another location on the same page, to
another page in the same document, or to another document which is currently open in
Acrobat:
>Activate the block tool and select the blocks you want to copy.
>Use Ctrl-C (on Windows) or Cmd-C (on the Mac) or Edit, Copy to copy the selected
blocks to the clipboard.
45
234
Chapter 10: Variable Data and Blocks
>Use Ctrl-V (on Windows) or Cmd-V (on the Mac) or Edit, Paste to paste the blocks
which are currently in the clipboard.
Duplicating blocks on other pages. You can create duplicates of one or more blocks on
an arbitrary number of pages in the current document simultaneously:
>Activate the block tool and select the blocks you want to duplicate.
>Choose Import and Export, Duplicate... from the PDFlib Blocks menu or the context
menu.
>Choose which blocks to duplicate (selected blocks or all on the page) and the range of
target pages where you want duplicates of the blocks.
Exporting and importing blocks. Using the export/import feature for blocks it is possi-
ble to share the block definitions on a single page or all blocks in a document among
multiple PDF files. This is useful for updating the page contents while maintaining ex-
isting block definitions. To export block definitions to a separate file proceed as follows:
>Activate the block tool and Select the blocks you want to export.
>Choose Import and Export, Export... from the PDFlib Blocks menu or the context menu.
Enter the page range and a file name for the file containing the block definitions.
You can import block definitions via PDFlib Blocks, Import and Export, Import... . Upon im-
porting blocks you can choose whether to apply the imported blocks to all pages in the
document, or only to a page range. If more than one page is selected the block defini-
tions will be copied unmodified to the pages. If there are more pages in the target range
than in the imported block definition file you can use the Repeate Template checkbox. If
it is enabled the sequence of blocks in the imported file will be repeated in the current
document until the end of the document is reached.
Copying blocks to another document upon export. When exporting blocks you can
immediately apply them to the pages in another document, thereby propagating the
blocks from one document to another. In order to do so choose an existing document to
export the blocks to. If you activate the checkbox Delete existing blocks all blocks which
may be present in the target document will be deleted before copying the new blocks
into the document.
10.3.4 Converting PDF Form Fields to PDFlib Blocks
As an alternative to creating PDFlib blocks manually you can automatically convert PDF
form fields to blocks. This is especially convenient if you have complicated PDF forms
which you want to fill automatically with the PDFlib Personalization Server, or need to
convert a large number of existing PDF forms for automated filling. In order to convert
all form fields on a page to PDFlib blocks choose PDFlib Blocks, Convert Form Fields, Current
Page. To convert all form fields in a document choose All Pages instead. Finally, you can
convert only selected form fields (choose Acrobat’s Form Tool or the Select Object Tool
to select form fields) with Selected Form Fields.
Form field conversion details. Automatic form field conversion will convert form
fields of the types selected in the PDFlib Blocks, Convert Form Fields, Conversion Options...
dialog to blocks of type Text. By default all form field types will be converted. Attributes
of the converted fields will be transformed to the corresponding block properties ac-
cording to Table 10.2.
62
10.3 Using the PDFlib Block Plugin to create Blocks 235
Multiple form fields with the same name. Multiple form fields on the same page are
allowed to have the same name, while block names must be unique on a page. When
converting form fields to blocks a numerical suffix will therefore be added to the name
of generated blocks in order to create unique block names (see also »Associating form
fields with corresponding blocks«, page 236).
Note that due to a problem in Acrobat the field attributes of form fields with the
same names are not reported correctly. If multiple fields have the same name, but dif-
ferent attributes these differences will not be reflected in the generated blocks. The Con-
version process will issue a warning in this case and provide the names of affected form
fields. In this case you should carefully check the properties in the generated blocks.
Table 10.2 Conversion of PDF form fields to PDFlib blocks
PDF form field attribute...
...will be converted to the PDFlib block property
all fields
Position
General, Rect
Name
General, Name
Tooltip
General, Description
Appearance, Text, Font
Text, fontname
Appearance, Text, Font Size
Text, fontsize; auto font size will be converted to a fixed font size of 2/3 of the
block height, and the fitmethod will be set to auto. For multi-line fields/blocks
this combination will automatically result in a suitable font size which may be
smaller than the initial value of 2/3 of the block height.
Appearance, Text, Text Color
Text, strokecolor; Text, fillcolor
Appearance, Border, Border Color
General, bordercolor
Appearance, Border, Fill Color
General, backgroundcolor
Appearance, Border, Line Thickness
General, linewidth: Thin=1, Medium=2, Thick=3
General, Common Properties, Form
Field
General, Status: Visible=active, Hidden=ignore, Visible but doesn’t print=ignore,
Hidden but printable=active
General, Common Properties, Orien-
tation
General, orientate: 0=north, 90=west, 180=south, 270=east
text fields
Options, Default Value
Text, defaulttext
Options, Alignment
General, position: Left={left center}, Center={center center}, Right={right center}
Options, Multi-line
Text, textflow: checked=true, unchecked=false
radio buttons and check boxes
If »Check box/Button is checked by
default« is selected: Options, Check
Box Style or Options, Button Style
Text, defaulttext: Check=4, Circle=l, Cross=8, Diamond=u, Square=n, Star=H
(these characters represent the respective symbols in the ZapfDingbats font)
list boxes and combo boxes
Options, Selected (default) item
Text, defaulttext
buttons
Options, Icon and Label, Label
Text, defaulttext
49
236
Chapter 10: Variable Data and Blocks
Associating form fields with corresponding blocks. Since the form field names will be
modified when converting multiple fields with the same name (e.g. radio buttons) it is
difficult to reliably identify the block which corresponds to a particular form field. This
is especially important when using an FDF or XFDF file as the source for filling blocks
such that the final result resembles the filled form.
In order to solve this problem the AcroFormConversion plugin will record details
about the original form field as custom properties when creating the corresponding
block. Table 10.3 details the custom properties which can be used to reliably identify the
blocks; all properties have type string.
Binding blocks to the corresponding form fields. In order to keep PDF form fields and
the generated PDFlib blocks synchronized, the generated blocks can be bound to the cor-
responding form fields. This means that the block tool will internally maintain the rela-
tionship of form fields and blocks. When the conversion process is activated again,
bound blocks will be updated to reflect the attributes of the corresponding PDF form
fields. Bound blocks are useful to avoid duplicate work: when a form is updated for in-
teractive use, the corresponding blocks can automatically be updated, too.
If you do not want to keep the converted form fields after blocks have been generat-
ed you can choose the option Delete converted Form Fields in the PDFlib Blocks, Convert
Form Fields, Conversion Options... dialog. This option will permanently remove the form
fields after the conversion process. Any actions (e.g., JavaScript) associated with the af-
fected fields will also be removed from the document.
Batch conversion. If you have many PDF documents with form fields that you want to
convert to PDFlib blocks you can automatically process an arbitrary number of docu-
ments using the batch conversion feature. The batch processing dialog is available via
PDFlib Blocks, Convert Form Fields, Batch conversion...:
>The input files can be selected individually; alternatively the full contents of a folder
can be processed.
>The output files can be written to the same folder where the input files are, or to a
different folder. The output files can receive a prefix to their name in order to distin-
guish them from the input files.
>When processing a large number of documents it is recommended to specify a log
file. After the conversion it will contain a full list of processed files as well as details
regarding the result of each conversion along with possible error messages.
During the conversion process the converted PDF documents will be visible in Acrobat,
but you cannot use any of Acrobat’s menu functions or tools.
Table 10.3 Custom properties for identifying the original form field corresponding to the block
custom property
meaning
PDFlib:field:name
Fully qualified name of the form field
PDFlib:field:pagenumber
Page number (as a string) in the original document where the form field was located
PDFlib:field:type
Type of the form field; one of pushbutton, checkbox, radiobutton, listbox, combobox,
textfield, signature
PDFlib:field:value
(Only for type=checkbox) Export value of the form field
44
10.4 Filling PDFlib Blocks with PPS 237
10.4 Filling PDFlib Blocks with PPS
Coordinate systems. The coordinates describing a block reference the PDF default co-
ordinate system. When the page containing the block is placed on the output page, sev-
eral positioning and scaling options may be supplied to PDF_fit_pdi_page( ). These pa-
rameters are taken into account when the block is being processed. This makes it
possible to place a template page on the output page multiply, every time filling its
blocks with data. For example, a business card template may be placed four times on an
imposition sheet. The block functions will take care of the coordinate system transfor-
mations, and correctly place the text for all blocks in all invocations of the page. The
only requirement is that the client must place the page and then process all blocks on
the placed page. Then the page can be placed again at a different location on the output
page, followed by more block processing operations referring to the new position, and
so on.
Note The Block plugin will display the block coordinates differently from what is stored in the PDF
file. The plugin uses Acrobat’s convention which has the coordinate origin in the upper left cor-
ner of the page, while the internal coordinates (those stored in the block) use PDF’s convention
of having the origin at the lower left corner of the page.
Simple example: adding variable text to a template. Adding dynamic text to a PDF
template is a very common task. The following code fragment will open a page in an in-
put PDF document (the template), place it on the output page, and fill some variable
text into a text block called firstname:
doc = p.open_pdi_document(filename, "");
if (doc == -1)
throw new Exception("Error: " + p.get_errmsg());
page = p.open_pdi_page(doc, pageno, "");
if (page == -1)
throw new Exception("Error: " + p.get_errmsg());
p.begin_page_ext(width, height, "");
p.fit_pdi_page(page, 0.0, 0.0, "");
p.fill_textblock(page, "firstname", "Serge", "encoding=winansi");
p.close_pdi_page(page);
p.end_page_ext("");
p.close_pdi_document(doc);
Cookbook A full code sample can be found in the Cookbook topic blocks/starter_block.
Overriding block properties. In certain situations the programmer would like to use
only some of the properties provided in a block definition, but override other properties
with custom values. This can be useful in various situations:
>The scaling factor for an image or PDF page will be calculated instead of taken from
the block definition.
>Change the block coordinates programmatically, for example when generating an
invoice with a variable number of data items.
>Individual spot color names could be supplied in order to match the requirements of
individual customers in a print shop application.
43
238
Chapter 10: Variable Data and Blocks
Property overrides can be achieved by supplying property names and the correspond-
ing values in the option list of all PDF_fill_*block( ) functions as follows:
p.fill_textblock(page, "firstname", "Serge", "fontsize=12");
This will override the block’s internal fontsize property with the supplied value 12. Al-
most all names of general properties can be used as options, as well as those specific to a
particular block type. For example, the underline option is only allowed for PDF_fill_
textblock( ), while the scale option is allowed for both PDF_fill_imageblock( ) and PDF_fill_
pdfblock( ) since scale is a valid property for both image and PDF blocks.
Property overrides apply only to the respective function calls; they will not be stored
in the block definition.
Controlling the display order of imported page and blocks. The imported page must
have been placed on the output page before using any of the block filling functions.
This means that the original page will usually be placed below the block contents. How-
ever, in some situations it may be desirable to place the original page on top of the filled
blocks. This can be achieved with the blind option of PDF_fit_pdi_page( ):
/* Place the page in blind mode to prepare the blocks, without the page being visible */
p.fit_pdi_page(page, 0.0, 0.0, "blind");
p.fill_textblock(page, "firstname", "Serge", "encoding=winansi");
/* ... fill more blocks ... */
/* Place the page again, this time visible */
p.fit_pdi_page(page, 0.0, 0.0, "");
Cookbook A full code sample can be found in the Cookbook topic blocks/block_below_contents.
Duplicating blocks. Imported blocks can also be useful as placeholder without any ref-
erence to the underlying contents of the block’s page. You can import a page with blocks
in blind mode on one or more pages, i.e. with the blind option of PDF_fit_pdi_page( ), and
subsequently fill the blocks. This way you can take advantage of the block and its prop-
erties, and can even duplicate blocks on multiple pages (or even on the same output
page).
Cookbook A full code sample can be found in the Cookbook topic blocks/duplicate_block.
Linking multiple Textflow blocks. Textflow blocks can be linked so that one block
holds the overflow text from a previous block. For example, if you have long variable
text which may need to be continued on another page you can link two blocks and fill
the text which is still available after filling the first block into the second block.
PPS internally creates a Textflow from the text provided to PDF_fill_textblock( ) and
the block properties. For unlinked blocks this Textflow will be placed in the block and
the corresponding Textflow handle will be deleted at the end of the call; overflow text
will be lost.
With linked Textflow blocks the overflow text which remains after filling the first
block can be filled into the next block. The remainder of the Textflow will be used as
block contents instead of creating a new Textflow. Linking Textflow blocks works as fol-
lows:
35
10.4 Filling PDFlib Blocks with PPS 239
>In the first call to PDF_fill_textblock( ) within a chain of linked blocks a value of -1 (in
PHP: 0) must be supplied for the textflowhandle option. The Textflow handle created
internally will be returned by PDF_fill_textblock( ), and must be stored by the user.
>In the next call the Textflow handle returned in the previous step can be supplied to
the textflowhandle option (the text supplied in the text parameter will be ignored in
this case, and should be empty). The block will be filled with the remainder of the
Textflow.
>This process can be repeated with more Textflow blocks.
>The returned Textflow handle can be supplied to PDF_info_textflow( ) in order to de-
termine the results of block filling, e.g. the end condition or the end position of the
text.
Note that the fitmethod property should be set to clip (this is the default anyway if text-
flowhandle is supplied). The basic code skeleton for linking Textflow blocks looks as fol-
lows:
p.fit_pdi_page(page, 0.0, 0.0, "");
tf = -1;
for (i = 0; i < blockcount; i++)
{
String optlist = "encoding=winansi textflowhandle=" + tf;
tf = p.fill_textblock(page, blocknames[i], text, optlist);
text = null;
if (tf == -1)
break;
/* check result of most recent call to fit_textflow() */
reason = (int) p.info_textflow(tf, "returnreason");
result = p.get_parameter("string", (float) reason);
/* end loop if all text was placed */
if (result.equals("_stop"))
{
p.delete_textflow(tf);
break;
}
}
Cookbook A full code sample can be found in the Cookbook topic blocks/linked_textblocks.
48
240
Chapter 10: Variable Data and Blocks
10.5 Standard Properties for Automated Processing
PDFlib supports general properties which can be assigned to any type of block. In addi-
tion there are properties which are specific to the block types Text, Image, and PDF. Some
properties are shared, which means that they can be assigned to multiple blocks at once
using the Block plugin.
Properties support the same data types as option lists except handles and action
lists.
Many block properties have the same name as options for PDF_fit_image( ) (e.g.,
fitmethod) and other functions, or as PDFlib parameters (e.g., charspacing). In these cases
the behavior is exactly the same as the one documented for the respective option or pa-
rameter.
Property processing in PDFlib. The PDFlib Block functions PDF_fill_*block( ) will process
block properties in the following order:
>If the backgroundcolor property is present and contains a color space keyword differ-
ent from None, the block rectangle will be filled with the specified color.
>All other properties except bordercolor and linewidth will be processed.
>If the bordercolor property is present and contains a color space keyword different
from None, the block rectangle will be stroked with the specified color and linewidth.
>Text blocks: if neither text nor default text has been supplied, there won’t be any
output at all, not even background color or block border.
There will be no clipping; if you want to make sure that the block contents do not ex-
ceed the block rectangle avoid fitmethod nofit.
To use a separation (spot) color in a block property you can click the »...« button
which will present a list of all HKS and PANTONE spot colors. These color names are built
into PDFlib (see Section 3.3.2, »Spot Colors«, page 61) and can be used without further
preparations. For custom spot colors an alternate color can be defined in the Block plu-
gin. If no alternate color is specified in the Block properties, the custom spot color must
have been defined earlier in the PDFlib application using PDF_makespotcolor( ). Other-
wise the block functions will fail.
10.5.1 General Properties
General properties apply to all kinds of blocks (Text, Image, PDF). They are required for
block administration, describe the appearance of the block rectangle itself, and manage
how the contents will be placed within the block. Required entries will automatically be
generated by the PDFlib Block Plugin. Table 10.4 lists the general properties.
Table 10.4 General block properties
keyword
possible values and explanation
Block administration
Name
(String; required) Name of the block. Block names must be unique within a page, but not within a docu-
ment. The three characters [ ] / are not allowed in block names. Block names are restricted to a maxi-
mum of 125 characters.
Description
(String) Human-readable description of the block’s function, coded in PDFDocEncoding or Unicode (in the
latter case starting with a BOM). This property is for user information only, and will be ignored when
processing the block.
Documents you may be interested
Documents you may be interested
