XFA Scripting API Reference

Some time ago we had an intern build a flex application that gave internal people a nice reference for the XFA scripting object model.  Our nightly build process generates XML files that describe all the objects, properties and methods available within XFA scripting.  This flex application loads those files and gives a very convenient tree view where we can drill into the details of the object model.  Any time the build is broken and this application isn’t available, I suffer withdrawal symptoms.  So I figured maybe you would find it useful as well.  I have taken the flex application, changed it up so that it works stand-alone and I’ve embedded it in a PDF.  The result is ScriptReference.pdf. (Warning: I encountered some strangeness when I tried to launch this pdf directly from firefox.  Probably best to right-click/download and then launch.)

ScriptReference.pdf

The reference divides up the objects among the various top-level models in XFA (form, template, data, etc).  The way you use it is that you select the object you are interested in — e.g. the field object under the form category — and then the right hand side of the page will display all the properties and methods available. 

Notice that the reference exposes some of our object hierarchy — each object has a parent class.  The display shows only the properties and methods for the current object.  If you want to see the properties and objects inherited from the parent class, then click on the parent object class.

Under the "XFA" category, you’ll find a miscellaneous list of objects, including the classes that occur higher in the class hierarchy.

The set of descriptors needs a bit of explanation.  For Properties:

type: The type of content (String, Object, Bool, integer etc).  Some properties may say "Multiple" because the property type changes depending on the context.  e.g. field.rawValue returns a string for text fields, but a number for numeric fields.

Based on schema: yes/no: indicates whether this property is exposed as a result of being part of the XFA schema.  i.e. part of the file format.  This value will be "no" for properties such as field.fillColor (a shortcut property) or field.formattedValue (a calculated value).

access: GET or SET or both. i.e. whether this property is read-only or if it is read-write.  Note that objects in the template may tell you that they are ‘set’able, but if you try to set them in Acrobat you’ll get an error.  This is because the template is read-only in Acrobat — but is read/write in other contexts — specifically on the server.

version: The XFA version where this property was introduced.

For methods, the form shows the method signature, displays the version number and describes the parameters.

Search

At the bottom left you will see a couple tabs where you can enter a search string.  When searching by name, the tree list will get filtered to those objects/properties that match the given name.  When searching by version, the tree list gets filtered to those objects/properties that match the specified version.

Warning: developer-speak

The descriptions of the objects, methods and properties are exactly as they were written by the developers who implemented the functionality.  What you probably already know about developers is that we not always good grammar writing.  The documentation you get with Designer has been produced by our talented bilingual tech writers who can translate from developer-speak to English.  So take the descriptions with a grain of salt, and if you find them confusing, consult the real documentation.

Check for New Version

Notice the "Check for New Version" button.  When we release a new version of XFA inside Acrobat/Reader/LiveCycle I will need to produce an update.  Or maybe I’ll fix a bug.  Periodically you should click the button and find out if the copy you have is the latest.

5 Responses to XFA Scripting API Reference

  1. Dear John,reading through the reference I got the question if it’s would be possible to generate a sourceSet definition from scratch i.e. to connect to a database only for specific users. A sample workflow might be that a customer fills out a form and someone within the company processes the form and would like to update a database. As the customer would not have a database a predefined connection will fail alerting the customer.Kind regardsMaruan

  2. Maruan:I haven’t worked too much with sourceSets. However, I am aware that people do want to be able to modify sourceSet properties before making a database query. I can’t test this entirely, but I think what you need to do is create a nominal sourceSet definition in your XDP file:<sourceSet xmlns=”http://www.xfa.org/schema/xfa-source-set/2.8/”><source name=”test”/></sourceSet>As long as this exists, it is possible to create a new source connection with this script:var s = xfa.sourceSet.createNode(“source”, “testConnection”);Or this one:var s = xfa.sourceSet.test.clone(true);You’d then populate all the properties and call the methods on your new source object.Of course, this is mostly theoretical until you try it and prove it :-)good luckJohn

  3. JohnI finally got around testing that a little bit with the following results:a) there has to be at least one entry for which causes a dialog to appear when opening the form if one want’s to allow access for that data connection and another dialog that the entry is missing.b) apart from that it worked fine to define a data connection with connect string, commands etc. via script.c) for Reader enabled forms you have to go for the .clone syntaxSo the result is that I can script my connection. Because there has to be at least one entry within sourceSet (which causes a dialog to appear) my initial request to avoid a dialog if a user should not work with a database for a specific step within a forms based workflow can not be solved that way.With kind regardsMaruan

  4. Maruan:As discussed, it appears that the message appears in Reader 8.x versions but does not appear in 9.2John

  5. John:I can confirm that. Using Reader 9.2 a database connection can be fully scripted from scratch provided there is a nominal sourceSet definition.Maruan