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.


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 -->

Here is the description for various mark up parameters (Table below).
parameter description
name The name of the bookmark that will appear in the bookmark pane. If it is not specified, the bookmark will not be generated.
color The color in which the bookmark name is rendered. The color parameter should be indicated in the RGB scheme. For example, to insert a bookmark in red color, this parameter should be specified as 255,0,0. The default value for the color parameter is 0,0,0 (black).
style The style in which the bookmark name is rendered. The default value of the style parameter is none. Other values can be bold, italic, or bold-italic.
action The action that is performed when the bookmark is clicked, Values that can be used for the action parameter are: 

  • gotoPage: This is the default value. Focus is shifted to the page where the parent subform starts.
  • setFocus: Can be used when the parent container is a field. Sets the parent field in focus.
  • runScript: Triggers JavaScripts to be run. (This value is ignored in PDF/A documents)
script Relevant, when the value of the action parameter is set to runScript. Supports only JavaScript, that contains script objects present in the document scope.


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>
   <subform name="level1">
		<extras name="bookmark">
			<text name="name">child1</text>

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


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



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




  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.












5 Responses to Create Bookmarks in XFA Forms

  1. Girish says:

    I have a xdp with 3 subforms, but when I render the xdp I do not see any bookmarks
    Can you please help

    • Raga says:

      Yeah sure. Did you insert any bookmark into that as just having subform wouldn’t generate any bookmarks.? You need to insert bookmark structure under those nodes like specified in the blog.

  2. Pingback: Other Blogs to Watch « FormFeed

  3. Girish says:

    I did get the bookmarks to show up
    Another question- the customer would like to generate a TOC something similar to what Word generates. would that be possible using this feature?

  4. Pingback: PDF Document Accessibility – Q & A | SSB BART Group

Leave a Reply

Your email address will not be published. Required fields are marked *