Navigation:  »No topics above this level« Using PDFlib Blocks plugin

Using PDFlib Blocks plugin

Variable Data and Blocks (PDFLib Plugin)

 

PDFlib supports a template-driven PDF workflow for variable data processing. Using the concept of blocks, imported pages can be populated with variable amounts of single- or multi-line text, images, or PDF graphics which can be pulled from an external source. This can be used to easily implement applications which require customized PDF documents.

 

Installing the PDFlib Block Plugin

 

The Block plugin and its sibling, the PDF form field conversion plugin, work with Acrobat 5, Acrobat 6/7/8 Standard and Professional on Windows and Mac. The plugins don’t work with Acrobat Elements or any version of Acrobat Reader/Adobe Reader.

 

Note: The plugins contain multiple language versions of the user interface, and will automatically use the same interface language as the Acrobat application if possible. If the plugin does not support the native Acrobat language the English user interface will be used instead.

 

Installing the PDFlib Block plugins for Acrobat 5/6/7/8 on Windows. To install the PDFlib Block plugin and the PDF form field conversion plugin in Acrobat 5, 6, 7, or 8, the plugin files must be copied to a subdirectory of the Acrobat plugin folder. This is done automatically by the plugin installer, but can also be done manually. The plugin files are called Block.api and AcroFormConversion.api. A typical location of the plugin folder looks as follows:

 

C:\Program Files\Adobe\Acrobat 8.0\Acrobat\plug_ins\PDFlib Block Plugin

 

 

Installing the PDFlib Block plugins for Acrobat 6/7/8 on the Mac. With Acrobat 6/7/8 the plugin folder will not be visible in the Finder. Instead of dragging the plugin files to the plugin folder use the following steps (make sure that Acrobat is not running):

•Extract the plugin files to a folder by double-clicking the disk image.

•Locate the Acrobat application icon in the Finder. It is usually located in a folder which has a name similar to the following:

/Applications/Adobe Acrobat 8.0 Professional

 

•Single-click on the Acrobat application icon and select File, Get Info.

•In the window that pops up click the triangle next to Plugins.

•Click Add... and select the PDFlib Block Plugin AcroX folder (where X designates your Acrobat version) from the folder which has been created in the first step. Note that after installation this folder will not immediately show up in the list of plugins, but only when you open the info window next time.

 

Installing the PDFlib Block plugins for Acrobat 5 on the Mac. To install the plugins for Acrobat 5, start by double-clicking the disk image. Drag the folder PDFlib Block Plugin Acro5-6 to the Acrobat5 plugin folder. A typical plugin folder name is as follows:

 

/Applications/Adobe Acrobat 5.0/Plug-Ins

 

Troubleshooting.  If the PDFlib Block plugin doesn’t seem to work check the following:

•Make sure that in Edit, Preferences, [General...], General (Acrobat 8)/Startup (Acrobat 6/7)/Options (Acrobat 5) the box Use only certified plug-ins is unchecked. The plugins will not be loaded if Acrobat is running in Certified Mode

•Some PDF forms created with Adobe Designer may prevent the Block plugin as well as other Acrobat plugins from working properly since they interfere with PDF’s internal security model. For this reason we suggest to avoid Designer’s static PDF forms, and only use dynamic PDF forms as input for the Block plugin.

 

 

To download the plugin visit:

 

http://www.pdflib.com/download/pdflib-family/block-plugin

 

Overview of the PDFlib Block Concept

 

Complete Separation of Document Design and Program Code

PDFlib data blocks make it easy to place variable text, images, or graphics on imported pages. In contrast to simple PDF pages, pages containing data blocks intrinsically carry information about the required processing which will be performed later on the server side. The PDFlib block concept completely separates the following tasks:

•A designer creates the page layout, and specifies the location of variable text and image elements along with relevant properties such as font size, color, or image scaling. After creating the layout as a PDF document, the designer uses the PDFlib Block plug-in for Acrobat to specify variable data blocks and their associated properties.

