There are still some great things worth mentioning about XFA 3.0. In particular,

• new “inactive” value for the presence attribute which, when set on a container (e.g. subform), “prevents the container and its contents from processing calculations, validations, and events”;
• enhancements to events framework now permits event propagation upward to parent objects — this is great because you can now implement validation code on a subform for all of its children instead of having validation code in each child, for example;
• new validation events and global validation handling control — this should address a lot of the current issues with form validation.

It looks like John Brinkman will be detailing these new features, and perhaps others, soon.

August 18, 2009 — Added links to new XFA 3.0 topics on FormFeed.

You could still use import bindings (set using the “Object palette > Bindings tab > Import/Export Bindings property”) but then you might have to hide most — or all — of those fields if you didn’t want to expose them. You would wait for the web service data connection to execute, then find the field that contains the piece of data you want and set it where it needs to go. This isn’t ideal, however, because Designer doesn’t expose any events, in the Script Editor, that would let you know that you now have data from the web service response in your form. Furthermore, having those extra fields around could add a lot of unnecessary weight (read: file size).

postExecute event

Unless you have studied the XML spec or deciphered its existence from the LC Designer ES Scripting Reference, you most likely don’t know about this event because Designer’s Script Editor palette doesn’t expose it. It’s purpose is to allow for post-processing of a web service response after a particular data connection is executed. The response data is temporarily stored in

xfa.datasets.connectionData.{DataConnectionName}

for the duration of the data connection’s PostExecute event.

Since it’s not exposed in the Script Editor, you have to go to the XML Source in order to set it on a form object — typically a subform. What follows is the XFA definition for the WebServiceDC data connection’s PostExecute event:

<event activity="postExecute" ref="$connectionSet.WebServiceDC">
    <script contentType="application/x-javascript">
        // do something...
    </script>
</event>

Note that I said this was the PostExecute event for the WebServiceDC data connection. The PostExecute event on its own — without a ref attribute that specifies the data connection to which it pertains — is of no use. In this case, the ref attribute specifies the WebServiceDC node inside the form’s connectionSet DOM (where web service data connections are defined). (Normally, the ref attribute has a value of “$”, which means “this”, since the event usually pertains to the form object on which it is defined.)

If you combine this with the ability to get web service response data without merging it into the form (either by not checking the “Object palette > Execute tab > Re-merge Form Data property” of the execute button for the data connection or you call xfa.connectionSet.{DataConnectionName}.execute(false)), you can essentially call a web service, get data back and do whatever you like with it.

Sample Form

To demonstrate how this works, I’ve created a sample form that has two web service data connections. It may take some time to open in Designer depending on how fast Designer can download the WSDL files from the two web services.

The first one, EchoEmployee, submits data from the top 4 fields and, using the PostExecute event, adds an item for each piece of data received in the response inside the list box. The following screen shot shows a sample result:

The second one, ConvertTemperature, obtains the conversion of the specified temperature from the web service response and displays it in a message box.

Download Sample [pdf]

Sample Minimum Requirements: While I developed the sample using Designer 8.2 and Acrobat 9.1, I have set the compatibility level to Acrobat/Reader 7.0.5 since this should work back to that version however I have not tested the form with anything earlier than 8.2/9.1.

Update (Sep 2, 2010): Note that the “Echo Employee” web service is no longer operational. This means that the first web service connection in the sample form can no longer be executed. The script is still valid, however, and serves as a good example. The second web service, “Convert Temperature”, is still operational.

Pre-Processor Library Snippet

In an effort to ease the pain of having to edit the XML Source, I have created an Object Library Snippet (XFO) that you can use to easily plug into this functionality:

Library Snippet [xfo]

In order to use it, you will have to save it to your Object Library’s Custom snippet folder which, depending on whether you installed Designer on XP or Vista, will be in one of the following locations:

C:\Documents and Settings\{username}\Application Data\Adobe\Designer\{version}\EN\Objects\Custom

C:\Users\{username}\AppData\Roaming\Adobe\Designer\{version}\EN\Objects\Custom

Once inserted into your form, the snippet will look like this:

By default, it’s set to work with a web service data connection that is named “WebServiceDC”. When that data connection’s PostExecute event is fired, the script inside will find the response data and call the processResponse() function defined on a script object that is included in the snippet (which is essentially a subform). Finally, the subform hides itself when the form is initialized so you don’t have to worry about hiding it yourself.

Now all you have to do is put script in the processResponse() function using the Script Editor!

If you need to use a different data connection name, you’ll have to go to the XML Source and make two modifications, highlighted here:

The first modification is to the ref attribute of the <event> node that defines the PostExecute event and the second is in the script itself where it extracts the XML of the response.

