How Lists Store Selected Items

To better understand the challenges, let’s look at how list form objects store a multi-selection of values.

In the Form DOM, the list’s value actually contains XML rather than plain text. For example, say we have a multi-selection list named “ListBox1″ (bound to a data element named “list1″) with items (“item1″, “item2″, “item3″). If the first two items were selected, the list’s value would look like this:

<value>
    <exData contentType="text/xml">
        <list1>
            <value>item1</value>
            <value>item2</value>
        </list1>
    </exData>
</value>

In script, this would translate to a newline (\n)-delimited string when the list’s value is accessed from its rawValue property:

item1\nitem2

In the Data DOM, the list’s value is stored in a series of repeating <value> nodes, much like the way it is stored in the Form DOM:

<list1>
    <value>item1</value>
    <value>item2</value>
</list1>

Adding the Schema

A schema describes how XML should be structured. Given how lists store their selected items in data, a schema that includes a multi-selection list will need to allow for the element that defines the list to contain zero or more repeating <value> nodes. Unfortunately, this means modifying your schema, if you already have one. (I can think of at least one workaround to this which would involve script and a sibling, hidden text field bound to the element in your schema, as opposed to the list itself, in which you would store the selection, but I won’t get into that in this article.)

For example, this is a schema that defines a “form1″ root element that contains an element named “list1″ that has a multi-selection list type (the way XFA expects it).

Data Connection

The problem with this structure is that once you connect your form to this schema, the Data View connection tree will interpret the list1 element as being a subform that contains a repeating node, “value”:

Because of this interpretation, you cannot simply drag & drop the “list1″ schema element into your form in order to get a multi-selection list. Instead, you’ll get a subform with a text field inside of it instead (only an element with a simple type restricted to an enumeration of values would be interpreted as a list). Furthermore, you cannot use the picker widget next to the “Object palette > Binding tab > Data Binding property” to assign “list1″ to a listbox you have already dragged into your form from the Object Library palette because “list1″ is viewed as a container (subform) and the form object you are attempting to bind is a field.

Data Binding

In order to bind the listbox to the “list1″ schema element, you must manually type its binding expression into the “Object palette > Binding tab > Data Binding property”. For our simple use case, the binding is “list1″. Note that you don’t actually bind the repeating “value” element to anything and that the schema data connection tree will not actually indicate that the “list1″ element is bound to a form object even though it now is (I’m guessing this is because it is expecting “list1″ to be bound to a subform, not a field).

The result of binding the listbox to the “list1″ schema element is that the Form DOM output changes slightly to include the proper namespace on the bound element within the field’s value:

<value>
    <exData contentType="text/xml">
        <scof:list1 xmlns:scof="http://forms.stefcameron.com/ns/2009/">
            <value>item1</value>
            <value>item2</value>
        </scof:list1>
    </exData>
</value>

Submitting Data

As you might expect, given the structure of the listbox’s selection in the Form DOM above, the list’s selection data will be similar in the Data DOM (which is what would be submitted from the form as well):

<xfa:data xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/">
    <scof:form1 xmlns:scof="http://forms.stefcameron.com/ns/2009/">
        <scof:list1>
            <value>item1</value>
            <value>item2</value>
        </scof:list1>
    </scof:form1>
</xfa:data>

The only problem with the data above is that it isn’t valid against the schema which specifies that the repeating <value> nodes inside the list1 element are part of the “scof” (target) namespace and should therefore look like <scof:value>.

Submitting Namespaced Data

In order to get the namespace into the repeating <value> nodes for the selected values, we have to use a workaround that involves a little script in the listbox’s Exit event (though the script could be triggered elsewhere, if you like):

// JavaScript:

// schema namespace info
var nspace = "scof";
var nsUri = "http://forms.stefcameron.com/ns/2009/";

// get selection from list
var selection = this.rawValue.split("\n");