•A programmer writes code to connect the information contained in PDFlib blocks on imported PDF pages with dynamic information, e.g., database fields. The programmer doesn’t need to know any details about a block (whether it contains a name or a ZIP code, the exact location on the page, its formatting, etc.) and is therefore independent from any layout changes. PDFlib will take care of all block-related details based on the block properties found in the file.

 

In other words, the code written by the programmer is »data-blind« – it is generic and does not depend on the particulars of any block. For example, the designer may decide to use the first name of the addressee in a mailing instead of the last name. The generic block handling code doesn’t need to be changed, and will generate correct output once the designer changed the block properties with the Acrobat plugin to use the first name instead of the last name.

 

Block Properties

The behavior of blocks can be controlled with block properties. The properties are as-signed to a block with the PDFlib Block plugin for Acrobat.

 

Standard block properties.  PDFlib blocks are defined as rectangles on the page which are assigned a name, a type, and an open set of properties which will later be processed on the server side. The name is an arbitrary string which identifies the block, such as firstname, lastname, or zipcode. PDFlib supports the following kinds of blocks:

•Type Text means that the block will hold one or more lines of textual data. Multi-line text will be formatted with the Textflow feature. Textflow blocks can be linked so that one block holds the overflow text of the previous.

•Type Image means that the block will hold a raster image. This is similar to importing a TIFF or JPEG file in a DTP application.

•Type PDF means that the block will hold arbitrary PDF graphics imported from a page in another PDF document. This is similar to importing an EPS graphic in a DTP application.

A block may carry a number of standard properties depending on its type. Properties can be created and modified with the PDFlib Block Plugin (see Section Editing Block Properties). A full list of standard block properties can be found in Section Standard Properties for Automated Processing. For example, a text block may specify the font and size of the text, an image or PDF block may specify the scaling factor or rotation. For each type of block the PDFlib API offers a dedicated function for processing the block. These functions search an imported PDF page for a block by its name, analyze its properties, and place some client-supplied data (text, raster image, or PDF page) on the new page according to the corresponding block properties.

 

Custom block properties.  Standard block properties make it possible to quickly implement variable data processing applications, but these are limited to the set of properties which are internally known to PDFlib and can automatically be processed. In order to provide more flexibility, the designer may also assign custom properties to a block. These can be used to extend the block concept in order to match the requirements of the most demanding variable data processing applications.

There are no rules for custom properties since PDFlib will not process custom properties in any way, except making them available to the client. The client code can examine the custom properties and act in whatever way it deems appropriate. Based on some custom property of a block the code may make layout-related or data-gathering decisions. For example, a custom property for a scientific application could specify the number of digits for numerical output, or a database field name may be defined as a custom block property for retrieving the data corresponding to this block.

 

 

 

Using the PDFlib Block Plugin to create Blocks

 

Creating Blocks interactively Activating the PDFlib Block tool. The PDFlib Block plugin for creating PDFlib blocks is similar to the form tool in Acrobat. All blocks on the page will be visible when the block tool is active. When another Acrobat tool is selected the blocks will be hidden, but they are still present. You can activate the block tool in several ways:

•by clicking the block icon in Acrobat’s Advanced Editing toolbar (in Acrobat 5: Editing toolbar);

•via the menu item PDFlib Blocks, PDFlib Block Tool;

•by using the keyboard shortcut P; make sure to enable Edit, Preferences, [General...], General, Use single key accelerators to access tools, which is disabled by default (not required in Acrobat 5)

 

Creating and modifying blocks.  Once you activated the block tool you can simply drag the cross-hair pointer to create a block at the desired position on the page and the de-sired size. Blocks will always be rectangular with edges parallel to the page edges. When you create a new block the block properties dialog appears where you can edit various properties of the block (see Section Editing Block Properties). The block tool will automatically create a block name which can be changed in the proper-ties dialog. Block names must be unique within a page. You can change the block type in the top area to one of Text, Image, or PDF. The General and Custom tabs will always be available, while only one of the Text, Image, and PDF tabs will be active at a time depending on the chosen block type. The Textflow tab will only be present for blocks of type text if the textflow property is true. Another tab labelled Tabs (tabulator positions) will only be available if the hortabmethod property in the Textflow tab has been set to ruler.

 

