Stefan Cameron on Forms
Building intelligent forms using Adobe LiveCycle Designer

Archive for September, 2008

LiveDocs JavaScript API for Acrobat 9

If you’re like me, you’re still waiting for the PDF version to be posted since Acrobat 9 shipped last Summer (seems strange to say “last Summer” already!). In the mean time, I found the LiveDocs version online (once the page loads, click on “JavaScript > JavaScript for Acrobat API Reference > JavaScript API” in the table of contents on the left hand side). It’s not as “rich” as the PDF version but it’ll do for now.

Posted by Stefan Cameron on September 29th, 2008
Filed under Acrobat,AcroForm Objects,Scripting

Restoring the State of your Form

This is a guest post from my colleague Anatole Matveief who works on XFA-related features in Acrobat. In this post, Anatole introduces a really cool feature available since Acrobat 8.0 and Designer 8.0 called “formstate” which allows you to persist non-data related changes to your forms and restore them when the form is subsequently re-opened.

Minimum requirements (to use the forms in this tutorial): Acrobat Standard 8.0, Designer 8.0


In Acrobat and Designer 8, Adobe introduced the concept of saving a form’s state in XFA Forms. First a quick review: An XFA Form file usually contains a template and data. When the form is opened, the template instructs the runtime engine (like Acrobat, Reader or the server) how to create the Form DOM given a set of data. The user can then interact with the form. After the user fills the form, Reader or Acrobat will save the data. When the form is then reopened, Acrobat or Reader will take the saved data and once again do the merge to create the form.

However, many customers encountered a problem: They wanted to save or persist an element of the form that was not bound to the data. For example maybe in the process of filling the form, some captions changed, or the color of fields changed. Or maybe the number of instances in an unbound subform changed. Since these changes were not bound to data they would not be restored the next time the form was opened, since only the data was saved.

In Acrobat 8 this changed. Now by default, the state of the form, or its formstate is saved. This means that all those changes in the form that happened at runtime that weren’t bound to data will be restored next time the form is opened.

Automatic State Restoration

As an example, open formstate-auto.pdf in Acrobat. Click on the “Change Country” button once or twice, which runs a script to change numerous properties on the form to make it into a US form or Canadian form. These include colors, captions, and the number of instances in a subform, values, and the items in a list. Now save the file. When you open the form again, the captions, colors number of instances, unbound field values, and list items will be as they were when you saved. This would not be the case prior to Acrobat 8.

Here is the setting in Designer 8.0 that controls this automatic form state saving:

In the XFA Language it’s the property in the root subform called “restoreState”. The default value is:


Now, as with most good things in life, it’s not quite so simple. Now that form state is restored, we open up a potential security issue. What if someone gets your form, changes a caption from “Address” to “Password”, then changes another caption to read “SSN”? When they save the file, the next time your intended customer opens the file they’ll see the spoofed captions, not the captions the original author intended! That is, the author’s intent has been compromised. So how do we get around this issue?

Manual State Restoration

There is now also the option to restore formstate manually, specified in the XFA Language on the root subform as:


Or in Designer by selecting the second radio as shown here:

What does this mean? This means that the form author decides, through script, what parts of the form will be restored when the file is reopened. In fact, for certified forms, this is the only way to restore form state. Certifying an XFA Form is disallowed if the formstate’s restoreState is set to “auto”.  (If for some reason the form does get certified, by a previous version of a product that doesn’t enforce this rule for example, Reader or Acrobat will not restore the formstate on open.) First let’s see an example using a form with restoreState=”manual”.

Open the file formstate-manual-noscript.pdf. Click the “Change Country” button once or twice, save, close and reopen the file. Notice that only values are restored. The properties changed by script are not. The exception to this rule are the unbound field values and the number of subform instances, as shown on the form. This means that even for restoreState=”manual”, unbound field values (where bind=”none”) and subform instances are restored.

So what do you do if you want to manually restore the form state? Thankfully, there is a simplified method to doing this by using script.

Open the file formstate-manual-script.pdf. Follow the same steps as before. When you reopen the file you’ll see that the entire state is restored. This is accomplished by placing this script on the Form:Ready event of the root subform:

// this script restores all the deltas manually.
var oList = this.getDeltas();
for (i=0; i < oList.length; i++)
    var oDelta = oList.item(i);

You can also be more selective about which fields, and even which properties within those fields you restore.

Open the file formstate-manual-script-partial.pdf. Follow the same steps as before. When you reopen the file you’ll see that only parts of the state are restored. This is accomplished by placing different scripts on different fields, and by not placing some scripts at all. For instance the form places the following script on the listbox to restore only the list items (it does not restore the color):

// this script restores the delta for the "items" (in XFA,
//  it's the <items> element) property of this listbox only.
// Ie the color is not restored but the items in the list are.

var oListDelta = this.getDelta("items");

You can use a similar script to restore only certain attributes of the field.

Technical Note: One important point here is that the script runs on the opening of the form when the formstate is being restored. The entire state of the form is always saved when the file is saved. But Acrobat/Reader will always check the script to restore only the parts of the form state that are specified. Why isn’t there a script to choose what part of the formstate to save? That wouldn’t be secure: A malicious person could intercept the form in transit, and inject additional information in the formstate before it reached its target. However if the script runs when the form is opened and state restored, then the script will ignore any section the author did not intend to be restored. Of course the security assurance works only if the form is certified, since certification ensures the integrity of the template, where the formstate restore script (which you implement) lives. Ie, the script which does the state restoration is covered by the certification, so we can be sure the script wasn’t tampered with.