Sep 2, 2010 — Added note that “Echo Employee” web service is no longer operational which affects the first of the two connection samples in the sample form.

The XFA 2.8 specification specifies the <event> node’s content as being one of the following nodes: <script>, <execute> (executes a web service data connection), <submit> (causes the form to be submitted via email or HTTP) or <signData> (causes the form to be signed). Only one may be specified and whatever content is there will be executed when the event is triggered.

This means that you could, for example, cause a web service to be executed whenever a repeatable subform’s index changes (i.e. whenever you add/remove instances).

Is this useful? Well, perhaps not, but I thought it was interesting! Who knows what you might think of doing with this…

The only catch to all this is that Designer only lets you enter script (JavaScript or FormCalc) into an event, thereby specifying an event’s content as <script> as opposed to <submit> or <execute>. If you want to, say, cause a form submit when a field’s Full event is triggered, you’ll have to go to the XML Source and set the event’s content to a <submit> node yourself. An easy way to do this is first to add an Email/HTTP Submit Button to the form, set the field’s Full event to a placeholder script, go to the XML Source view, find the button using the Hierarchy palette, copy its Click event <submit> node and paste it into the field’s Full event so it looks like what’s below and delete the button:

<event activity="full" name="event__full">
    <submit format="xml" textEncoding="UTF-8" target="mailto:"/>
</event>

Sample Form

Check-out my little sample form that causes the form to be submitted via email when you fill the text field at the top and where a web service data connection is executed whenever you add an instance of Subform2 using the button at the bottom (below the web service import/export fields).

Download Sample [pdf]

Sample Minimum Requirements: Designer and Acrobat Standard/Pro 8.0 (XFA 2.5)

I have discovered that in that event isn’t quite accurate. It should rather be stated as within the context of that event. That’s because any function calls that you make from the event handler (for instance, into a script object that contains other functions — maybe your event handler simply passes execution to a re-usable event handler function that you have defined in this script object) will have access to these very useful objects.

In essence, xfa.event and event (if defined) are, for lack of a better term, contextual objects that exist — and are valid — as long as you are within the context (where context is different from usual definition of scope) of an event handler.

I had a case, just recently, where I needed to access the event.target property (that is, the AcroForm Doc object provided by Acrobat when it’s the host) in a function located inside a script object which I was calling from a subform’s Initialize event. At first, I thought I needed to pass it in as a parameter:

// Subform Initialize Event handler code
utils.InitSubform(this, xfa.host.name == "Acrobat" ? event : null);

-----
utils Script Object
-----

function InitSubform(sf, hostEvent)
{
    ...
    if (hostEvent != null)
    {
        // access AcroForm Doc object from parameter
        var pdfDoc = hostEvent.target;
        ...
    }
    ...
}

Unfortunately, this would’ve required updates to many forms since the script object was being used as a script object fragment and many forms were already using that function with only the first parameter.

Since the event object is actually available at that point in time, given that the handler is executing in the context of the subform’s Initialize event, I didn’t have to pass it in as a parameter and so I didn’t have to update a bunch of forms:

// Subform Initialize Event handler code
utils.InitSubform(this);

-----
utils Script Object
-----

function InitSubform(sf)
{
    ...
    if (xfa.host.name == "Acrobat")
    {
        // access AcroForm Doc object from in-context event object
        var pdfDoc = event.target
        ...
    }
    ...
}

Just remember that the xfa.event and event objects are only valid for the duration of the event which was triggered (so you shouldn’t hold on to them for future use) and that the event object is only available to you if the host is Acrobat/Reader (testing for xfa.host.name == “Acrobat” works for both Acrobat and Reader).

Tested with Adobe Acrobat and Reader 9.0.

Single Selection Lists

All XFA events have an object that represents properties about the event currently in execution:

xfa.event

This object holds many interesting properties but the one that’s important here is the newText property which, for a list, contains the new selection.

It’s important to note that there are two types of list items: Ones that have text data only and ones that have both text and value data. By default, the Object palette creates lists with items that have text data only. On the Field tab, you can add/remove items and specify their text data while on the Binding tab, you can optionally set each item’s value data by checking the “Specify Item Values” box.

The xfa.event.newText property always returns the text data. You can access the value data associated with the new text data by using the list’s boundItem() method:

// get the value data associated with the new selected text data
var newValue = MyList.boundItem(xfa.event.newText);

For single selection lists, you can therefore use the text data or get the associated value data for the new selection and do something from there. The following code sample gets the new selected value data in a list object’s Change event and changes the list’s background color accordingly:

var newValue = this.boundItem(xfa.event.newText);