Note After you added blocks or made changes to existing blocks in a PDF, use Acrobat’s »Save as...« Command (as opposed to »Save«) to achieve smaller file sizes.

 

Note When using the Acrobat plugin Enfocus PitStop to edit documents which contain PDFlib blocks you may see the message »This document contains PieceInfo from PDFlib. Press OK to continue editing or Cancel to abort. « This message can be ignored; it is safe to click OK in this situation.

 

Selecting blocks.  Several block operations, such as copying or moving, work with selected blocks. You can select one or more blocks with the block tool as follows:

•To select a single block simply click on it with the mouse.

•Hold down the Shift key while clicking on another block to extend the selection.

•Press Ctrl-A (on Windows) or Cmd-A (on the Mac) or Edit, Select All to select all blocks on a page.

 

The context menu. When one or more blocks are selected you can open the context menu to quickly access block-related functions (which are also available in the PDFlib Blocks menu). To open the context menu, click on the selected block(s) with the right mouse button on Windows, or Ctrl-click the block(s) on the Mac.

For example, to delete a block, select it with the block tool and press the Delete key, or use Edit, Delete in the context menu.

 

Figure 1: Editing Block Properties: The textflow panel is only visible if textflow=true

 

 

Fine-tuning block size and position. Using the block tool you can move one or more selected blocks to a different position. Hold down the Shift key while dragging a block to restrain the positioning to horizontal and vertical movements. This may be useful for exactly aligning blocks. When the pointer is located near a block corner, the pointer will change to an arrow and you can resize the block. To adjust the position or size of multiple blocks, select two or more blocks and use the Align, Center, Distribute, or Size commands from the PDFlib Blocks menu or the context menu. The position of one or more blocks can also be changed by using the arrow keys.

 

Alternatively, you can enter numerical block coordinates in the properties dialog. The origin of the coordinate system is in the upper left corner of the page. The coordinates will be displayed in the unit which is currently selected in Acrobat. To change the display units proceed as follows:

 

•In Acrobat 6/7 go to Edit, Preferences, [General...], Units & Guides [or Unit, Page Units in Acrobat 7 Standard] and choose one of Points, Inches, millimeters, Picas, Centimeters. You can also go to View, Navigation Tabs, Info and select a unit from the Options menu.

•In Acrobat 5 go to Edit, Preferences, General..., Display, Page Units and choose one of Points, Inches, Millimeters. You can also go to Window, Info and select a unit from the Info menu.

 

Note that the chosen unit will only affect the Rect property, but not any other numerical properties.

 

Creating blocks by selecting an image or graphic. As an alternative to manually dragging block rectangles you can use existing page contents to define the block size. First, make sure that the menu item PDFlib Blocks, Click Object to define Block is enabled. Now you can use the block tool to click on an image on the page in order to create a block with the size of the image. You can also click on other graphical objects, and the block tool will try to select the surrounding graphic (e.g., a logo). The Click Object feature is intended as an aid for defining blocks. If you want to reposition or resize the block you can do so afterwards without any restriction. The block will not be locked to the image or graphics object which was used as a positioning and sizing aid.

The Click Object feature will try to recognize which vector graphics and images form a logical element on the page. When some page content is clicked, its bounding box (the surrounding rectangle) will be selected unless the object is white or very large. In the 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 generated 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, depending 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 underlying font which is present at the location where a block is positioned, and can automatically 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, resizing,

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.

 

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 1). As detailed in Section Standard Properties for Automated Processing, 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.

 

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 entry 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. Section Standard Properties for Automated Processing, details which properties can be shared among multiple blocks. Custom properties cannot be shared.

 

Copying Blocks between Pages and Documents

