Create Bookmarks in XFA Forms

There is a growing demand from our customers to extend the bookmark capability of pdf documents to XFA also. In LiveCycle Server ES3, we are introducing the support for authoring bookmarks in XFA Forms. It is also available in LiveCycle Server ES2.5 via a patch.  This post will show how one can author bookmark in an XFA form and also how the final pdf does look like.

Authoring

You can define bookmarks at any of the XFA containers like subform, field or area.

The XFA processor starts processing bookmarks based on the following markup definition, under any of the valid container
elements. You can also specify multiple bookmarks for the same container. However, since only one extras tag is allow under any container markup, one can always wrap multiple extras tags inside another extras tag. LiveCycle supports up to two level of nesting for extras tags.

<subform> <!-- Any container element like subform, field or area-->
	<extras name="bookmark">
		<text name="name">ANY_NAME</text>
		<text name="color">0,0,0|R,G,B</text>
		<text name="style">normal | italic | bold | bold-italic</text>
		<text name="action">gotoPage | setFocus | runScript</text>
		<text name="script">ANY_FORM_LEVEL_SCRIPT</text> <!-- Javascript only. No formcalc support -->
	<extras>
	...
</subform>

Here is the description for various mark up parameters (Table below).

To author bookmarks in XFA forms:

1) You can use the attached Designer macro. The macro has been written for Designer versions ES2 or later. For more information, see the blog on Design macros.

2) Download the bookmark macro from collateral.

When you invoke the macro, a dialog box  (as shown above) is displayed. In the dialog box, specify all the bookmark  parameter values.

Document generation

Once a bookmark has been authored, generate the PDF document. The bookmarks generated are available in dynamic and static documents. Bookmarks are compatible with Reader 9.0 and 10.0. You can use bookmarks in any XFA version document.

The bookmark will be generated in the same hierarchy as it is defined in the XFA Form design.

<subform name="root">
    <extras name="bookmark">
		<text name="name">parent1</text>
    </extras>
	....
   <subform name="level1">
		<extras name="bookmark">
			<text name="name">child1</text>
		</extras>
		...

		<subform name="level2">
			<extras name="bookmark">
				<text name="name">grand1</text>
			</extras>
			...

		</subform>
	</subform>

   <subform name="level1">
		...
		<subform name="level2">
			<extras name="bookmark">
				<text name="name">grand2</text>
			</extras>
			...

		</subform>

    </subform>
</subform>

For example, for the above form design, the bookmarks will be generated in the following hierarchy:

bookmarkRoot
	parent1
		child1
			grand1
		grand2

Limitations

1. To ensure compatibility with existing Reader versions, some capabilities are limited.
2. For security reasons, a user can change the value of any bookmark element/parameter except action and script.
3. For dynamic forms, you cannot make changes using the script – LiveCycle Server will always generate bookmarks based on what user has specified in the template. For example, assume that a form contains a select-one-subform type subformset, and the author has defined bookmarks for all the subforms of the subformset. In such a scenario, for dynamic PDF documents, LiveCycle Server will generate bookmarks for all subforms, and for static PDF documents, LiveCycle Server will generate one bookmark, depending on which subform gets selected based on user input.
4. Bookmarks defined for XFA containers which form master page content are ignored
5. Bookmarks specified on containers other than subform, area, field, and draw objects are not supported, and may result in unpredictable behavior.
6. Bookmarks with value runScript for the action parameter/element are disabled, if the rendered PDF is archived.
7. If an interactive form with bookmark is flattened using LiveCycle Output Service, it will not retain the bookmarks that somebody has inserted after the generation of PDF using Acrobat or Assembler.