// build XML string for new selection in *Form DOM*
//  that includes the namespace in the <value>
//  nodes the outer <listSelection> node is
//  essentially irrelevant and will be discarded later
//  however it is required so that we can load its
//  content into the listbox's exData value node where
//  its value is set in the Form DOM
// this.dataNode.name gets the listbox's bound data
//  element name from the Data DOM which is required
//  in the XML
var newSelection = "<listSelection>\n<" + nspace +
    ":" + this.dataNode.name + " xmlns:" + nspace +
    "='" + nsUri + "'>";

// add selected items into the new selection -- take
//  note of the newline character at the beginning of
//  the string as it is critical to the XML loading
//  properly later on (it shouldn't be but it is...)
for (var i = 0; i < selection.length; i++)
{
    newSelection += "\n<" + nspace + ":value>" +
        selection[i] + "</" + nspace + ":value>";
}

// close the XML elements in the string
newSelection += "\n</" + nspace + ":" +
    this.dataNode.name + ">\n</listSelection>";

// load the new namespaced selection into the listbox's
//  exData value node, ignoring the root <listSelection>
//  node in the XML string
this.value.exData.loadXML(newSelection, true, true);

The script above essentially builds an XML string equivalent in structure to that which is normally used to store the list’s selection in the Form DOM however it adds the necessary namespaces to the repeating <ns:value> nodes. This change is then replicated in the list1 data node in the Data DOM and the form’s exported data changes to this (which can be successfully validated against the schema we’re using):

<xfa:data xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/">
    <scof:form1 xmlns:scof="http://forms.stefcameron.com/ns/2009/">
        <scof:list1>
            <scof:value>item1</scof:value>
            <scof:value>item2</scof:value>
        </scof:list1>
    </scof:form1>
</xfa:data>

Import Data Warning

Unfortunately, I have to point-out a bug as it relates to exporting multi-selection values with namespaces (which you only get when you use the above workaround script): Importing data with namespaced <ns:value> nodes for multi-selection lists — though valid XML and valid against the schema — will fail in Acrobat 9.1.3 (I have not done any testing on previous versions). My testing has revealed that the form doesn’t render properly after the data merge. Importing namespaced data that does not have namespaced <value> nodes for multi-selection lists, however, does work fine (this is the default way data is exported, unless you use the script I outlined above).

Sample Form

I have built a sample form that demonstrates how multi-selection lists store their data in the Form DOM and Data DOM. The form also includes a checkbox which, when checked, will generate namespaced <ns:value> nodes instead of the default <value> nodes, using the workaround script in the list’s Exit event.

Download:

• Form [pdf]
• Schema [xsd]
• Sample Data [xml]
• Sample Data (namespaced) [xml]

Minimum Requirements: I designed this form using Designer ES2 Beta and Acrobat 9.1.3 however the form should work all the way back to Designer 7.1 and Acrobat 7.0.5.

In particular, this 8.2.1 SP2 update resolves a nasty bug where your form would grow to multiple megabytes in size due to a processing instruction (PI) being repeated thousands of times for a particular field. The PI looks like this (though the value, ‘aped3′, may differ):

<?templateDesigner StyleID aped3?>

Thankfully, this bug doesn’t occur often but when it does, the most common symptoms are:

1. reduced performance when working in Designer;
2. form file bloat (into the multiple MBs); and
3. crashes when working in Designer with the form open.

If you can’t update Designer due to your licensing agreement and you come across this bug, you’ll need to go to the XML Source and look for a processing instruction like the one quoted above. It’ll be there many, many times. Just delete all occurrences. If your form is saved as an XDP, then you can exit Designer and open it in Notepad (or some other text editor) and delete it that way as well. Then re-open it in Designer.

Updated: March 28, 2009

Form Guide Layout

The goal is to design a form guide which will provide two panels: one for user options and the other for results.

The first panel will expose the 4 fields inside the GuideObjects subform (which are only meant to be exposed in the form guide — hence why the GuideObjects subform has the Initialize script to hide it if the host isn’t “Flash”). The user will have the option to choose an actor and/or category for further filtering and will then click on the GetMovies button to execute the request on the Movie Service. When the requested XML is returned to the form guide, the GetMovies result handler will convert the XML into instances of MovieRow inside the Listing table.