switch (newValue)
{
    case 1:
        this.fillColor = "255,0,0"; // red
        break;

    case 2:
        this.fillColor = "0,255,0"; // green
        break;

    case 3:
        this.fillColor = "0,0,255"; // blue
        break;
}

Multiple Selection Lists

List objects may also support a multiple selection of items. You can specify that the list supports multiple selection by setting the “Object palette > Field tab > Allow Multiple Selection” property but you cannot specify a default selection of multiple items using the Object palette (only a single default selection is supported though it still works for lists that allow multiple selections). You would have to use the list’s Initialize script to do that.

At runtime (e.g. in Acrobat/Reader), you may select multiple items in the list by using the Shift and Ctrl keyboard keys: Shift + Click will select all items from the last selected item to the item you click on and Ctrl + Click will add/remove individual (non-sequential) items to/from the selection.

Determining the selection in a multiple selection list is different from doing so in a single selection list because you have to deal with the fact that more than one item may be selected. There is also a difference in the event you must use in order to handle the change in selection: When you set the “Allow Multiple Selection” property, the “Object palette > Field tab > Commit On” property changed to allow only a setting of “Exit” (as of Designer 8.1; Designer 8.0 may have still allowed “Select” to be chosen however I recommend setting this property to “Exit” if you have the choice) which means that the change in selection — as far as the list is concerned — will only take place once the user exits the list (once they hit the Enter key, tab away or click away from the list) rather than immediately when they visually change the selection. The result is that you must handle the change in selection in the Exit Event rather than in the Change event as in single selection lists.

You can handle a change in single selection lists using the Exit event as well however for single selection lists, it’s usually preferable to handle the change immediately rather than once the user leaves the list. For multiple selection lists, the idea is that the user may click more than once to set the selection they want so you typically want to react to the change only once they’re done which is why the selection is only committed once the user exits the list.

Determining the set of selected items was really difficult leading up to Designer and Acrobat/Reader 8.0 when the new list object properties and methods were finally introduced. These new APIs make it much easier to deal with lists that contain multiple selections: Use the length property to iterate through the items, the getDisplayItem method to get the text data associated with an item, the getSaveItem method to get the value data associated with an item and the getItemState method to determine whether the item is selected or not.

Here’s our sample script from earlier that sets the background color of the list object after a change in the selection (in the list’s Change event) however this time the script is meant for the Exit event and the list supports multiple selection. The color values are combined if more than one is selected, producing more color combinations up to white (an RGB color value of “255,255,255″) then all 3 items are selected:

// array with 3 elements, all at zero initially
var rgb = new Array(0, 0, 0);

for (var i = 0; i < this.length; i++)
{
    if (this.getItemState(i))
    {
        // item is selected
        // item values are 1, 2 or 3 (1-based)
        // array elements are 0, 1 or 2 (0-based)
        rgb[this.getSaveItem(i) - 1] = 255;
    }
}

// Array.toString() produces a comma-delimited string containing the
//  values of the array elements so this will produce "255,0,255" if
//  items 1 and 3 are selected.
this.fillColor = rgb.toString();

If you give this a try, remember to create a list with 3 items (1, 2, 3) and place the script in the Exit event, not the Change event. Then remember to click away from the list once you’ve set the selection at runtime.

Multiple Item Default Selection

Setting a default selection of more than one item is unfortunately not something that Designer supports. To achieve this, you’ll need to set the list’s Initialize script to do the work. For example, to initialize a multiple selection list of 5 items where items 1, 4 and 5 are selected, you would do this (remember that list item indexes are 0-based, not 1-based) in the list’s Initialize event:

this.setItemState(0, true); // item 1
this.setItemState(3, true); // item 4
this.setItemState(4, true); // item 5

Sample

To see this in action in what you might consider a more realistic example, my “What About the Other Field?” tutorial uses single selection lists that show an “other” field when their “other” item is selected.

Hi first post relates to exclusion group-like functionality using any type (or combination) of fields in a subform where each field is treated as a mutually-exclusive radio button. Check it out, it works very nicely!

The Secret

The secret to changing the email recipient for an email submit button (or even changing it for a regular button which you’ve turned into a submit button using the "Object palette > Field tab > Control Type > Submit property") is to set the "target" attribute of the <submit> node that is part of the button’s Click event. The "target" specifies the URL to which the data will be submitted. HTTP and mailto are valid protocols.

In XFA, the difference between a regular button with Click event script and a submit button which submits form data when it’s clicked is that the submit button’s Click event has a <submit> node instead of a <script> node.

A regular button’s Click event:

<event activity="click">
    <script contentType="application/x-javascript">
        // your JavaScript code here...
    </script>
