Interactive PDF Output
PDF Forms
PTC ALD provides the option to define, create, and use all types of PDF form object, such as buttons, text boxes, and list boxes. With these user interface features you can interact with a PDF.
There is no interactive element for PDF forms in the PTC ALD WYSIWYG view, since they are intended for PDF only. PTC ALD reserves space for the form object and provides an option to display the non-printing border and identifier of the object.
The option PDF Form Items is provided under Screen Draw Level options:
With this option selected, PTC ALD draws a box on screen with the PDF name of the form object displayed for identification purposes. For example:
You can add scripting to PDF form objects. For more information, see PDF Actions in this topic.
PDF Form Objects
All PDF form items are represented in PTC ALD documents as control streams held in tags of type PX. You can access them either as streams (read, write, and so on) or through their own objects. The different form object types all inherit a base object fPDFFormItem. This object carries a number of properties which are common to all form object types.
The fPDFFormItem object carries these properties:
• actionActivate — The fPDFAction object to execute when the form item is activated
• alignment — How to align the text in the form item
Allowed values are listed on the fPDFFormItem.AlignmentTypes constant:
◦ fPDFFormItem.ALIGNMENT_LEFT
◦ fPDFFormItem.ALIGNMENT_CENTER
◦ fPDFFormItem.ALIGNMENT_RIGHT
• backgroundColor — The color for the background of the form item
An fColor object is expected, but can only be RGB or CMYK colors.
• borderColor — The color for the border drawn around the form item by the reader
An fColor object is expected, but can only be RGB or CMYK colors.
• borderStyle — The rule style applied to the border
The allowed values are listed on the fPDFFormItem.BorderStyles constant. They are not PTC ALD’s own styles but those supported by the reader:
◦ fPDFFormItem.BORDER_SOLID
◦ fPDFFormItem.BORDER_BEVEL
◦ fPDFFormItem.BORDER_DASH
◦ fPDFFormItem.BORDER_INSET
◦ fPDFFormItem.BORDER_UNDERLINE
• calculationOrder — The order number for when form calculations are provided through a calculate action
• display — Whether the form item should be visible on screen or when printed from Acrobat
Allowed values are listed on the fPDFFormItem.DisplayModes constant:
◦ fPDFFormItem.DISPLAY_VISIBLE — output on screen and when printing
◦ fPDFFormItem.DISPLAY_HIDDEN — do not output on screen or when printing
◦ fPDFFormItem.DISPLAY_NOVIEW — only output when printing from Acrobat
◦ fPDFFormItem.DISPLAY_NOPRINT — only output when on screen, not when printing
• exportable —Whether the value of this form item will be submitted with the form if there is a submit form action.
• fillColor — The fill color of the form item
An fColor object is expected, but can only be RGB or CMYK colors.
• font — The system font name to use for the text in the field
The fonts used are embedded in the PDF.
Pseudo fonts are not supported.
• fontHeight — The height of the font used for the text in the field
• lineWidth — The weight of the border
• locked — Whether the form item is locked for edit with Acrobat’s form editing tools
• orientate — How to orient the contents of the form item
Allowed values are listed on the fPDFFormItem.Orientations constant:
◦ fPDFFormItem.ORIENT_NORTH = 0 — Regular orientation
◦ fPDFFormItem.ORIENT_WEST = 1 — Rotated so that the contents are aligned with the left of the form item
◦ fPDFFormItem.ORIENT_SOUTH = 2 — Rotated so that the contents are aligned with the bottom of the form item
◦ fPDFFormItem.ORIENT_EAST = 3 — Rotated so that the contents are aligned with the right of the form item
• pdfLayer — The PDF layer (fPDFLayer object) on which to draw the form item
PDF form items do not inherit the frame’s layer, so this should be specified explicitly.
• pdfName — The name given to the form item in the PDF, which allows it to be addressed by actions
The name must be unique in the PDF.
• readonly — Whether the form is read only and cannot be changed by a user in Acrobat
• required — Whether the form item must have a value when the form is submitted
• strokeColor — The stroke colour for the form item
An fColor object is expected, but can only be RGB or CMYK colors.
• tabOrder — The numeric order in which the form item will be accessed using the tab key in Acrobat
• tooltip — A string to display when the mouse hovers over a form item
Additions to the fContent object support the use of PDF form items:
• Property pdfFormItems — Returns a list of all form items in the document
• Method createPDFFormItem() — Creates new form items
• Constant PDFFormItemTypes — provides the form item type to the createPDFFormItem() method:
◦ fContent.PDFFORM_PUSHBUTTON = 0 — A push button form item, for an fPDFFormPushButton object
◦ fContent.PDFFORM_CHECKBOX = 1 — A check box, for an fPDFFormCheckbox object
◦ fContent.PDFFORM_RADIOBUTTON = 2 — A radio button, for an fPDFFormRadioButton object
◦ fContent.PDFFORM_LISTBOX = 3 — A list box, for an fPDFFormListbox object
◦ fContent.PDFFORM_COMBOBOX = 4 — A combo box, for an fPDFFormCombobox object
◦ fContent.PDFFORM_TEXTFIELD = 5 — A text field, for an fPDFFormTextField object
◦ fContent.PDFFORM_SIGNATURE = 6 — A signature field, for an fPDFFormSignature object
◦ fContent.PDFFORM_ANY = -1 — not used when creating a form object.
For example, the code below will create the new PDF form item mySpecialButton as a push button:
var myButton;
myButton = template.content.getPDFFormItem("mySpecialButton");
if (!myButton) {
myButton =
template.content.createPDFFormItem("mySpecialButton",
fContent.PDFFORM_PUSHBUTTON);
}
You can then set the properties on the button to configure its behavior.
PDF Form Object Types
• Push Buttons
• Check Boxes
• Radio Buttons
• List Boxes
• Combo Boxes
• Text Fields
• Signatures
Each type has its own set of properties, in addition to those that are inherited from the fPDFFormItem object. The following sections provide information on the PDF Form object types.
Push Buttons
Push buttons are used to kick off an action and must have either a caption or an icon, or both.
Push buttons are represented in PTC ALD by the fPDFFormPushButton object, which has these properties:
• buttonLayout — Where the caption (if there is one) appears relative to the icon (if there is one)
The allowed values for this property are listed on the fPDFFormPushButton.ButtonLayouts constant:
◦ fPDFFormPushButton.LAYOUT_BELOW = 0 — show the caption below the icon
◦ fPDFFormPushButton.LAYOUT_ABOVE = 1 — show the caption above the icon
◦ fPDFFormPushButton.LAYOUT_RIGHT = 2 — show the caption to the right of the icon
◦ fPDFFormPushButton.LAYOUT_LEFT = 3 — show the caption to the left of the icon
◦ fPDFFormPushButton.LAYOUT_OVERLAID = 4 — show the caption over the top of the icon
• caption —The string to appear as text on the button in its default state
• captionDown — The string to appear as text on the button when the mouse clicks on it (fPDFFormPushButton.highlight = 3)
• captionRollover — The string to appear as text on the button when the mouse is over it (fPDFFormPushButton.highlight = 3)
• charSpacing — The character spacing of the caption text, provided as an fLength object
• fitMethod — How the icon should fit onto the button
The allowed values are listed on the fPDFFormPushButton.FitMethods constant:
◦ fPDFFormPushButton.FIT_AUTO = 0 — Try to fit the icon within the button, and clip it if this is not possible
◦ fPDFFormPushButton.FIT_CLIP = 1 — Clip the edges of the icon which do not fit into the button area
◦ fPDFFormPushButton.FIT_MEET = 2 — Scale the icon proportionally to fit into the button area
◦ fPDFFormPushButton.FIT_ENTIRE = 3 — Scale the whole icon to fit inside the button
• highlight — The behaviour of the button when it is clicked
The allowed values are listed on the fPDFFormPushButton.HighlightModes constant:
◦ fPDFFormPushButton.HIGHLIGHT_NONE = 0 — Do not highlight — the button won’t change
◦ fPDFFormPushButton.HIGHLIGHT_INVERT = 1 — Invert the colours used on the button
◦ fPDFFormPushButton.HIGHLIGHT_OUTLINE = 2 — Draw an outline around the button to highlight it
◦ fPDFFormPushButton.HIGHLIGHT_PUSH = 3 — Change the outline to make the button look like it has been pushed in
• icon —The icon for the button in its default state (fRaster object)
• iconDown — The icon which should be shown when the button is pressed (fPDFFormPushButton.highlight = 3) (fRaster object)
• iconRollover — The icon which should be shown when the cursor hovers over the button (fPDFFormPushButton.highlight = 3) (fRaster object)
• positionBottom — Where to place the icon relative to the bottom edge of the button
Permitted values are between 0 and 100, where 100 is the top edge and 50 is centered.
• positionLeft — Where to place the icon relative to the left edge of the button
Permitted values are between 0 and 100, where 100 is the right edge and 50 is centered.
• submitName — The name of the field value to use when submitting the form
For more information, see fPDFFormPushButton.
Check Boxes
Check boxes are fields which indicate an on or off state using a symbol in a box.
Check boxes are represented by the fPDFFormCheckbox object, which inherits the fPDFFormItem object. These are the properties of the object:
• buttonStyle — The check box symbol
The allowed values are listed on the fPDFFormCheckbox.ButtonStyles constant:
◦ fPDFFormCheckbox.STYLE_CHECK = 0 — Tick (default)
◦ fPDFFormCheckbox.STYLE_CROSS = 1 — Cross symbol
◦ fPDFFormCheckbox.STYLE_DIAMOND = 2 — Diamond
◦ fPDFFormCheckbox.STYLE_CIRCLE = 3 — Filled circle
◦ fPDFFormCheckbox.STYLE_STAR = 4 — Filled star
◦ fPDFFormCheckbox.STYLE_SQUARE = 5 —Filled square
The symbols are provided in Acrobat by the ZapfDingbats font in Windows.
| The symbols are aligned to the right of the checkbox in Acrobat. |
• currentValue — The value of the checkbox when opened
If the value is anything other than Off, the checkbox appears selected.
• defaultValue — The value to which the checkbox reverts if the form is reset
If the value is anything other than Off, the checkbox appears selected.
• itemName — The name to use for the form item when it is exported
For more information, see fPDFFormCheckBox.
Radio Buttons
Radio buttons are used in groups to allow the user to select an option. They can be set up such that selecting one in a group will automatically deselect all others in the group. A group is specified using the name property — for example, a name of group1.radio1 will create a group called group1. Other buttons with the group1 prefix will belong to the same group.
Radio buttons are represented by the fPDFFormRadioButton object, which inherits the fPDFFormItem object. These are the properties of the object:
• buttonStyle — The button symbol
The allowed values are listed on the fPDFFormRadioButton.ButtonStyles constant:
◦ fPDFFormRadioButton.STYLE_CHECK = 0 — Tick (default)
◦ fPDFFormRadioButton.STYLE_CROSS = 1 — Cross symbol
◦ fPDFFormRadioButton.STYLE_DIAMOND = 2 — Diamond
◦ fPDFFormRadioButton.STYLE_CIRCLE = 3 — Filled circle
◦ fPDFFormRadioButton.STYLE_STAR = 4 — Filled star
◦ fPDFFormRadioButton.STYLE_SQUARE = 5 — Filled square
The symbols are provided in Acrobat by the ZapfDingbats font in Windows. Normal radio buttons are using the circle option.
• currentValue — The initial value of the radio button
If the value is anything other than Off, the button is set to On.
• defaultValue — The value to which the radio button reverts if the form is reset
If the value is anything other than Off, the button is set to On.
• itemName — The name of the field to use when the form is exported
This value is also used by unisonSelect.
• toggle — Whether the radio buttons can work in a ‘mutually exclusive’ mode.
If set to false, the button is deactivated by selecting another radio button in the group.
If set to true, the button can be deactivated by selecting it again
• unisonSelect — Whether the button can be activated when another button with the same itemName is also selected (when true)
For more information, see fPDFFormRadioButton.
List Boxes
List boxes present a list of options on separate lines. The list items have two values — the item text and the item name. Item text is displayed in the list. Item name is the value used when the form is submitted. These values are provided as lists which can be sorted (or not). List boxes can have many actions associated with them.
List boxes are represented by the fPDFFormListbox object, which has these properties:
• Actions — List boxes can have actions (fPDFAction objects) associated with many events, using these properties:
◦ actionBlur
◦ actionCalculate
◦ actionClose
◦ actionDown
◦ actionEnter
◦ actionExit
◦ actionFocus
◦ actionInvisible
◦ actionKeystroke
◦ actionOpen
◦ actionUp
◦ actionValidate
◦ actionVisible
• charSpacing — The character spacing of the text, expressed as an fLength object
• commitOnSelect — whether the value of the list item is committed when the list item is clicked (true)
Otherwise, when selecting an item in a list, it is only committed when a different form item is selected.
• currentValue — The current selected value of the list
The value is expressed as the index number of the initial itemTextList item to use.
• defaultValue — The value to which to return when the form is reset
The value is expressed as the index of the itemTextList item to use.
• itemNameList — The names of the text items displayed (comma separated list)
• itemTextList — The values that appear in the list box (comma separated list)
• multiSelect — Whether more than one item can be selected
• sorted — Whether Acrobat should sort the items displayed
• topIndex — The index of the first item to be visible if the list is long
If the list is longer than the space allocated, Acrobat will provide scroll bars.
For more information, see fPDFFormListBox.
Combo Boxes
Combo boxes are similar to list boxes, in that they present a list of values, but they present them as a drop-down field rather than a large rectangle.
Combo boxes are represented by the fPDFFormCombobox object, which shares similar properties with fPDFFormListbox:
• Actions — Combo boxes can have actions (fPDFAction objects) associated with many events, using these properties:
◦ actionBlur
◦ actionCalculate
◦ actionClose
◦ actionDown
◦ actionEnter
◦ actionExit
◦ actionFocus
◦ actionInvisible
◦ actionKeystroke
◦ actionOpen
◦ actionUp
◦ actionValidate
◦ actionVisible
• charSpacing — The character spacing of the text, expressed as an fLength object
• commitOnSelect — whether the value of the list item is committed when the list item is clicked (true)
Otherwise, when selecting an item in a list, it is only committed when a different form item is selected.
• currentValue — The current selected value of the list
The value is expressed as the index number of the initial itemTextList item to use.
• defaultValue — The value to which to return when the form is reset
The value is expressed as the index of the itemTextList item to use.
• editable — Whether the currently selected value can be edited
• topIndex — The index of the first item to be visible if the list is long
• itemNameList — The names of the text items displayed (comma separated list)
• itemTextList — The values that appear in the list box (comma separated list)
• multiSelect — Whether more than one item can be selected
• sorted — Whether Acrobat should sort the items displayed
• spellCheck — Whether to spell check the editable entries
For more information, see fPDFFormComboBox.
Text Fields
Text fields are rectangular areas where a user can type text. They can be used as text entry fields or as file selectors and password entry fields.
Text fields are represented by the fPDFFormTextField object, which has these properties:
• Actions — Text fields can have actions (fPDFAction objects) associated with many events, using these properties:
◦ actionBlur
◦ actionCalculate
◦ actionClose
◦ actionDown
◦ actionEnter
◦ actionExit
◦ actionFocus
◦ actionFormat
◦ actionInvisible
◦ actionKeystroke
◦ actionOpen
◦ actionUp
◦ actionValidate
◦ actionVisible
• charSpacing — The character spacing of the text, expressed as an fLength object
• currentValue — The string that is currently in the text field
This property can also be used to set the initial value of the text field.
• defaultValue — The value to which to return when the form is reset
• fileSelect — Whether the value in the text field is treated as a filename
• maxChar — The maximum number of characters allowed in the text field
• multiLine — Whether the text field can contain multiple lines of text, otherwise just a single line is allowed
• password — Whether text characters appear as asterisk characters when entered in the text field, to hide their value
• richText — Whether the text in the field can be ‘rich’ and have formatting applied to it
• scrollable — Whether the text field can scroll if the contents exceed the dimensions of the field
• spellCheck — Whether the contents of the text field are checked for spelling
For more information, see fPDFFormTextField.
Signatures
A signature is a field which will take a digital signature in Acrobat.
Signatures are represented by the fPDFFormSignature object. The object has no additional properties.
For more information, see fPDFFormSignature.
Creating PDF Forms
In addition to creating PDF form objects and applying them to the page, it is necessary to tell PTC ALD to include the form objects in PDF output. The fPDFPrinter property fPDFPrinter.generateFormItems ensures they are included. This option is also available through the PDF Options dialog box — see the Generate Form items option on the Page tab.
Creating PDF Forms — Buttons
This sample code creates a button and adds it to the page:
var name = "myButton";
var control = template.content.getPDFFormItem(name);
if (!control) {
control =
template.content.createPDFFormItem(name,
fContent.PDFFORM_PUSHBUTTON);
}
control.pdfName = "b_" + name;
control.borderColor = "Black";
control.highlight = fPDFFormPushButton.HIGHLIGHT_PUSH;
control.caption="Press";
formatting.addPDFFormItem(name,
fFormatting.PLACE_BLOCK,
"30mm",
"10mm");
The button has a caption Press, which meets the minimum functionality requirements for a button. The highlight method mimics a push button.
This sample code will create the same button with icons and a tooltip instead:
var control = template.content.getPDFFormItem(name);
if (!control) {
control =
template.content.createPDFFormItem(name,
fContent.PDFFORM_PUSHBUTTON);
}
control.pdfName = "b_" + name;
control.borderColor = "Black";
control.highlight = fPDFFormPushButton.HIGHLIGHT_PUSH;
control.icon="ButtonUp";
control.iconDown="ButtonDown";
control.iconRollover="ButtonOver";
control.fitMethod = fPDFFormPushButton.FIT_AUTO;
control.tooltip = "Press me";
formatting.addPDFFormItem(name,
fFormatting.PLACE_BLOCK,
"30mm",
"10mm");
In this example, three icons are provided: for the default state, when the button is pressed and when the mouse is over the button. The name provided for each icon refer to a Raster graphic tag in the document.
One use cases for buttons is to provide a tool tip for a link or other text, for example this text:
Some text in a <tooltip tip="This is my tooltip">paragraph
</tooltip > with a tooltip
Some sample code is provided below, to output this text as tooltip over a link:
//Give the tooltip a name
var toolName = "tooltip_" + formatting.counters[100]++;
var toolText = arguments[0].attributes.tip;
//Get the width of the text to apply the tooltip to
var toolTextWidth = new fLength();
toolTextWidth.text = formatting.evaluateXPath('string(.)');
//Get or create the button
var control = template.content.getPDFFormItem(toolName);
if (!control) {
control =
template.content.createPDFFormItem(toolName,
fContent.PDFFORM_PUSHBUTTON);
}
control.pdfName = "b_" + toolName;
control.borderColor = "None";
control.caption = " ";
control.fontHeight = "0pt";
control.display = fPDFFormItem.DISPLAY_NOPRINT;
control.highlight = fPDFFormPushButton.HIGHLIGHT_NONE;
control.tooltip = toolText;
//Add the button
formatting.addPDFFormItem(toolName,
fFormatting.PLACE_INLINE,
toolTextWidth.makeAbsolute(),
"5mm");
//Move the following text back over the button
formatting.addHorizontalKern(new fLength(0 -
toolTextWidth.makeAbsolute()));
formatting.styleSave();
formatting.currentStyle.color = "blue";
This example will give the following when the cursor hovers over the blue text:
Creating PDF Forms — Radio Buttons
When creating radio buttons, ensure they’re in a group. For example, here is a group of button names:
<group name="group1">
<radioButton name="radio1"/>
<radioButton name="radio2"/>
<radioButton name="radio3"/>
<radioButton name="radio4"/>
</group>
You can create a group of radio buttons using code in this format:
var groupName = formatting.evaluateXPath('string(../@name)');
var name=groupName + "_" + arguments[0].attributes.name;
//Get or create the radio button
var control = template.content.getPDFFormItem(name);
if (!control) {
control =
template.content.createPDFFormItem(name,
fContent.PDFFORM_RADIOBUTTON);
}
//Use the group name and button name to create a group using
the '.' to separate control.pdfName = groupName + ".r_" + name;
//Set the radio button properties
control.buttonStyle = fPDFFormRadioButton.STYLE_CIRCLE;
control.currentValue = "Off";
control.borderColor = "Black";
//Output the button
formatting.addPDFFormItem(name,
fFormatting.PLACE_INLINE,
"5mm",
"5mm");
Creating PDF Forms — Check Boxes
You can create check boxes using code in this format:
var name="myCheckBox;
//Get or create the check box
var control = template.content.getPDFFormItem(name);
if (!control) {
control =
template.content.createPDFFormItem(name,
fContent.PDFFORM_CHECKBOX);
}
//Set some properties
control.pdfName = "c_" + name;
control.borderColor = "Black";
control.buttonStyle = fPDFFormCheckbox.STYLE_CROSS;
//Output the check box
formatting.addPDFFormItem(name,
fFormatting.PLACE_INLINE,
"10mm",
"5mm");
Creating PDF Forms — Combo Boxes
When creating combo boxes, the itemTextList and itemNameList values must be in the correct form. In the control stream, they should look like this:
itemtextlist "Monday", " Tuesday", " Wednesday", " Thursday",
" Friday"
itemnamelist "Monday", " Tuesday", " Wednesday", " Thursday",
" Friday"
You can add code that will pass the required values in this format, even if they don’t appear in that way in the original list definition. For example, here is the original list definition:
<comboBox name="combo1" items="Monday, Tuesday, Wednesday,
Thursday, Friday"/>
Use code in this format to ensure that the values from the original list are supplied in the correct structure to be included in the combo box:
var name=arguments[0].attributes.name;
var items = arguments[0].attributes.items.split(',');
//Create a string suitable to pass to list values with
escaped quotes
var listString = "";
for (var i=0; i<items.length; i++) {
var item = items[i];
if (i > 0) listString = listString + ", ";
listString = listString + "\"" + item + "\"";
}
//Get or create combo box
var control = template.content.getPDFFormItem(name);
if (!control) {
control =
template.content.createPDFFormItem(name,
fContent.PDFFORM_COMBOBOX);
}
//Set some properties
control.pdfName = "c_" + name;
control.borderColor = "Black";
//Set the item text and name lists
control.itemTextList = listString;
control.itemNameList = listString;
//Display the combo box
formatting.addPDFFormItem(name,
fFormatting.PLACE_INLINE,
"20mm",
"5mm");
Creating PDF Forms — List Boxes
When creating list boxes, as for combo boxes, the itemTextList and itemNameList values must be in the correct form. For example, here is the original list definition:
<listBox name="list2" items="January, February, March, April,
May, June, July, August, September, October, November,
December"/>
Use code in this format to ensure that the values from the original list are supplied in the correct structure to be included in the list box:
var name=arguments[0].attributes.name;
var items = arguments[0].attributes.items.split(',');
//Process the attribute to create a string with escaped quotes
var listString = "";
for (var i=0; i<items.length; i++) {
var item = items[i];
if (i > 0) listString = listString + ", ";
listString = listString + "\"" + item + "\"";
}
//Get or create the list box
var control = template.content.getPDFFormItem(name);
if (!control) {
control =
template.content.createPDFFormItem(name,
fContent.PDFFORM_LISTBOX);
}
control.pdfName = "c_" + name;
control.borderColor = "Black";
control.itemTextList = listString;
control.itemNameList = listString;
formatting.addPDFFormItem(name,
fFormatting.PLACE_BLOCK,
"30mm",
"30mm");
Creating PDF Forms — Text Box
You can create a text field to support mark-up like the example shown below:
<textField name="text3" text="Here is some text"/>
Use code in this format to create a text box with some text already in it:
var name=arguments[0].attributes.name;
var text = arguments[0].attributes.text;
if (text == undefined) text="";
//Get or create the text box
var control = template.content.getPDFFormItem(name);
if (!control) {
control =
template.content.createPDFFormItem(name,
fContent.PDFFORM_TEXTFIELD);
}
control.pdfName = "t_" + name;
control.borderColor = "Black";
//Set some properties for the text in the box
control.fontHeight = "12pt";
control.richText = true;
control.multiLine = true;
//Set the text in the box
control.currentValue = text;
//Output the text box
formatting.addPDFFormItem(name,
fFormatting.PLACE_BLOCK,
"60mm",
"30mm");
Use code in this format to create a password text box:
var name="pass1";
//Get or create the text field
var control = template.content.getPDFFormItem(name);
if (!control) {
control =
template.content.createPDFFormItem(name,
fContent.PDFFORM_TEXTFIELD);
}
control.pdfName = "t_" + name;
control.borderColor = "Black";
//Set some properties to hide the password entered and
limit the number of characters
control.password=true;
control.maxChar = 10;
formatting.addPDFFormItem(name,
fFormatting.PLACE_INLINE,
"20mm",
"5mm");
Creating PDF Forms — Signatures
Signatures don’t have any properties of their own, so the code to create them is quite simple. For example:
var name="Sig1";
//Get or create the signature
var control = template.content.getPDFFormItem(name);
if (!control) {
control =
template.content.createPDFFormItem(name,
fContent.PDFFORM_SIGNATURE);
}
control.pdfName = "tig_" + name;
control.borderColor = "Black";
//Put the signature on the page
formatting.addPDFFormItem(name,
fFormatting.PLACE_INLINE,
"20mm",
"5mm");
PDF Actions
PTC ALD supports scripting for interactive PDF by allowing you to create PDF actions and include them in PDF output.
Actions in PDF are used to provide interactivity such as bookmarks, scripted actions, and opening of URLs, especially when working with multimedia content, 3D images, and PDF forms. Actions are called by form objects and other events in Acrobat.
Actions are represented in PTC ALD documents as control streams held in tags of type PA. You can access them either as streams (read, write, and so on) or through their own object fPDFAction in the Formatting Object Model. The content and function of the action is dependant on the type of action the tag will implement.
PDF Action Types
PTC ALD supports nine types of action through the fPDFAction.actionType property. The allowed values of this property are listed on the fPDFAction.ActionTypes constant:
• fPDFAction.TYPE_JAVASCRIPT = 0 — Runs JavaScript within Acrobat
The contents of the JavaScript function are specified in the fPDFAction using the function property.
See PDF Actions — JavaScript section in this topic.
• fPDFAction.TYPE_FORMITEM = 1 — Hides or shows a PDF form item (such as a button)
If this type of action is being used, the fPDFAction.state property is used to determine the state of the annotation (hide or show) specified by the fPDFAction.itemName property.
• fPDFAction.TYPE_LAYER = 2 — Hides or shows a PDF layer
If this action type is being used, the fPDFAction.state property value is used to determine whether the layer is visible or not. The layer is specified by the fPDFAction.itemName property.
See PDF Actions — Layer section in this topic.
• fPDFAction.TYPE_MENU = 3 — Executes a named menu item inside Acrobat
The menu item name is specified by the fPDFAction.itemName property.
See PDF Actions — Menu section in this topic.
• fPDFAction.TYPE_RESETFORM = 4 — Resets the whole form back to the default values set on each of the form items
When using PDF forms, a reset button is sometimes required.
See PDF Actions — Form Reset section in this topic.
• fPDFAction.TYPE_SUBMITFORM = 5 — Submits a PDF form
In order to submit a PDF form, this action must be applied to something, for example an event or a button. The form information is sent to the URL specified by the fPDFAction.arguments property.
See PDF Actions — Form Submit section in this topic
• fPDFAction.TYPE_GOTO = 6 — Tells Acrobat to go to an item such as a bookmark property
The name of the bookmark is specified using the fPDFAction.itemName property. If the action is intended to open an external document, the location path is provided using the fPDFAction.arguments property.
See PDF Actions — Go To section in this topic.
• fPDFAction.TYPE_URI = 7 — Opens a URI
The URI is specified by the fPDFAction.itemName property.
See PDF Actions — URI section in this topic
• fPDFAction.TYPE_DOCUMENTOPEN = 8 — Sets up a JavaScript script to be run when the PDF is opened in Acrobat
The script to be run is specified by the fPDFAction.function property.
The fPDFPrinter object has a property to specify the fPDFAction to set for the output PDF — fPDFPrinter.actionDocumentOpen. This option is also available through the PDF Options dialog box — see the Document Open option on the Page tab.
See PDF Actions — Document Open section in this topic
Creating and Using PDF Actions
Actions are PTC ALD tags that contain the options for creating PDF actions. The different types of action determine their use, but the general pattern of creation and use is common.
To create a new action, use code in this format:
var action;
action = template.content.getPDFAction("myAction");
if (!action) {
action = template.content.createPDFAction("myAction");
action.actionType = fPDFAction.TYPE_JAVASCRIPT;
}
In this example, the action tag is created, leaving it to be used as an fPDFAction object.
PDF Actions — JavaScript
JavaScript actions (and Document Open actions) contain JavaScript code, written against the Acrobat JavaScript API, that is intended to be run on an event such as button press. The JavaScript is contained in braces after the function keyword in the control stream.
To create this code, use code in this format:
//Declare the function to attach to the action
var f = function() {
var docTitle = this.title;
app.alert("Doc title is " + docTitle);
}
//Create the action
var action;
action = template.content.getPDFAction("myJSAction");
if (!action) {
action = template.content.createPDFAction("myJSAction");
action.actionType = fPDFAction.TYPE_JAVASCRIPT;
}
action.function = f;
This creates this code in the control stream:
type javascript
state 0
function {
var docTitle = this.title;
app.alert("Doc title is " + docTitle);
}
PDF Actions — Layer
Layer actions are used to activate and deactivate PDF layers. The fPDFAction.state property specifies whether the layer specified by the fPDFAction.itemName property should be visible.
To create the action, use code in this format:
//Create the action
var action;
action = template.content.getPDFAction("myLayerActionON");
if (!action) {
action = template.content.createPDFAction("myLayerActionON");
action.actionType = fPDFAction.TYPE_LAYER;
}
action.itemName = "myPDFLayer";
action.state = 1;
PDF Actions — Menu
Menu actions allow the PDF to associate Acrobat menu actions with other events, including form field events.
To create the action, use code in this format:
//Create the action
var action;
action = template.content.getPDFAction("myPrintAction");
if (!action) {
action = template.content.createPDFAction("myPrintAction");
action.actionType = fPDFAction.TYPE_MENU;
}
action.itemName = "Print";
The action.itemName property carries the name of the menu action in Acrobat.
| Menu actions differ between versions of Acrobat. |
PDF Actions — Form Reset
Form reset actions set the contents of form fields back to their default values. When using these actions, ensure that the form fields are all created in the same group. You can do this by specifying their name using the group.fieldName type of pattern, where the group precedes the full stop. The group to reset is then provided by the fPDFAction.itemName property.
To create the action, use code in this format:
//Create the action
var action;
action = template.content.getPDFAction("resetFormAction");
if (!action) {
action = template.content.createPDFAction("resetFormAction");
action.actionType = fPDFAction.TYPE_RESETFORM;
}
action.itemName = "form";
The action.itemName property carries the name of the group for the form fields (form).
PDF Actions — Form Submit
Form submission sends the contents of form fields to a URL specified in the submit action. The group of form fields to collect are specified using the fPDFAction.itemName property. The target URL is defined by the fPDFAction.arguments property.
To create the action, use code in this format:
//Create the action
var action;
action = template.content.getPDFAction("submitFormAction");
if (!action) {
action = template.content.createPDFAction("submitFormAction");
action.actionType = fPDFAction.TYPE_SUBMITFORM;
}
action.itemName = "form1";
action.arguments = "mailto:test@ptc.com?subject=TEST";
PDF Actions — Go To
Go to actions allow users to jump to a bookmark or location inside or outside the current document.
To create the action, use code in this format:
//Create the action
var action;
action = template.content.getPDFAction("myBookmarkAction");
if (!action) {
action = template.content.createPDFAction("myBookmarkAction");
action.actionType = fPDFAction.TYPE_GOTO;
}
action.itemName = "BookTitle";
This sample specifies an action to go to the bookmark BookTitle in the current PDF.
To go to a bookmark in an external PDF, use code in this format:
//Create the action
var action;
action =
template.content.getPDFAction("myRemoteBookmarkAction");
if (!action) {
action =
template.content.createPDFAction("myRemoteBookmarkAction");
action.actionType = fPDFAction.TYPE_GOTO;
}
action.itemName = "BookTitle";
action.arguments = "F:\\Work\\ACTIONS demo REMOTE.pdf";
action.state = 1;
The fPDFAction.arguments property provides the location of the remote file. The fPDFAction.state property value of 1 tells Acrobat to open the remote PDF in a new window.
PDF Actions — URI
URI actions allow the user to open a URI in a browser.
To create the action, use code in this format:
var action;
action = template.content.getPDFAction("testURIAction");
if (!action) {
action = template.content.createPDFAction("testURIAction");
action.actionType = fPDFAction.TYPE_URI;
}
action.itemName = "https://www.ptc.com/";
The fPDFAction.itemName property specifies the URI to open.
PDF Actions — Document Open
Document Open actions are run when the document is opened. With this type of action, JavaScript code can be run when Acrobat opens the document, for example to perform some automated tasks or to create some global functions to be used in other actions. Document Open actions are only ever JavaScript functions.
To create the action, use code in this format:
var f = function() {
function myTestDocFunction() {
app.alert("YOU PRESSED IT", 1, 0, "TEST ALERT");
}
}
var action;
action = template.content.getPDFAction("myDocumentAction");
if (!action) {
action = template.content.createPDFAction("myDocumentAction");
action.actionType = fPDFAction.TYPE_DOCUMENTOPEN;
}
action.function = f;
The function in the action control stream declares a new global function in Acrobat to pop open an alert.
To subsequently call the function from another JavaScript action, if required, use code in this format:
//Create the action
var f = function() {
myTestDocFunction();
}
var action;
action =
template.content.getPDFAction("testDocumentActionAction");
if (!action) {
action =
template.content.createPDFAction("testDocumentActionAction");
action.actionType = fPDFAction.TYPE_JAVASCRIPT;
}
action.function = f;
The JavaScript action, possibly attached to a button, calls the global function declared in the Document Open action.
| You must set the PDF option to use your action as the Document Open action in your PDF: • fPDFPrinter.actionDocumentOpen • Document Open option on the Page tab of the PDF Options dialog box |
Bookmarks and Interactive PDF
PTC ALD supports four bookmark types that help interaction in PDF.
The types are listed on the fBookmark.BookmarkTypes constant:
• fBookmark.TYPE_PDF_3DVIEW = 3 — A reference to a view of a 3D graphic in the PDF
See Bookmarks – 3D View section in this topic.
• fBookmark.TYPE_PDF_MEDIA = 4 — A reference to a media object in the PDF
See Bookmarks — Media section in this topic.
• fBookmark.TYPE_PDF_JAVASCRIPT = 5 — A JavaScript function to run
See Bookmarks — JavaScript section in this topic.
• fBookmark.TYPE_PDF_ACTION = 6 — A PDF action to run
See Bookmarks — PDF Action section in this topic.
These types are used together with properties fBookmark.remoteFile and fBookmark.remoteName to drive interactive tasks.
Bookmarks – 3D View
The 3D View bookmark type allows you to set the view of a 3D object on the same page in the PDF. You need to know both the PDF name of the 3D object and the name of the view to which to change.
To create a bookmark and link using an attribute value to provide the view name, use code in this format:
var viewName = arguments[0].attributes.name;
//Create the bookmark
var bookmarkName = "bm_" + viewName;
var bookmark;
bookmark = template.content.getBookmark(bookmarkName);
if (!bookmark) {
bookmark = template.content.createBookmark(bookmarkName);
}
bookmark.bookmarkType = fBookmark.TYPE_PDF_3DVIEW;
bookmark.remoteFile = "my3D";
bookmark.remoteName = viewName;
//Create a link to the bookmark
formatting.bookmarkLinkStart(bookmarkName, "red");
The fBookmark.remoteFile property specifies the 3D object on the page and fBookmark.remoteName specifies the view name within the 3D graphic.
Bookmarks — Media
Media bookmarks are used to send commands to the Flash players being used to display video or audio content. PTC ALD includes some Open Source media players, which can be used.
To embed a video using the VPlayer.swf Flash player from Media9, use code in this format:
var myVideo = template.content.getRaster("myVideo");
var myPoster = template.content.getRaster("poster");
formatting.addMedia(myVideo,
fFormatting.PLACE_BLOCK,
fFormatting.SCALE_ABSOLUTE, "100mm",
fFormatting.SCALE_ABSOLUTE, "60mm",
fFormatting.BESTFIT_NONE,
fFormatting.BESTFIT_NONE,
false,
"myVideo",
"",
"VPlayer.swf",
myPoster);
In this example, no Flash variables are sent and a ‘poster’ image is used. The PDF name of the video object is myVideo — this information is needed to address that object from the bookmark.
To create a bookmark that sends a play() message to the Flash player, use code in this format:
//Create the bookmark
var bookmarkName = "mediaPlay_Bookmark";
var bookmark;
bookmark = template.content.getBookmark(bookmarkName);
if (!bookmark) {
bookmark = template.content.createBookmark(bookmarkName);
}
bookmark.bookmarkType = fBookmark.TYPE_PDF_MEDIA;
bookmark.remoteFile = "myVideo";
bookmark.remoteName = "play()";
//Create a link to the bookmark
formatting.bookmarkLinkStart(bookmarkName, "red");
formatting.write("PLAY");
formatting.bookmarkLinkEnd();
The fBookmark.remoteFile property points to the video object using its PDF name. The fBookmark.remoteName property is then used to specify the command to send.
Bookmarks — JavaScript
A JavaScript bookmark executes a small chunk of JavaScript in the PDF when the link is clicked. To execute more JavaScript, use a PDF action.
For more information, see PDF Actions in this topic.
To create the bookmark and link, use code in this format:
//Create the bookmark
var bookmarkName = "js_Bookmark";
var bookmark;
bookmark = template.content.getBookmark(bookmarkName);
if (!bookmark) {
bookmark = template.content.createBookmark(bookmarkName);
}
bookmark.bookmarkType = fBookmark.TYPE_PDF_JAVASCRIPT;
bookmark.remoteFile =
"{var docTitle = this.title;\napp.alert(\"Doc title is \" + docTitle);}";
//Create a link to the bookmark
formatting.bookmarkLinkStart(bookmarkName, "red");
The JavaScript to be run is provided in the fBookmark.remoteFile property. PTC recommends using this method only for small snippets of JavaScript.
Note the braces {} around the code and the escaped characters \”.
Bookmarks — PDF Action
PDF actions can be used for performing in a PDF such as running scripts, submitting forms, and opening URIs.
To create an action, the associated bookmark, and a link, use code in this format:
//Create the action
var action;
action = template.content.getPDFAction("testURIAction");
if (!action) {
action = template.content.createPDFAction("testURIAction");
}
action.actionType = fPDFAction.TYPE_URI;
action.itemName = "https://www.ptc.com/";
//Create the bookmark
var bookmarkName = "act_Bookmark";
var bookmark;
bookmark = template.content.getBookmark(bookmarkName);
if (!bookmark) {
bookmark = template.content.createBookmark(bookmarkName);
}
bookmark.bookmarkType = fBookmark.TYPE_PDF_ACTION;
bookmark.remoteFile = "testURIAction";
//Create a link to the bookmark
formatting.bookmarkLinkStart(bookmarkName, "red");
The URI can come from an attribute value.
PDF Assets
When creating interactive PDF, it is sometimes necessary to include resources which aren’t declared as part of the template and formatting code. For example, a specific skin for playing video might be required, or an audio file that isn’t declared inline is called from scripting.
PTC ALD provides a tool for creating a list of resources and including them in the PDF as assets.
Assets
PDF assets are supported by these objects:
• A list of assets is represented by the fPDFMediaAssets object and the control stream tag of type PM.
Each fPDFMediaAssets object (PM tag) provides a list of the assets to include in the output PDF. The values specify the PDF name of the object and a path to the resource.
• The fContent.pdfMediaAssets property provides a list of these tags within the document.
• The fContent.getPDFMediaAssets() and fContent.createPDFMediaAssets() methods allow you to create and work with the objects.
To create an assets list, use code in this format:
var assetList;
assetList = template.content.getPDFMediaAssets("myAssets");
if (!assetList) {
assetList = template.content.createPDFMediaAssets("myAssets");
}
assetList.assets.test = "D:/myFile.jpg";
This creates this line in the myAssets.pm tag:
test=D:/myFile.jpg
Include Assets in PDF
A PDF option specifies the assets tag that defines the assets to include in PDF output. The Load external assets option is provided in the Page tab of the PDF Options dialog box:
PDFLib, PTC ALD’s PDF library, validates the items in the assets list. If assets are incorrectly declared or do not exist, an error is raised and the PDF may not be created.