The second panel will use a repeater layout to expose the Listing table’s contents within the form guide however this panel will only be accessible if the movie query returned 1 or more results.

Once the results are in, the user will then be able to switch (“flip”) to the PDF view which will show the Listing table in the form, from which the user could then print or archive the results.

Designing the Form Guide

Open your tutorial form in Designer and launch GuideBuilder (GB) by choosing the “Tools > Create or Edit Form Guide” command. Switch to the “Customize Appearance” tab and choose “Save Styles”, saving them to a SWC file of your choice (usually in the same folder). It’s not mandatory to do this but if you don’t specify a file name here, GB will auto-generate a style SWC (which contains information about any style customizations you might apply) named according to the wrapper you choose (e.g. “ga.wrappers.CobaltStandard.swc” for the “Cobalt Standard” wrapper — not the most meaningful name for our solution).

Back to the “Edit Guide” tab, set the guide’s title to “MAX 2008 Movie Catalog Service” (double-click on the “New Guide” label to set it), the section’s title to “Movie Catalog” and the panel’s title to “Options”. Set the panel’s layout to “Two Column”.

Options Panel

Click on the “Add or Bind Fields” button and drag the entire GuideObjects subform into the panel. You’ll see, in the “Panel Preview” pane on the lower-right, that objects in the panel are laid-out in two columns from left to right, top to bottom, according to the top-down order in which they appear in the panel. What we want is for the MatchCount field to show-up below the GetMovies button. To do this, insert a “Next Area” object (from the “Utility Objects” group at the top of the form tree) after all the objects in the panel and then drag the MatchCount field below it. The “Next Area” object causes a break in the layout algorithm, thereby forcing the following object onto the next row in the two-column layout.

To make the panel layout more pleasing, switch back to the “Set Properties” view and set the captions of the ActorList, CategoryList and MatchCount fields to be at the top and the width of both listboxes to be “100%”. Finally, override the MatchCount field’s caption (double-click on it) and set it to “Number of movies matching criteria:” (accept the warning about the caption binding being removed).

One important form guide feature is the ability to display fields in different ways. In other words, if your field is a listbox, for example, you aren’t limited to displaying it as a traditional listbox. You could choose to display it as a series of checkboxes or radio buttons, for example, or you could create your own custom control using FlexBuilder.

GB provides a checkbox control type which will suit our needs perfectly because while our listboxes are single-selection only, using checkboxes will allow the user to remove a previous selection which is important if they previously filtered by actor, for instance, and now they want to remove that filter.

For the ActorList and CategoryList fields, set their “Display field as a” property to “Check Boxes”.

At this point, the settings for the ActorList (and CategoryList) fields should look like this:

and your form guide hierarchy should look like this:

Movie Listings Panel

The second panel is a lot simpler since it just shows the Listing table’s contents and it doesn’t require as much settings.

Insert a second panel into the “Movie Catalog” section, give it a title of “Movie Listings” and set its layout to be “Repeater Grid”.

The objects named “Repeater First Column” and “Repeater Second Column” don’t apply to this type of repeater panel however they do matter in other repeater layouts and are there for consistency (should you decide to change the repeater panel type). The “Trailer” object signifies that all objects placed after it, on this panel, will go below the grid as opposed to being part of the grid (this would be good for footer objects, if we had any).

Drag the MovieRow subform (table row) into the panel between the “Repeater First Column” and “Repeater Second Column” objects (drop the subform directly in between the two objects — if you miss, just drag each object back to where it’s supposed to go).

For each field you dragged-in, set its caption as follows: “Title”, “Actor”, “Category” and “Cost”. (You should see these changes in real-time in the Panel Preview pane.) Select the Title item and set its width to 150 (which means pixels in the form guide) to ensure the titles are completely visible and then set its “Allow field to repeat” property to indicate that it, and all associated fields, should be repeated within the grid layout. The items in the panel will then get a yellow outline indicating that they are repeating items.