</event>

versus a submit button’s Click event (set to email form data in this case because of the "mailto" protocol):

<event activity="click">
    <submit format="xml" textEncoding="UTF-8" target="mailto:"/>
</event>

How is it done?

Changing the recipient is done simply by setting the submit button’s target appropriately, following the rules of the protocol you wish to use. In this case, we’ll be using the mailto protocol. Of course, we can do much more than change the recipient: We can actually specify multiple recipients, CC some others, BCC others still, specify any subject we want and even specify a customized email body (message)! All that needs to be done is to apply the mailto protocol when specifying the submit button’s target.

For example, setting the target to the following string would create an email with two recipients (one "to" and one CC’d), a subject and a body:

mailto:john@asdf.com?cc=lisa@adsf.com&subject=Re: New Account Opening&body=Thank%20you%21"

Note that the body must be URL-encoded using the "%" codes for non-URL characters such as "%20" for a space and "%21" for an exclamation mark (!). Thankfully, we can use the encodeURIComponent(string) method in JavaScript to do that part for us!

The most difficult part of all this is finding the Click event (since there could be multiple <event> nodes specified on a single field, one for each event that does something) and locating the <submit> node inside.

Sample Form

To illustrate how this is done, I’ve created a sample form that submits an address block as data and provides fields for specifying the recipient(s), CC list, BCC list, subject and body of the email.

The result of the above settings is a new email with the specified recipients, subject and body, along with the attached XML data file:

In order to accomplish this, I used the two-button submit technique where a regular button is used to set the properties on a hidden email submit button. Doing it this way also lets me easily prevent the submission if there are no recipients ("to") selected. (Note that the To, CC and BCC fields are multi-select list boxes so you can choose multiple email addresses.) You’ll be interested in the script in the "Send" button’s Click event.

Download Sample [pdf]

Minimum Requirements: Designer 8.0, Acrobat/Reader 8.0 for this form since it uses functions that are part of the new List Object API which was introduced with the 8.0 versions however you could access the selected items differently and get this to work in previous versions as well.

XFA Spec (page 353 in version 2.7).

Say your form object hierarchy looked like this (in the Hierarchy palette in Designer):

The fields and subforms would get initialized in the following order:

To clarify, this is the order (note that text objects don’t get initialized just like squares, circles and images wouldn’t — image fields would, however):

0. DateTimeField1
1. TextField1
2. PasswordField1
3. Subform2
4. NumericField1
5. Subform1
6. CheckBox1

To demonstrate this, I’ve provided the form that contains the objects above. When you preview the form (or view it in your web browser) using Acrobat, use the JavaScript Console to see the output from the Initialize events of the various form objects to see the order of initialization.

Download Sample [pdf]

Minimum Requirements: I created this form in Designer 8.1.1 SP2 and tested it in Acrobat Pro 8.1.2.

I thought it might be useful to provide a sample form which demonstrates how to build a list field which has an “other” option and clicking on the “other” option displays a field for entering the specific value and makes that field required — but only if the user chooses the “other” option. (You wouldn’t want the “other” field to be hidden and required or else the user would never be able to submit their form since Acrobat would prevent the submission on the premise that there’s an un-filled required field somewhere.)

“Other” Fields in Acrobat/Reader 8.1+

The first thing I did was create my sample form using Designer 8.1 and Acrobat 8.1. That was very easy and just as straight-forward as I expected it would be: One radio button list, one list box and one drop down list, each set to be required and with their own “other” item and script to show their respective “other” field (and make it mandatory) when their “other” item is selected and hide it (and make it optional) when their “other” item is de-selected. Add a submit button and Acrobat/Reader 8.1 automatically takes care of preventing the submission if any required field isn’t filled.

To keep things simple, each list field has script that detects when the user either selects the “other” item or an alternate item and sets the presence and mandatory properties of its “other” field to be visible/required or invisible/optional, respectively.

Download 8.1 sample [pdf]

Minimum requirements: Designer 8.1, Acrobat/Reader 8.1

“Other” Fields in Acrobat/Reader 8.0 or Earlier

Unfortunately, I didn’t have the same kind of experience getting this form to work in Acrobat/Reader 8.0 or earlier.

The first thing I did, since my 8.1 sample form doesn’t use any functionality only available as of Designer/Acrobat 8.1 (in fact, it uses XFA properties and script functions that have been available since Designer/Acrobat 7 and likely even earlier), I simply used Designer 8.1 to set my form’s Target Version to Acrobat/Reader 7.0.5 and figured I would open it in Acrobat 7.0.9 and all would be good. Well, that wasn’t the case.