The Block plugin offers several methods for moving and copying blocks within the current 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 replace the underlying page(s) while keeping the blocks. Use Document, Replace Pages... (Acrobat 5 and 7) or Document, Pages, Replace (Acrobat 6).

 

Moving and copying blocks. You can relocate blocks or create copies of blocks by selecting 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 exception 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.

•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 possible 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 existing 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 importing 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 definitions 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 Repeat 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.

 

Standard Properties for Automated Processing

 

PDFlib supports general properties which can be assigned to any type of block. In addition 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 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 parameter.

 

 

Property processing in PDFlib. The PDFlib Block functions fill_*block( ) will process block properties in the following order:

•If the backgroundcolor property is present and contains a color space keyword different 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 exceed 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 and can be used without further preparations. For custom spot colors an alternate color can be defined in the Block plugin. If no alternate color is specified in the Block properties, the custom spot color must have been defined earlier in the PDFlib application using makespotcolor( ). Otherwise the block functions will fail.

 

 

 

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 1 lists the general properties.

 

 

 

Table 1 General block properties

 

 

Text Properties

Text-related properties apply to blocks of type Text (in addition to general properties). All text-related properties can be shared.

 

Properties for all text blocks. Text blocks can contain a single line or multiple lines, depending on the textflow property. Table 2 lists the text-related properties which apply to both types.

 

Table 2 Text block properties

 

 

Properties for Textflow blocks.

Textflow-related properties apply to blocks of type Text where the textflow property is true. The text-related properties will be used to construct the initial option list for processing the Textflow (corresponding to the optlist parameter of create_textflow( )). Inline option lists can not be specified with the plugin, but they can be supplied on the server as part of the text contents when filling the block with fill_textblock( ). All Textflow-related properties can be shared. Table 3 lists the Textflowrelated properties.

 

Table 3  Textflow block properties

 

 

Image Properties

Image-related properties apply to blocks of type Image (in addition to general properties). All image-related properties can be shared. Table 4 lists image-related properties.

 

Table 4 Image block properties

 

 

PDF Properties

 

PDF-related properties apply to blocks of type PDF (in addition to general properties). All PDF-related properties can be shared. Table 5 lists PDF-related properties.

 

Table 5 PDF block properties

 

 

Custom Properties

 

Custom properties apply to blocks of any type of block (in addition to general and type-specific properties). Custom properties are optional, and can not be shared. Table 6 lists the naming rules for custom properties.

 

Table 6 Custom block properties

 

 

ePower Online uses the above Custom properties to add more commands to the application.

Blocks Custom Commands (ePower Online Specific)

 

(Note: Each block created using the PDFLib Blocks plug-in can have an unlimited number of custom fields. Go ePower, however, recognizes the first 5 only. Please do not add more than 5 fields.)

 

Adding a Custom Field (or Property)?

1. Click on the custom button inside the Block Dialogue box (PDFLib Block Properties), then hit the Add button.

2. Always use string as the property type of the field.

3. Property Name has to be one of the following commands (or keys):

 

Table 7 Custom block properties

 

How to Use dropdown and radio commands?

The value portion of this command consists of any number of records separated by ;

Each segment is further divided into three portions, the first portion contains the displayed online value, and the second portion contains the actual printed value. The third portion is optional, if it contains the term $default then the segment would be selected (if a dropdown is used) or checked (if radio buttons are used)

Example:

Displayed Text 1::::Value 1::::$default;Displayed Text 2::::Value 2;Displayed Text 3::::Value 3

 

\n can be embedded into the value portion to indicate a new line

Embedded fields can be used inside the values as well.

 

As an option, the value field can contain a file name to read the string from, since the maximum number of characters allowed in a value fields is limited to 4096.

 

How to Use an external text file as value to dropdown and radio commands?

The value portion contains the text file name with full (virtual) path. The starting character should always be ~ followed by / then the reset of the path. It is recommended to reference a file in the company assets so company managers can update it.

The path to the asset is: ~/Storage/ProducerID/CompanyID/Assets/Documents/ follows either by subfolder(s) then the filename.

