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().
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.