Making a Table of Contents

One of the hottest topics on the “Designer Forums”:http://www.adobeforums.com/cgi-bin/webx/.3bb7d189 these days seems to be methods by which one can add a table of contents to their form. Since there are many different ways to achieve this, I thought I would post a little sample to demonstrate how this can be done.

Of primary concern when adding a table of contents to your form is ensuring that the links provided to the form’s various pages/sections remain valid at all times. Static forms whose page set never changes don’t really need to worry about this but dynamic forms do. That is, regardless of whether content pages are added, re-ordered or even deleted from your dynamic form, you need to ensure that when a TOC link is clicked, the user is taken to the correct page pertaining to the topic they selected.

The best way of ensuring that TOC links don’t get broken as a result of changes to the form’s pages is by using layout information provided by the *XFA Layout Model*. This model provides information such as an object’s actual dimensions (width/height), the page on which it is located as well as a few other interesting pieces of information.

By using the

bc. xfa.layout.absPage

we’re able to get the page number on which an object is currently located, taking into account the various pages which may have been inserted or removed in-between the TOC page and the page in question. Taking that page number and assigning it to the

bc. xfa.host.currentPage

property then sets the current page to the one on which is located the object in quetsion.

“Download Sample [pdf]”:http://blogs.adobe.com/formbuilder/samples/TOCUsingXFALayoutModel.pdf

*Minimum Requirements:* Designer 7.x, Acrobat 7.x.


h2. page or absPage?If you’re looking at the “Adobe XML Form Object Model Reference”:http://www.adobe.com/devnet/livecycle/designing_forms.html (page 188), you’ll notice that there are actually two methods which provide the number of the page on which an object is currently located:bc. xfa.layout.page // returns a 1-based numberandbc. xfa.layout.absPage // returns a 0-based numberSince we need to set that information to thebc. xfa.host.currentPageproperty and that it expects a *zero-based* page number, it’s simpler to use the _absPage_ version.h2. The Layout:Ready EventWhen using the XFA Layout Model, it’s very important to realize that the information it contains is constantly updated whenever something on your form changes that may affect an object’s positional data. Therefore, you must ensure that the form’s layout has been updated before you attempt to obtain information from it about a particular object.For TOC page fields that display the page number on which a topic is currently located, it’s easier to simply put script in the *Layout:Ready* event of that field since this event is fired every time the form’s layout process is complete. Therefore, whenever pages get added, re-ordered or even removed, this event is fired and the fields are updated with the most current information.Alternatively, if you’re writing script in another event and you need to know whether information in the XFA Layout Model is up-to-date, you can use thebc. xfa.layout.readyboolean property which returns _true_ if the form’s layout process is complete and _false_ otherwise.h2. Links in XFAA lot of customers have asked me how to create links in XFA. The concept of links is essential to a TOC page since it’s sole purpose is to provide links to various pages within a document.Unfortunately, XFA 2.4 (used by Designer 7.1+ and Acrobat 7.0.5+) doesn’t have the ability to describe the equivalent of an HTML anchor (link) or a PDF Bookmark. Therefore, we’re forced to cheat a little. One way of doing that is by using a transparent button overlaid on top of another object (text or field) which displays information about a link. You could also use a button directly by using its caption to describe what it links to but you’ll most likely run into text alignment problems if you need the button’s caption to be anything but centered.My sample uses the former solution and places transparent buttons over the fields which display information about the link (title and current page number). You can make a button transparent by removing its caption text and customizing its Appearance property (on the Object palette’s Field tab) to remove its borders and fill.Finally, the z-order (or top-down order in the Hierarchy palette) of the transparent buttons used as links with respect to the fields over which they’re to be located is very important in that the buttons must be _above_ (higher in z-order or lower in the Hierarchy palette) the fields to which they pertain. One way to do this is by selecting a button and choosing the “Layout | Bring to Front” menu item. This will ensure that when you click on the topic, you’ll click on the link button rather than the field which describes the topic.