The syntax is the same as when entering the values directly, with the exception that line breaks are allowed, so it can be something like:

 

Displayed Text 1::::Value 1::::$default;

Displayed Text 2::::Value 2;

Displayed Text 3::::Value 3

 

 

How to Use prefix and postfix?

The value for this command can be any text. The value will display before the entered value (prefix) or after the entered value (postfix). This value will only display if the field has a value, that is, the user has entered something in the field.

<space> can be used to indicate a space

 

How to Use rows?

The value for this command is simply an integer that defines the number of rows required for a multiline textbox. Height in pixel can be used in the 'status' command.

 

How to Use Checkbox?

For a text field, this command will display a checkbox. The checkbox will be checked off if Y was used as the third parameter. The value consists of four parameters separated by ^

1. Displayed value

2. Printed Value

3. Y for checked N for unchecked

4. P for print

 

Example:

Display Time^10:00pm^Y^P

 

For an image field, three parameters are used

1. Displayed Value

2. Path and file name of image

3. Y for checked N for unchecked

 

Example:

Display Logo^images/logo.gif^Y

How to Use follow?

The value of the follow command is the name of a block to follow. If the named block is empty then the current block will take its place. This runs recursive, so if the followed block is following an empty block then the current block will follow as well and so on.

Follow happens regardless of block position, that is, the current block location is replaced by the followed whether it was on top or bottom or any other location.

The follow command can be applied to all block types (Text, Image and PDF)

 

How to Use follow maintaining block size and specifying adjusted location?

To retain the dimension of the original block, add a semicolon (;) after the followed Block name then put one or two of the following:

left right top bottom center vcenter hcenter

 

Usage example: follow-à  Name;left top

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

How to Use inline?

This command is used to display fields on the same line. The fields are separated by semi-colon ;

Each segment is further divided using ^, these are used as follows:

First  ^ put a prefix

Second ^ put a postfix

Third  ^ for Action, use MD for Mandatory and/or MC for Must Change

Fourth ^ Default Value

Fifth  ^ for dropdown - Text::::Value~Text::::Value

~ separates items, :::: separates text and values

 

Example

City^^,<space>;

Province^^^MCMD^ON^Alberta::::AB~Ontario::::ON~British Columbia::::BC~Quebec::::QB;

PostalCode^<space><space>

 

{Phone}^Tel: ^ ;{Fax}^Fax:

 

The prefix and postfix allow another separator %% inside, this separator is used to indicate whether to print the prefix or postfix depending if another block has value.

Please note that this function applied only to external blocks and not within the inline command. That is, it only works with the last example above.

 

How to use another block to control displaying a prefix or postfix?

The separator used here is %% to be followed by a block name. As an example:

{Phone};{Fax}^ | %%{Phone}

 

The prefix here is the pipe character |, if %%{Phone} part does not exist then | will appear every time there is a fax number. Using %%{Phone} asks the system to check the value of {Phone} block as well, in case both Fax and Phone have values then | will print otherwise it will not. The {Phone} after the %% separator does not print, the system just uses its value to control the prefix and postfix.

 

How to Use paragraph?

The paragraph command simply prints its value to. The value can contain two types of Blocks:

1. Block fields that are enclosed by <>

2. Block fields that are enclosed by {}, these are called embedded fields or blocks

 

The first type will prompt the user for a value, that is, it will be treated almost like any other standalone block, whereas the second assumes that the block does already exist and only its value used to print.

 

Differences between Paragraph Fields and Embedded Fields

1.Paragraph fields are enclosed by <> where as the embedded fields are enclosed by {}

2.Paragraph fields can only appear in 'paragraph' custom field command. They are displayed online asking the user for values, where as Embedded fields can appear in almost all custom fields, they need to be present in advance and only their values will be used. That is, the Embedded fields are not displayed online - but rather they take their values from already defined blocks.

 

How to use format?

Simply put the one of the following commands as values to the format command (or key)

 

