I am certain at some point in time you have had to fill-out some type of form on a website and the required fields were identified by an asterisk (*). This is a common way to communicate to a user which fields are mandatory and which ones aren’t.

This is a design pattern that the Form Guide Team adopted when they conceived the default Form Guide user experience. Since the appearance of a field in a form guide doesn’t have to be the same as that of the field in the form (PDF), they were able to automatically add an asterisk next to mandatory fields without affecting their PDF counterparts.

For example, in the following images, the Name and Address fields are mandatory (“Object palette > Value tab > Type property” is set to “User Entered – Required”) while the rest are optional. Notice how the captions of the Name and Address fields in the Form Guide have asterisks while the ones in the PDF don’t (and I didn’t have to do anything other than include those fields in a panel in a Form Guide in order to get this functionality):

— Form Guide

— PDF

Unfortunately, while XFA gives us the ability to mark a field as mandatory, Acrobat/Reader doesn’t automatically set them apart like the Form Guide does. Perhaps that’s a good thing because it gives you full control over how to identify fields as being mandatory.

Mandatory fields could be highlighted in different ways: An asterisk, a different background color or various other types of styles. If you use an asterisk, however, the tendency is to put it in the caption but doing this manually can be tedious if there are a lot of fields. What if some fields only become mandatory after certain conditions are met as the user is filling the form? If you don’t put the asterisk in the field’s caption (so that you can easily show/hide it when necessary using script), then you risk getting into various layout issues trying to get the asterisk to show-up at the right position next to each field. It also means lots more form objects which could really bloat your form.

That’s why I decided to implement a script that automatically adds the asterisk to a field’s caption. That way, you don’t have to worry about the asterisk — just mark the field as mandatory, run the script on initialization and it will search the entire form, placing a red asterisk in the captions of mandatory fields regardless of nesting levels. Furthermore, if you decide to use a text object as a caption next to a caption-less field or radio button list, the script will mark it with an asterisk as well (provided the text object’s name is the same as the field/radio button list’s but with a “_Caption” postfix).

Applying my script to the sample above would yield the following results in the PDF without affecting field appearances in the Form Guide:

— PDF

mandatoryLib

The following sample form references the auto-asterisk script in the mandatoryLib script object fragment. I suggest you download the fragment (see link below) and reference it in all the forms in which you want to use the script. Feel free to enhance it as well if it doesn’t work quite right for your particular needs: The script is heavily commented so it should be easy to follow and extend.

There are two functions you can call:

• IdentifyMandatoryFields(formObj): Given a form object (field or container such as radio button list or subform), find all mandatory fields inside (all nesting levels) and add an asterisk to their captions (actual captions or text object captions).
• ToggleMandatoryField(formObject, isMandatory): Given a field or radio button list, toggle its mandatory state by adding (isMandatory == true) or removing (isMandatory == false) the asterisk.

Furthermore, since the scripts handles both plain and rich text captions, you don’t have to worry about making sure all captions use rich text formatting.

Note about rich text: If you look at the script, you’ll notice that the rich text value of a field’s caption or text object’s content is retrieved from the Template DOM rather than the Form DOM. The Template DOM is where the design-time form object definitions are stored (it’s what you define when you edit the form in Designer) and cannot be modified at runtime (i.e. Acrobat/Reader) while the Form DOM, generated at runtime, is very sparse and contains only what is needed to render the form object in its current state. That means as long as there are no modifications to the rich text value, it will not appear in the Form DOM and must be retrieved from the Template DOM instead. One draw-back of this issue is that if you make any modifications to the caption/text object and then run the script, those modifications will be lost because the script will use the un-modified rich text from the Template DOM rather than your modifications stored in the Form DOM.

Download Sample [pdf] (if you plan on editing this Designer, you’ll also need the fragment below in the same folder)

Download mandatoryLib Fragment [xdp] (to download, right-click on the link and choose “Save Link As…”)

Special Thank You to my friends at Avoka for pointing-out that my original solution didn’t handle mandatory fields in repeating subform instances.

Sample Minimum Requirements: Since the script object uses dynamic object variables for optimization, I had to set it to use XFA 2.8 which means you’ll need Acrobat/Reader 9.0 to run it.

mandatoryLib Minimum Requirements: You could probably get away with running this script in an XFA 2.5 form (Acrobat/Reader 8.0), maybe even less, but the optimizations with the $formObjMap object may not function properly due to an aggressive JavaScript Garbage Collector in earlier versions (in other words, the script may run slower but it should still run).

Aug 28, 2009 — Separated mandatoryLib script object out into a script object fragment.

---

Posted by Stefan Cameron on March 16th, 2009
Filed under Acrobat,Form Guides,Scripting,Tutorials
Both comments and pings are currently closed.

---