Adding bookmarks to a Form

Since Designer ES3 came out we have been able to add PDF bookmarks to our forms.  This adds a useful navigation feature and hopefully makes the form more accessible. 

Although Designer would create bookmarks there was no support for them within the Designer UI, you had to go into the XML Source view and enter elements directly, so something like;

<extras name="bookmark">
  <text name="name">Bookmark</text>
  <text name="color">0,0,0</text>
  <text name="style">normal</text>
  <text name="action">gotoPage</text>
<extras>

Radzmar has since written a great macro to generate these elements, http://thelivecycle.blogspot.de/2011/09/xfa-bookmarks.html.

As described in the Adobe Designer help the values for action 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.

The gotoPage action seems to go to the top of the page that contains the form control with the bookmark.  This can be confusing for a user if the control is not at the top of the page.

The setFocus action on a subform seems to behave the same as gotoPage and on a field that can receive focus will set focus to that field, but it will also position the field in the middle of the display area, which I didn't like either.

This left me with the runScript action, which I thought I could use my Using Doc.scroll Method In Livecycle Designer method to navigate the form more accurately.  The first thing I found was that the bookmark script runs in the context of the Doc object.  This meant to reference my script object and form controls I had to prefix them with xfa.form.form1, where form1 is the top most subform of my form.  The next thing I found was that event.target did not return the Doc object as it does in a LiveCycle event.  This was not a great problem as the Doc object was my context so I could pass it to my scrollTo method.  Now my bookmark elements look like;

<extras name="bookmark">
  <text name="name">Bookmark</text>
  <text name="color">0,0,0</text>
  <text name="style">runScript</text>
  <text name="action">xfa.form.form1.XFAUtil.scrollTo(xfa.form.form1.Body.PartC, undefined, this);</text>   
<extras>
 
The scrollTo method signature has now changed to;  

/** Scrolls the specified control to the top of the current view and optional sets focus the the specified control.

 *  @param {form object} target   (required)    -- the control to place at the top of the current view.
 *  @param {form object} setFocus (optional)    -- the control that receives focus.
 *  @param {Doc object}  doc      (optional)    -- the Doc object (required when used in a bookmark).
 */
function scrollTo(target, setFocus, doc)
  

Samples

Here are three samples;

• Using the scrollTo method SetFocusBookmarks.pdf
• Using the gotoPage action GotoPageBookmarks.pdf
• Using the setFocus action SetFocusBookmarks.pdf

Remember that gotoPage and setFocus navigate to the top of the page so there may be no movement at all if you click between two bookmarks that are close together.

Testing

When testing bookmarks in LiveCycle Designer you need to be able to get to the navigation panels that are normally display on the right side of Adobe Reader.  To view these in preview mode press the ESC key.  This will then show the Acrobat toolbar and the navigation panels,  but not there doesn't seem to be the Tools menu available. 

You can also press Crtl + Shift + F5 to open the navigation panels and set focus to them directly.