Now that we’ve set this up, I’ll follow-up on a comment I made in part 1 when we designed the Listing table and set the MovieRow to have 1 initial instance: There’s a bug in the Repeater Grid panel layout where the data entered into the fields in the grid will not be rendered (it’s there, you just can’t see it) unless there’s some data in the grid when the form guide is initialized. To work around the bug, we simply include an initial instance of the MovieRow and then the GetMovies result handler code simply removes the instance prior to populating the table with movie results (whether there are any or not).

The last step in setting-up this panel is to apply a Display Rule to indicate when the panel should be visible (accessible to the user) in the form guide. What we want to do is set the panel to be visible only if the MatchCount field’s value is greater than zero, meaning there’s at least one movie result from the query. To do this, you simply toggle the “Specify panel display rules” pane in the panel’s properties, choose “Use Display Rules”, add a rule, set MatchCount as the field, “greater than” as the condition and “0″ as the value.

FormBridge XFO Fix

Now that the form guide has been designed, the
re’s just one more thing we need to do: Apply a small fix to the FormBridge code that brokers the communication between the form guide and the PDF at runtime. The FormBridge code is normally automatically injected into the PDF when it’s generated by the GB Preview functionality or by LiveCycle when the form is rendered as a form guide with the PDF however we need to use our own “fixed” version of the FormBridge code. Otherwise, when we flip to the PDF, there will be no data in the table.

To do this, save your changes to the form guide and exit GB. Find the “Custom” pane in Designer’s Object Library and drag the “Form Bridge” object onto your form below the GuideObjects subform (where there are no objects on the page).

It shows-up as a hairline selection on the page and in the hierarchy looks like this:

Select the “ContainerFoundation_JS” script object and open the Script Editor to edit the script. Find the two instances of “saveXML()” (lines 316 and 631) using the Find dialog (Ctrl + F) and change them from

saveXML().replace(/\n/g, "");

to

saveXML();

Do not remove/change any of the code that comes before it on the same line. This fix ensures that the format of the data going across the line is correct.

With the FormBridge object in our form, GB Preview and LiveCycle will not inject their version into the PDF. The only draw-back from this approach is that if the FormBridge code changes, you’ll have to manually update it in your form as opposed to automatically getting the new version when you preview with GB or render your form with LiveCycle.

This bug should be fixed in a future release and so the workaround in the FormBridge code will eventually no longer be needed.

Flash Log and Debug Players (Optional)

You may have noticed some “trace()” statements in the code we set on the ActorList, CategoryList and GetMovies objects in part 2. This is a handy way to get a read on what’s going on (i.e. debugging) inside the form guide at runtime if you aren’t using FlexBuilder to debug it (which we’re trying to avoid in this tutorial). It’s a lot like using “console.println()” to output information to Acrobat’s JavaScript Console.

If you want to see trace statement outputs (it’s not necessary but it could be handy), you need to look at your flashlog.txt file which is auto-generated by the debug version of the Flash Player. These are normally called “debug players” or “content debuggers” and are downloadable here. To ensure that you have a debug player, you can hit this page which will tell you what version and type of Flash Player your browser is using.

Once you’ve installed a debug player, you’ll need to configure your system to enable the flashlog.txt file which will be located here, once enabled: C:\Documents and Settings\user_name\Application Data\Macromedia\Flash Player\Logs\flashlog.txt (XP) or C:\Users\user_name\AppData\Roaming\Macromedia\Flash Player\Logs\flashlog.txt (Vista).

The debugger configuration page details where to place the mm.cfg file and what to put in it in order to enable output to the flashlog.txt file. For example, if you’re running XP, you would create a new mm.cfg file in your “C:\Documents and Settings\user_name\” folder and you would put the following lines inside to enable error reporting and trace logging (i.e. output to the flashlog.txt file):

TraceOutputFileEnable=1
ErrorReportingEnable=1

Running the Solution

Now that the form guide is designed, we’re ready to run our solution: Launch GB again and this time, choose the Preview tab, select “Include PDF Preview” (to ensure that a PDF is included, otherwise you won’t be able to flip to it to see the results) and click on the Preview button.