The last two are free formats, except for the enclosing brackets; any character except for # will be printed as is. The # is replaced by a digit. The last example has an additional extension. This extension is separated by the ^ character. Ext: can be replaced by other characters.

 

How to use replace?

This command scans the field entry and replaces characters by others. For example changing & to and.

The terms are separated by semi-colon ; whereas replaced text and new text are separated by ^

A third term can be added to indicate whether to ignore case (I) or match it (M)

Ignoring the case is the default, so I can be ignored.

 

Example:

&^and;text^Text^I;PT^Print Three^M

 

In the above:

'&' is replaced by 'and'

'text', 'Text', 'TEXT', 'TExt'... is replaced by 'Text' since I is indicated (ignore case)

'PT' is replaced by 'PRINT THREE'. Since M is specified then only PT is replaced and not pt, Pt or pT

 

How to use optlist?

This is an advanced command. It requires further reading into the PDFLib manual. To use this command, make sure that the containing block be of type textflow and not just text.

This command can be used to insert certain text commands, like changing fonts, sizes, attributes and so on. There are examples that will show some of these commands that can be embedded into other commands without the need for specifically using optlist.

 

How to use shape?

Values allowed for shape are:

       

All of the four commands support further attributes. Syntax is as follows:

Command(caps, small, proper or char)%%<Font attributes of first character in word>%%<Font attributes for the rest>

 

Example 1:

Shape                caps%%<fontsize=10>%%<fontsize=10>

 

For the above if the entry is:

capitalize all characters and make the first larger

 

then the output is:

 

CAPITALIZE ALL CHARACTERS AND MAKE THE FIRST LARGER      

 

 

Example 2:

 

       

For the text:

Change font of first character and capitalize it

 

Output is:

Change Font Of First Character And Capitalize It

 

 

How to use order?

This simply organizes the order of the fields that will show to the user. The values are just integers starting from 0 up. Numbers can be skipped.

 

How to use address?

This command is used to access the address book fields for single entry block types. The address book consists of the standard fields and any extra fields that are added for the company.

 

How to use fontchange?

This is mainly used to change fonts and sizes within the entered text.

 

Example:

1^<fontname=Helvetica fontsize=20 encoding=winansi>^<fontname=Helvetica fontsize=12 encoding=winansi>

 

The first character of the field is changed to size 20 while the rest will be of size 12. The number in the command (here 1) specifies the number of characters to use the first font. Fields are separated by ^

 

How to use status with text block?

A number of conditions can be used as value to this command. The recognized conditions are:

no print, noprint, do not print, don't print, dontprint

mandatory

readonly, read only

hide

must change, change, mustchange

max length = 200, maxlength = 200, length = 200

width = 200                                        width of control

height = 80                                        height of control (for multi-line textbox)

 

Example:

mandatory must change max length=100 width=200 height=80

 

That is the user must enter a value (the field cannot be empty), the default text that displays to the user must be changed by the user (must change). Users can only enter a maximum of 100 characters. The width of the displayed textbox is 200 pixels while the height is 100 pixels (assuming this field has textflow enabled otherwise the height is ignored)

 

 

 

 

How to use status with image and pdf blocks?

The values for the status command are typed as one string. For example:

 

size=100 selectedsize=100 imagesperline=3 upload

 

size is the image size on the product page. selectedsize is the images size on the image selector page, it defaults to size if not mentioned. Imagesperline controls the number of images per row of the selector.

upload is used with the select command to allow upload to the directory indicated as value to the select command.

 

 

How to use the Embedded blocks?

A blockname can be embedded in the value portion of the commands that allow embedding (see related table). Assume that there is a block (or field) that needs to be inserted as prefix to another block. For example, the first block is called title and has a dropdown command with the value as such:

Mr::::Mrs::::Ms

 

A dropdown will display for the customer to select title from, then another text block (field) to enter the fullname. This block will have a prefix command with the following value:

{title}.<space>

 

If the user selected Mr and then entered David Smith as a name then the printed text will be:

