XFA 3.0: List of Invalid Fields

This post describes the last of the enhancements targeting form authoring usability in XFA 3.0/Acrobat 9.1.

The subform object has a new script method:

<container list> = subform.getInvalidObjects();

This function returns a list of all the descendant containers (field, exclGroup, subform) of a subform which are in an invalid state.  If the subform that this script method is called on is itself invalid, that subform will be included in the returned list. The list is only generated on demand by recursively traversing the subform. The list returned is in document order.

This function will allow form authors to selectively highlight errors on sections of their form.  For example, in the "exit" event of a subform, you could highlight the missing or invalid fields contained within that subform, and direct the form filler to complete that section before continuing with the rest of the form.

As mentioned in yesterday’s post, missing mandatory fields are not considered invalid until they have been edited or there has been a call to execValidate().  To be consistent, the call to getInvalidObjects() respects the same rule.  The returned list will not include missing mandatory fields until the XFA processor considers them invalid. 

One of the places where the list of invalid fields is useful is during the submit process.  Form authors can use the preSubmit event to detect invalid fields, notify the user and cancel the submit action.  Note that submit performs a call to execValidate() — but only after preSubmit has fired.  This means that a call to getInvalidObjects() in the preSubmit event might not include missing mandatory fields.  If you want to be sure those fields included, simply call execValidate() before the call to getInvalidObjects().

It will be some time before form authors can really take advantage of the XFA 3.0 enhancements — mainly because it will be a while before Acrobat/Reader 9.1 is on enough desktops.  In the meantime, I expect authors will continue to make use of JavaScript frameworks to gain enough control over the user experience.  If you are new to the idea of JavaScript frameworks, have a look at the one that I’ve included in various samples.  The framework is described in a series of posts: Validation Patterns: Part 1, Part 2, Part 3 and here. The most recent version of the framework is embedded in the samples for this post

The framework was designed to:

  • Imitate the "form authoring usability" enhancements described in the last few XFA 3.0 blog postings
  • Leverage as much of the native XFA validation mechanism as possible for controlling validations
  • Over time, be replaced by the new built-in XFA 3.0 capabilities

I anticipate one one more post on XFA 3.0 enhancements and then back to regular programming.

4 Responses to XFA 3.0: List of Invalid Fields

  1. Keith Gross says:

    I was wondering if there is any way to use any of the XFA 3.0 features at this time or are we stuck until this fall when a new designer comes out?

  2. Keith:There’s no way to get there with anything we ship today. But of course, this is all based on an open standard — so if you have the right tools to modify a PDF you could get there. But I suspect you’re better off waiting for the user-friendly tools :-)John

  3. Jake Kim says:

    Thanks for your article.This may solve the problem I have right now if getInvalidObjects works.I’ve been trying to make the call in my PDF but it doesn’t seem to be working.Is it the name of the subform I want to invoke the method or just literally “subform”? The scripting guide says it is reference to the subform but neither works in my PDF. Would it be the version issue?I have Reader 9.2, Professional 8.1.7 and LiveCycle Designer 8.2 installed on my machine.Thanks.

  4. Jake:Unfortunately, you won’t be able to design this form with LiveCycle Designer 8.2. It is not able to create a PDF with an XFA 3.0 template inside. You will need to try and get your hands on the recently released LiveCycle ES2 Designer (version 9.0).John