The resulting form guide should look like this (with the pre-loaded actor and category lists):

When you click on the “Get Movies” button, the button will become temporarily disabled and then, assuming your query returned movies, the count should be updated and the “Movie Listing” panel should appear in the left toggle bar:

Now click on the “Movie Listing” panel to see the results in the form guide:

Finally, click on the “Show PDF” icon in the toolbar at the top-right to see the results (i.e. imported Movie Service data) in the PDF:

Cool? I think so! And the cherry on top is that this even works with the free Reader! Users don’t need Acrobat in order for the data to go back and forth between the form guide and the PDF.

Solution to Part 3

Try not to peek at this before you attempt to build the form guide on your own…

Download Part 3 [zip]

Minimum Requirements: Designer 8.2.1 SP1, GuideBuilder 8.2.1 SP1, Reader 9.0.

Note: If you decide to deploy this sample to LiveCycle (e.g. using FormsIVS), you’ll also need to deploy the styles SWC you created earlier. The form guide will not render without it.

There’s a feature in Acrobat’s scripting object model that lets you determine the status of a DigSig field (i.e. whether it’s signed or not): It’s the AcroForm Field object’s signatureValidate() method which returns a status code indicating the state of the signature field. In particular, the method returns 0 if the DigSig field is empty (hasn’t been signed) and 4 if the DigSig applied is valid and the identify of the signer was verified.

Note: This method cannot validate the status of an XML Data Signature which is different from a traditional DigSig.

Accessing the AcroForm Field Object

To access the AcroForm Field object that represents the XFA DigSig field in your form, you have to use the AcroForm Doc object’s getField() method and give it the name of the field you’re looking for.

To access the Doc object, you simply need to access the event.target property in any XFA event. This property is the Doc object. From there, you call getField() and you give it the name of the DigSig field as it’s defined in the AcroForm DOM. That’s the tricky part: Your field’s full name is its SOM expression (shown here for a DigSig field in a page subform named “PageSubform1″):

xfa.form.form1.PageSubform1.SignatureField1

however its AcroForm Field Name looks like this:

form1[0].PageSubform1[0].SignatureField1[0]

Fortunately, I’ve already written some JavaScript that generates the above syntax: Copy and paste the script from my AcroForm Field Name Generator into your event and all you have to do in your script is call GetFQSOMExp(DigSigField) where “DigSigField” is the XFA DigSig field whose AcroForm Field name you can to get.

From there, you simply make a call to the signatureValidate() method:

var status = event.target.getField(GetFQSOMExp(DigSigField).signatureValidate();

switch (status)
{
    case 0:
    case 1:
        // not signed...
        break;

    case 2:
        // invalid signature...
        break;

    case 3:
        // valid but identity of signer cannot be verified...
        break;

    case 4:
        // valid signature...
        break;

    default:
        // error -- unexpected status code
        break;
}

PreSign and PostSign Events

A key component to making this work is the ability to verify the status of the signature after the user has interacted with the DigSig field. You may think of using either the Click or MouseUp events on the DigSig field however there’s a bug in Acrobat/Reader 9 (and older) that prevents the Click and MouseUp events from coming through if the user successfully applies a signature (if they cancel-out of the digital signature dialog that appears when they click in the DigSig field, the events fire but not if they apply a signature).

Fortunately, XFA 2.8 includes new PreSign and PostSign events which occur just before and immediately after clicking on the DigSig field and they behave correctly. The only drawback here is that they are only available for scripting in Designer 8.2 and only work in Acrobat/Reader 9 or greater.

Note that if you wanted to check for signature status on start-up, the DocReady event is the correct place to do it. Initialize, FormReady and LayoutReady events are too soon in the initialization sequence for signature status to be available.

Sample Form

Getting back to our use case where we want to show the submit button only once the user has signed the form, you would simply script the DigSig field’s PreSign event to show the button and then the PostSign event to check the status of the signature. If it’s not valid (the user didn’t apply a signature or there’s something wrong with the signature that was applied), you would then hide the submit button again.

The reason why you would show the submit button in PreSign and hide it again in PostSign is because showing the button in PostSign after applying a good signature would invalidate the signature’s status (the status would become “unknown”) because the form would be modified after signing. By showing the button after signing when it was hidden prior to it, the form would no longer be the state in which it was when it was signed (which is one reason for DigSigs in the first place — to ensure that the document is in the same state as which it was when the user signed it, otherwise the document may have been maliciously modified between the time when the user signed it and the time at which you received it).

Download sample [pdf]

(Note that you’ll need a digital ID to run the sample; if you don’t, you can easily create one in the digital signature dialog that appears when you click on the DigSig field.)

Sample Minimum Requirements: Designer 8.2, Acrobat 9.0

Normally, setting a field’s rawValue property to null essentially clears its value. It should follow that setting a radio button list’s rawValue property would clear its selection (i.e. if one of its radio buttons was selected, none would be selected when its value is set to null).

To clear a text field, for example, you would do the following:

MyTextField.rawValue = null;

To clear a radio button list, the following should also work:

MyRadioButtonList.rawValue = null;

The issue is that the above statement for clearing a radio button list doesn’t work: The selection remains and the radio button list’s rawValue property remains set to the value of the selected radio button.

Workaround

There are two workarounds to this issue. The first consists of clearing the data node associated with the radio button list, provided the radio button list is bound to data (which means the “Object palette > Binding tab > Default Binding property” is set to something other than “None”):

MyRadioButtonList.dataNode.isNull = 1;

Note that if you attempt to use this workaround when the radio button list is not bound to data, an error will occur because its dataNode property will be null and you’ll attempt to access the isNull property of a null object.

The second workaround consists of using the xfa.host.resetData() method to clear the radio button list:

xfa.host.resetData(MyRadioButtonList.somExpression);

The advantage of the second workaround is that it will work regardless of whether the radio button list has a data binding or not.

Fix

Please refer to the Bug List for updated information on the version(s) affected by this bug as well as if and when it was/will be fixed.

Make it so

I think one of the most significant improvements to the functionality is that what you set in Designer is what you get in Acrobat. In the past, given certain circumstances, the order you set in Designer was not necessarily the order you would get in Acrobat. Designer 8.2 and Acrobat/Reader 9, together, fix that issue.

For example, this view shows the new Tab Order palette where tab order is set to “Automatic” which means the order depends largely on the visual placement of fields on the form, from left to right and top to bottom:

In this next view, I’ve simply moved the City field below the Country field. As you can see in the tab order list, City is now last in tab order simply because it’s positioned below the Country field (and it’s also highlighted in the list because I have it selected on the canvas):

Tab Order palette

The Tab Order palette is how you work with tab order in Designer 8.2. While there is still a “tab order mode”, you no longer (attempt to) set the order by entering tab order mode and clicking on fields on the canvas in the order you want tab order to be set. Instead, you do everything from the palette (sequence numbers are still displayed over the fields and you can still click on them to select their corresponding item in the tab order list within the Tab Order palette but the order itself is no longer set by clicking on the canvas).

Before we go any further, there’s some extra visual aids for tab order which you’ll want to turn-on (if anything, they’re really cool). In the “Tools menu > Options command > Tab Order tab”, set the “Display Additional Visual Aids for Tab Order” setting:

Now select the Tab Order palette (“Window menu > Tab Order command”) and you’ll automatically be entered into “tab order mode” (if not, click on the “Show Order” button on the palette):

Once this is done, set the order to “Custom” so that you can set the order you want.

To get a feel for what the order is (now that you’ve enabled the “additional visual aids”), you can simply mouse-over the fields on the canvas:

(In the above screen shot, my mouse is hovering over the City field.)

Setting the order

Using the object list in the Tab Order palette, the order can be set in many different ways:

• drag and drop the items in the list
• multi-select items in the list and drag & drop them
• make a selection and use the arrow buttons to move them around
• select one item and hit the F2 key to manually set its sequence number
• make a selection (either with the mouse or the keyboard) and change the order by holding the Control key while using the up/down arrow keys
• cut and paste a selection using the items in the palette menu

Form Fragments

The Tab Order feature also handles form fragments gracefully and treats them as “white blocks”. Following my address block example, if you make a fragment out of the City, State and Zip fields, that object is now treated as a single object. The tab order can’t be changed from the reference to the fragment (i.e. the tab order of the fields inside the fragment can’t be changed from the form that references the fragment) but it can be changed around it:

In order to change the tab order inside the fragment, you’ll need to edit the tab order in the fragment itself.

Text Objects

Finally, the revamped Tab Order feature is also capable of handling text objects. This comes in handy especially when you have a hyperlink somewhere in a text object and you want to control where, in the tabbing sequence, that focus jumps to the hyperlink and where it goes to afterward.

In order to set the tab order of a text object, you must uncheck the “Tools > Options > Tab Order > Only Show Tab Order for Fields” option in the Tab Order Properties Dialog (checked in the linked screenshot: you must uncheck it).

After applying the above setting, the Tab Order Palette will show all form objects, not just fields.

Apr 3, 2010 — Added “Text Objects” section

Steve, a colleague of mine who works on LiveCycle Designer ES, wrote two posts about this technique a while back. I’ve frequently referred to it in my replies to your comments on various posts so I thought I would include the links in a more prominent place so they’re easier to find:

1. The original HTTP Submit post.
2. An important update to the original post.

One use of this could be to make submitting data to a database more secure* than exposing the database on the Internet (which is seldom a good idea). For example, you could have your form’s data posted to a PHP page which could then relay it into a MySQL database running behind the scenes. Another popular combination is ASP and Microsoft Access databases.

* Please note that I cannot speak to the level of security of said suggestion/solution. I’m merely suggesting it could be more secure.

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

When changing a table’s column widths via the table object’s “columnWidths” attribute, the table’s columns will not be rendered correctly.

For example, consider the following table:

Clicking on the “Expand Columns” button sets the width of the first column to 2 inches and the width of the second column to 3 inches with the following script:

Table1.columnWidths = "2in 3in";

In Acrobat 8.0 or earlier, this is the result:

The problem is that the table’s layout hasn’t been properly updated after the changes to its column width attribute.

Workaround

Fortunately, there’s a simple workaround to this problem which consists in forcing an update to the layout after setting the column widths of a table:

Table1.columnWidths = "2in 3in";
xfa.layout.relayout();

Note that a lot of these table rendering issues have now been addressed in Acrobat/Reader 8.1.

When using the above workaround or Acrobat/Reader 8.1, this is the result you get:

Fix

Please refer to the Bug List for updated information on the version(s) affected by this bug as well as if and when it was/will be fixed.

If an exception is thrown during a web service (WSDL) data connection request call (you’re executing a request to a web service in order to get a response in return), the bound data accumulated by Acrobat (for submitting the request to the web service) is not cleared from the data connection’s "request data buffer/queue" (to put it in simple terms).

For example, if your form attempts to execute a WSDL data connection while there is no active connection to the Internet, the call to the

xfa.connectionSet.WSDLConnectionName.execute

method will fail with an exception (which you can catch by placing the call within a try-catch block) however the form data accumulated to be sent as part of the request operation isn’t cleared. If you are then resetting the form by clearing repeatable subform instances that contained data at the time the data connection was executed and then re-execute the data connection, the old instance data will still be sent as part of the new request even though it’s no longer part of the form (which is clearly not what you would want/expect).

Workaround

Fortunately, you can manually clear the "request data buffer/queue", located in

xfa.datasets.connectionData.WSDLConnectionName

where "WSDLConnectionName" is the name of your WSDL data connection, simply by using the "remove" function as follows:

xfa.datasets.connectionData.WSDLConnectionName.remove();

Fix

Please refer to the Bug List for updated information on the version(s) affected by this bug as well as if and when it was/will be fixed.