Mr. David Smith

 

While we could've used the two blocks separately, the problem would've been in the spacing, Mr and Mrs and Ms have different widths that cannot be defined when creating the blocks. Please note here that we need another command for the dropdown so that it will not print on its own, the command is status and the value is simply noprint.

 

How to use the select and upload commands?

Values to these commands are folder path to select files from or upload files to.

The system recognizes the keywords ‘personal’ and ‘company’. These two keywords point to the personal images / document folders or the company images / document folders that are preset for each company.

Sub-folders can be appended to the keywords too.

In addition to the two option, free format can also be used, starting with ~/

The ‘upload’ option also recognizes the keyword auto which is equivalent to not adding the ‘upload’ or ‘select’ options (default) where the system creates a temporary directory for upload.

Upload Sample:

Personal/my logos

 

‘status’ command is also checked when processing the above options, the keyword ‘upload’ (as value to status) is recognized when using the ‘select’ command. It allows users to upload images/pdfs to the selected folder.

 

How to make text overflow from one block to another?

 

The starting block should be defined with the following parameters:

1.Fitmethod (general table) should be set to Clip

2.Add a custom command named: continue

3.Enter a block name to follow as a value to the continue command. The block name is case sensitive. It is very important to enter the name EXACTLY as defined.

4.It is required to add a status custom command with value: hide

5.The hide value will prevent the followed block from displaying to the user as an input field.

6.Any number of blocks can be chained together; the above rules are applied to them too.

 

 

How to use a Font Alias?

 

Aliases are required in cases where font names exist in more than on font file. To create an alias:

1.Change the font name of a block to an alias (do not uses spaces in the name).

2.Change the font type to ‘Load’

3.Put the alias name in the force load fonts field followed by a colon : then the actual filename. For type1 fonts, use either the pfm or pfb file names.

 

CASES:

 

How to create Provinces and Territories dropdown with displayed values being of the whole text while the printed values are the abbreviation? Make Ontario shows as the default.

command:        dropdown

value:        copy and paste the following:

 

Alberta::::AB;British Columbia::::BC;Manitoba::::MB;New Brunswick::::NB;Newfoundland and Labrador::::NL;Nova Scotia::::NS;Ontario::::ON::::$default;Quebec::::QC;Prince Edward Island::::PE;Saskatchewan::::SK;Northwest Territories::::NT;Nunavut::::NU;Yukon::::YT;

 

How to create a day of week dropdown?

command:        dropdown

value:        copy and paste the following:

 

Sunday;Monday;Tuesday;Wednesday;Thursday;Friday;Saturday

 

How to use a dropdown to return more than one value?

As an example, assume that there are two locations to print different values depending on Users’ selection. The selection would be either English French or Both Languages

Create a block with name ‘ Language’ and with two command keys:

Key 1        Status

Value 1       noprint

Key 2               dropdown

Value 2       copy and paste the following:

English Language::::Company Name for string One in English////Company Name for string Two in English;

French Language::::Company Name for string One in French////Company Name for string Two in French;Both Languages;

Both Language::::Company Name for string One in English / Company Name for string One in French////Company Name for string Two in English / Company Name for string Two in French

 

The value for the English Language, for example, comes after ::::

This string has another separator //// which tells the application that only a portion of the string is to be returned depending on the block call. That is, {Language::1} will bring the first portion while {Language::2} returns the second.

 

In the first print location we'll put a block with a paragraph command (make sure that the block has its textflow enabled). The value for the paragraph command is simply {Language::1}

The second location has the value to paragraph be {Language::2}

 

Unlimited ::: separators or //// can be used. A call to the block without a number, that is {Language} will return all values with their //// replaced by single spaces.

What are the acceptable font types?

 

 

What is order of execution of the commands?

 

 

Can I change or add commands after uploading the file to ePower Online?

It is recommended to change or add the commands in the PDF file; you can always download the ‘blocked’ file, edit it then upload it again. For quick changes or testing, all the commands and there values are accessible from ePower Online’s backend.

 

