AcroForm Objects

Today I thought I would tackle the subject of AcroForm Objects — objects available via scripting in the Acrobat Form Object Model — because they offer unique possibilities for your forms *when they’re running in Acrobat in the PDF format*.

Just to be clear, AcroForms are *specific to Acrobat* and therefore this functionality doesn’t apply when rendering your forms to a target other than PDF (e.g. when using “LiveCycle Forms”:http://www.adobe.com/products/server/formserver to render your XFA Forms as HTML).

First, let’s explain what XFA (XML Forms Architecture — a “W3C Submission”:http://www.w3.org/1999/05/XFA/xfa-template) does: It lets you describe a form, using a defined set of rules that govern an XML structure, which can target many different clients (e.g. PDF, HTML, etc.) — as long these clients support the XFA format. Today, the Adobe LiveCycle Designer targets PDF out-of-the-box and, along with “LiveCycle Forms”:http://www.adobe.com/products/server/formserver, targets HTML.

The fact that XFA is always translated into a format which can be understood by a client with which a user interacts in order to fill a form and possibly submit its data to a receiver means that the scripts you write in your XFA forms get executed in the target client application (such as Acrobat or a web browser). If the target client also contains a Scripting Object Model — like Acrobat does — there may be ways that you can take advantage of specific functionality exposed by the client which is hosting your XFA forms.

This brings us to the topic at hand: “Acrobat’s Form (AcroForm) Object Scripting Model”:http://partners.adobe.com/public/developer/acrobat/sdk/index_doc.html#js. If you’re designing your form only to target PDF (or you add code to your form to detect when your form is being hosted by Acrobat using xfa.host.name, for example), you can get access to the Acrobat _app_, _Document_ and _Field_ objects, amongst others, and do some really cool things like have a “field with invalid data start flashing red”:http://blogs.adobe.com/formbuilder/2006/06/invalid_flashing_fields.html when the user attempts to submit the form’s data.


h2. xfa.hostWhen writing scripts in an XFA form, you have access to the special _xfa.host_ object. This object gives you access to methods which are *specific to the application hosting your form* (such as Acrobat, a form server or a web browser). For example, thebc. xfa.host.nameproperty tells you the name of the application hosting your form at the time the script is interpreted. If your form is being viewed/hosted in Acrobat, this property will return “Acrobat” while it’ll return the name of the browser if it has been served to a web browser. Furthermore, it’ll return “Presentation Agent” if the script was flagged to run on the server and the server application serving the form to PDF or HTML is Adobe’s “LiveCycle Forms”:http://www.adobe.com/products/server/formserver product.xfa.host also gives you access to other properties and functions such asbc. xfa.host.messageBox // displays a dialog box on the screenxfa.host.validationsEnabled // turns the form’s validations on/off with a single callbut take note that not all functions and properties are available on all hosts (e.g. since a server host can’t display a dialog which requires user input, the xfa.host.messageBox function is only supported on _client_ hosts like Acrobat and web browsers).You can obtain more information on xfa.host on page 185 of the “Adobe XML Form Object Model Reference”:http://www.adobe.com/devnet/livecycle/designing_forms.html.h2. Acrobat app ObjectSince the scripts you write in functions and events within an XFA form are interpreted by and executed within the context of Acrobat’s Scripting Engine, you have access to a special object called _app_. This object gives you access to the collection of active documents and plugins, amongst other things, and lets you display alert messagesbc. app.alert(“Hello world!”);and even set Acrobat into full screen mode with a red background!bc. app.fs.backgroundColor = color.red;app.fs.isFullScreen = true;Note that while _color.red_ isn’t an object provided by the XFA Scripting Object Model, it still exists within the context of your scripts because the scripts are ultimately interpreted and executed within Acrobat. You can get more information on the _app_ object in the “Acrobat JavaScript Scripting Reference”:http://partners.adobe.com/public/developer/acrobat/sdk/index_doc.html#js.h2. xfa.eventThis is a special object which exists only via the XFA Plugin which executes XFA scripts on XFA object events inside Acrobat. Whenever an event occurs (such as the click of a button or a field gaining input focus), your script has access to the _xfa.event_ object which gives lots of important information about the event.For example, if you want to know the value that was selected in a list box or a drop down list in order to change the state of another object on your form, you would script against the list box’s or drop down list’s Change event. If you used the following code to get the value of the item that the user selected:bc. this.rawValueyou would get the previously-selected value because the object’s rawValue property isn’t updated until after the Change event has occurred. In order to get the information you need, you must use the following code:bc. xfa.event.newTextwhich will give you the value of the item the user just selected._xfa.event_ also gives you access to a very useful property called _target_: In Acrobat, this property specifies the Acrobat _Document_ object (which contains the Acrobat _Field_ object which wraps the XFA object whose event is being scripted). This means that you can get at the Acrobat _Document_ object for the “active document” just by using:bc. event.target(Note that you don’t need — and shouldn’t use — the “xfa” prefix when accessing the “event.target” property — I don’t know why yet but you’ll have trouble using it if you use the “xfa.event.target” syntax.)Using this information, you can:bc. event.target.zoom *= 2; // increase the zoom level two-foldevent.target.zoomType = zoomtype.fitW; // zoom to page-width levelevent.target.zoomType = zoomtype.fitH; // zoom to page-height levelor you can use the _getField_ method to get an Acrobat _Field_ object and do some more interesting things.You can get more information on the _Document_ and _Field_ objects in the “Acrobat JavaScript Scripting Reference”:http://partners.adobe.com/public/developer/acrobat/sdk/index_doc.html#js.h2. Putting it all Into PerspectiveTo tie this all together, I’ve drawn-up a *simplified* version of the Scripting Object Model the way I picture it in my head:==Scripting Object Model (simplified)==This image illustrates how things work from the perspective of a script running within an XFA Event or an XFA Script Object Function (note that you don’t have access to the xfa.event object there unless you pass it into the function by calling it from an XFA Event). You can see how, from the XFA object, you can get to the:* Acrobat app object (directly);* Acrobat Document object (via event.target or the app object);* Acrobat Field object (via the Document object);* xfa.host object (directly).Hopefully this post will have given you a general idea of the *Acrobat-specific* tools at your disposal when you’re writing XFA scripts using the JavaScript language. Please note, however, that changes may occur to the way XFA Form Objects are hosted within Acrobat in future releases and therefore using the AcroForm Object Model should be a *last resort* if an XFA equivalent simply isn’t available.====~*Updated:* August 30, 2006~