Aside from Acrobat not respecting the “required” setting on the radio button list (which was expected since required radio button lists weren’t supported until Acrobat 8.0), I discovered a very strange behaviour in the list box where simply having a statement within its Change event that sets a field’s mandatory property to “error” will always result in that field being required, as far as Acrobat/Reader is concerned, even if the statement doesn’t appear ever to be executed on form initialization. The result is that selecting an item other than the “other” item in the list box and attempting to submit the form prompts Acrobat to cancel the submission because a required field isn’t filled. The problem is that the required field is the list box’s “other” field which is hidden from view because it isn’t supposed to be required. Finally, there was also another issue with list boxes that have Change event script: Their value is never committed to the Data DOM, which means that the list box always appears to have no value and that also prevents the user from being able to submit the form because the list box appears never to have been filled (even though an item is clearly selected).

So the are three problems with the 8.1 sample form when it’s running in versions of Acrobat/Reader prior to 8.1:

1. Although properly supported in Acrobat/Reader 8.0, radio button lists can’t be set to “required”;
2. List boxes with Change event script containing a statement which sets a field’s mandatory property to “error” results in that field always being “required” (this strange issue is resolved in Acrobat/Reader 8.1); and
3. List boxes with Change event script don’t commit their value to the Data DOM (this is also resolved in Acrobat/Reader 8.1).

Fortunately, issues #2 and #3 can be resolved fairly easily simply by not using the Change event. The only viable alternative I found was using the Exit event instead. (Note that in the Exit event, you have to use the list’s “rawValue” property to determine its value rather than using the “xfa.event.newText” property as in the original Change event script.)

Issue #1 (required radio button lists not supported) can also be resolved although it requires a little more work. One alternative is to use the “Two Button Submit” Technique I described on a previous post on Complex Validations, which is what I implemented in my 7.x sample form.

Download 7.x sample [pdf]

Minimum requirements: Designer 7.0, Acrobat/Reader 7.0

The easiest way to make sure that all your new scripts default to the JavaScript language is to use the Form Properties dialog and set JavaScript as the default scripting language (in the Defaults tab). The problem with this setting is that it affects only the current form. If you’re like me, you create lots of forms every day, you constantly forget that the default scripting language is FormCalc and you only remember once you’re running your form and you get a FormCalc error message box in Acrobat telling you that your syntax is incorrect. How annoying!

Fortunately, there’s a way to set JavaScript as the default scripting language for all new forms — based on a specific template. The default setting for the scripting language is actually specified as a processing instruction in the XML Source. If you create a new document and go to the XML Source tab, you’ll find the following processing instruction set as a child of the <template> element (also shown in the image below):

<?templateDesigner DefaultLanguage FormCalc?>

Since all new documents created in Designer are based on templates and that each template comes with its own set of processing instructions, modifying the processing instruction in the template would effectively modify the default scripting language on all new forms based on that template. Going one step further and making that modified template your default template would ensure makes things even easier when you’re creating new forms.

Fortunately, you don’t have go to the XML Source view to modify this processing instruction. Instead, you can set its value using the Form Properties dialog (accessible via the File menu): In the Defaults tab, set the Default Language property to “JavaScript”.

Modifying Designer Templates

In Designer, you use the Template Manager to organize your templates. You can access the Template Manager from the Tools menu.

To modify a template, you can follow these easy steps:

1. Create a new document based on the template you wish to modify.
2. Make the necessary modifications (like setting the processing instruction for the default scripting language setting to "JavaScript").
3. Save the new document as an "Adobe LiveCycle Designer Template (*.tds)" file. If you want to replace an existing template (say "Letter"), use that same name as the file name for the new (modified) template file you’re saving.
4. Using the Template Manager, select the tab pertaining to the group in which you want to add your new template. If you’re wanting to replace the "Letter" template, for example, select the "Standard" tab.
5. Right-click in the list panel and select "Add Template…". Select the template you just saved and it’ll be added to Designer’s "template store". Note that if the name of your new template file is the same as an existing template in the group you selected (e.g. the "Letter" template in the "Standard" group), you’ll be prompted to overwrite the existing template.

One important thing to note in the way Designer handles templates is that any template file you add to the Template Manager gets copied into the "template store" which means that new documents based on that template aren’t actually based on the template file in the location where you saved it but rather on the copy that was placed in the "template store".

If you’re wondering what the "template store" is, it’s actually a folder inside Designer’s Application Data folder on your system. While I don’t encourage you to look in there (because you might see things that look interesting but you shouldn’t be playing with , if you find them, then you should also be able to open them directly in Designer and modify them without having to create a separate copy.

_{Updated: January 17, 2006}