How to ask a customer for an entry once but print to more than one location?

Create as many blocks as required to print. For the first block, type the block name as you want it to display to the user. For all other blocks, name them exactly the same but add (. Dot) followed immediately by a digit. So if the block name is ‘Company Name’ then the other blocks are named ‘Company Name.1’, Company.Name.2’ and so on. Make sure not to use dots in names except in such cases.

 

How to print bulleted or numbered text?

 

Place the following coding as value to the ‘paragraph’ command after replacing text with your data:

 

<leftindent=0>BULLET<leftindent=10>{Block Name 1}<nextline>

<leftindent=0>BULLET<leftindent=10>{Block Name 2}<nextline>

<leftindent=0>BULLET<leftindent=10>{Block Name 3}<nextline>

 

Where BULLET is the bullet character used (or number) and Block Name 1, 2 and 3 are valid blocks in the document. The above example is for adding three bulleted lines, more can be added.

 

The Idea here is to set the left indentation to 0 before the bullet character, then set it again after the character to the specified distance. <nextline> will simply feed a new line.

Please note that these angle-bracket commands work with textflow type only. They do not work with the standard text type. If you need to use them, then enable textflow for the block even if it uses one line only.

 

What is PDFLib’s coordinate system?

 

PDF’s default coordinate system is used within PDFlib. The default coordinate system (or default user space) has the origin in the lower left corner of the page, and uses the DTP point as unit:

1 pt = 1/72 inch = 25.4/72 mm = 0.3528 mm

 

Example:

Leftindent=10 converts to 10 * 1/72 = 10/72 = 0.139 inches

 

You can also use percentages instead, something like leftindent=5%

 

How to add Phone and Fax in one line?

 

The following shows one method of joining the phone and fax fields.

 

1.Create two blocks and name them phone and fax

2.Add a prefix command to each (e.g. tel:<space> and fax:<space>)

3.Optional: add a postfix command for the phone (e.g. <space>|<space>)

4.Add a status command with noprint as value

5.Create another block to combine phone and fax

6.Add an inline command to the new block and enter the following as value {phone};{fax}

7.Add a status command with hide as value (this is needed so that the user will not be asked for a value for this block)

8.If changing fonts is required then change the type of the combination block to textflow so that it can handle the attributes

9.To change certain text to bold use the following:

 

<fontname=Helvetica-Bold encoding=winansi>tel:<space><fontname=Helvetica encoding=winansi>

 

We change the system font before the word tel: then restore the original font afterwards. It is important to add the encoding part, otherwise PDFLib will ignore the whole tag. Fonsize can be changed too.

 

You can also add a ‘format’ command in the custom area for both phone and fax field to control how they look. Acceptable values are:

canada phone  (123) 123-1234

us phone    (123) 123-1234

dot phone  123.123.1234

or free format like

{### / ### - ####}   the {} are mandatory, # is replaced by a digit and anything else will printed as is

               Actually, we could have added the tel: or fax: right here, something like

               {phone: (###) ###-####}

 

More advanced option to contain an extension

{phone: (###) ###-#### Ext:^ ####}  ^ is a special character to separate the number form the extension.

 

‘if’ command Recognized Functions

 

Acceptable functions are:

 

 

 

Recognized operators in the expression

+    -    =    !=    <    <=    >    >=

 

Example:

"{Location}"!=concat("Toro","nto") and string-length("{Location}")>5

and

translate('{Location}','ABCDEFGHIJKLMNOPQRSTUVWXYZ','abcdefghijklmnopqrstuvwxyz')='toronto'

 

How to add predefined spot colors within text?

 

Use the following syntax:

 

<fillcolor={spotname {actual color name} tint-value}>

 

 

Examples:

<fillcolor={spotname {PANTONE 481 U} 1}>

 

<fillcolor={spotname {PANTONE 100 C} 0.8}>

 

 

The actual color name can be taken from the list offered by PDFLib plugin when separation option is selected for color.