The new formstate feature:

  • allows saving state in the form where that state is not bound to data — which is a good thing since you don’t necessarily want to “mess up” your data, which may need to comply to an XML schema, with formstate-related information.
  • has an automatic mode which just restores the entire state from the last time the file was saved.
  • has a manual restore mode, for added security. This manual mode:
    • is required if you plan on certifying your form
    • is made easier by the use of deltas
    • allows you to pick and choose exactly what parts of the formstate to restore.

Posted by Stefan Cameron on September 29th, 2008
Filed under Acrobat,Designer,Scripting,Tutorials,XFA

Tab Order Revamped

Back when I announced that Designer 8.2 and Acrobat 9 had shipped, I mentioned that there had been a “major tab ordering UI update”. The Team knew that something had to be done to address all the issues you had been experiencing (it follows that it was the most requested feature on my Designer 8.2 Featur-O-meter) and I think they really delivered!

Make it so

I think one of the most significant improvements to the functionality is that what you set in Designer is what you get in Acrobat. In the past, given certain circumstances, the order you set in Designer was not necessarily the order you would get in Acrobat. Designer 8.2 and Acrobat/Reader 9, together, fix that issue.

For example, this view shows the new Tab Order palette where tab order is set to “Automatic” which means the order depends largely on the visual placement of fields on the form, from left to right and top to bottom:

In this next view, I’ve simply moved the City field below the Country field. As you can see in the tab order list, City is now last in tab order simply because it’s positioned below the Country field (and it’s also highlighted in the list because I have it selected on the canvas):

Tab Order palette

The Tab Order palette is how you work with tab order in Designer 8.2. While there is still a “tab order mode”, you no longer (attempt to) set the order by entering tab order mode and clicking on fields on the canvas in the order you want tab order to be set. Instead, you do everything from the palette (sequence numbers are still displayed over the fields and you can still click on them to select their corresponding item in the tab order list within the Tab Order palette but the order itself is no longer set by clicking on the canvas).

Before we go any further, there’s some extra visual aids for tab order which you’ll want to turn-on (if anything, they’re really cool). In the “Tools menu > Options command > Tab Order tab”, set the “Display Additional Visual Aids for Tab Order” setting:

Now select the Tab Order palette (“Window menu > Tab Order command”) and you’ll automatically be entered into “tab order mode” (if not, click on the “Show Order” button on the palette):

Once this is done, set the order to “Custom” so that you can set the order you want.

To get a feel for what the order is (now that you’ve enabled the “additional visual aids”), you can simply mouse-over the fields on the canvas:

(In the above screen shot, my mouse is hovering over the City field.)

Setting the order

Using the object list in the Tab Order palette, the order can be set in many different ways:

  • drag and drop the items in the list
  • multi-select items in the list and drag & drop them
  • make a selection and use the arrow buttons to move them around
  • select one item and hit the F2 key to manually set its sequence number
  • make a selection (either with the mouse or the keyboard) and change the order by holding the Control key while using the up/down arrow keys
  • cut and paste a selection using the items in the palette menu

Form Fragments

The Tab Order feature also handles form fragments gracefully and treats them as “white blocks”. Following my address block example, if you make a fragment out of the City, State and Zip fields, that object is now treated as a single object. The tab order can’t be changed from the reference to the fragment (i.e. the tab order of the fields inside the fragment can’t be changed from the form that references the fragment) but it can be changed around it:

In order to change the tab order inside the fragment, you’ll need to edit the tab order in the fragment itself.

Text Objects

Finally, the revamped Tab Order feature is also capable of handling text objects. This comes in handy especially when you have a hyperlink somewhere in a text object and you want to control where, in the tabbing sequence, that focus jumps to the hyperlink and where it goes to afterward.

In order to set the tab order of a text object, you must uncheck the “Tools > Options > Tab Order > Only Show Tab Order for Fields” option in the Tab Order Properties Dialog (checked in the linked screenshot: you must uncheck it).

After applying the above setting, the Tab Order Palette will show all form objects, not just fields.

Apr 3, 2010 — Added “Text Objects” section

Posted by Stefan Cameron on September 22nd, 2008
Filed under Acrobat,Bugs,Designer,Form Fragments,Tutorials

Dot Leaders

Designer 8.2 and Acrobat 9 now support adding dot leaders in XFA forms. This feature is typically used when creating an index of some sort (like a table of contents) in order to lead the reader’s eye from one piece of information to another across the page.

Stephanie Legault, from the Adobe LiveCycle Designer Team, has produced a short video that explains how to use the new Dot Leader feature. Check it out — it’s very informative!

Posted by Stefan Cameron on September 18th, 2008
Filed under Designer,Tutorials

Hyphenation Video Tutorial

Hyphenation can greatly enhance the appearance of your forms, especially when the text is written in a language that tends to have long words like German.

Alex Kalaidjian, from the Adobe LiveCycle Designer Team, has put together a great video tutorial on the new feature. It’s definitely worth the 5 minutes to learn about it.

Note that the hyphenation settings under the “Tools > Options” menu represent default hyphenation settings for all new forms while the settings under “File > Form Properties” represent settings for a particular form.

Posted by Stefan Cameron on September 16th, 2008
Filed under Designer,Tutorials