Archive for June, 2006

Sorting Lists at Runtime

Have you ever needed to sort the content of a list box or drop down list at runtime (e.g. in a form loaded in PDF with Acrobat or HTML with a browser)?

Unfortunately, neither the XFA nor the AcroForm Object Models give you either properties or methods to achieve this functionality. The only thing available are Sort Ascending and Sort Descending buttons on the list of items you define in the Object palette’s Field tab in Designer — not very useful at runtime! Say you were loading data from an XML Data File into your form and this was populating a list with values that needed to be sorted: There wouldn’t be a built-in way for you to do that.

The only solution I’m aware of at this time is to flex your scripting muscles and write some functions that’ll get you sorting lists (from either list boxes or drop down lists) and that’s exactly what I did today while replying to a post on Adobe’s Designer Forums:

Download Sample [pdf]

Minimum Requirements: Designer 7.0, Acrobat 7.0.

Update: It looks like Acrobat 8.0 broke something that prevents my sample form from working correctly. It has to do with the call to

resolveNodes(“#items[*]“)

Fortunately, the bug will be fixed in Acrobat’s next release.

As a workaround, I would encourage you to have a look at the new list object properties and methods now available in Acrobat 8.0. You should be able to use a combination of those new properties/methods along with some of the original script in this sample in order to come-up with an update solution that works.

All the code is located in the script object appropriately named, “ScriptObject”.

The idea was to make use of the JavaScript Array object’s built-in sorting function, sort, by giving it a custom sorting function that was able to sort pairs of text and value items. Remember that for XFA choiceList fields, there’s always one <items save=”1”> node but there may be a second <items> node if text and value items are defined.

From Designer’s UI, you define value items by default by entering items in the list on the Object palette’s Field tab. This defines an <items save=”1”> node. If you then go to the Bindings tab and specify values, the items you specified on the Field tab become the “text” items, defined in the second <items> node, and the values are set in the <items save=”1”> node.

When sorting the list, it’s important to maintain the association between text and value item pairs and that’s why the script is a little complex — not to mention the fact that getting items out of an XFA choiceList field (list box or drop down list) isn’t as easy as 1-2-3 either!

So the script attempts to find text and/or value items, create ListItem objects for each pair, sort them using the custom sort function __SortFunction and then replaces the current items in the list with the ones in the sorted order.


Updated: April 11, 2007

Process All Fields

A common requirement on the “Adobe Designer Forums”:http://www.adobeforums.com/cgi-bin/webx/.3bb7d189/ is to find all fields on a form and do something specific with them.

For instance, you may want all mandatory fields to be automatically highlighted when a user attempts to submit a form electronically before having filled all mandatory fields. While Acrobat provides a button to toggle mandatory field highlighting on/off (via the _Highlight required fields_ check box in the yellow Form Field toolbar), Acrobat’s Scripting Object Model doesn’t provide a function to do the same. Therefore, you’re left having to write some script to achieve the same functionality.

Since this is requested so often, I thought I would try to put together some canned script that you can copy and paste into your form in order to instantly have the ability to make changes on everything that’s considered a field on your form.

“Download Script [js]“:http://blogs.adobe.com/formbuilder/samples/ProcessAllFields.js
“Download Sample [zip]“:http://blogs.adobe.com/formbuilder/samples/ProcessAllFields.zip

*Minimum Requirements:* Designer 7.0, Acrobat 7.0.

Continue reading…

Invalid Flashing Fields

So what’s the use of learning about new toys like “AcroForm Objects”:http://blogs.adobe.com/formbuilder/2006/06/acroform_objects.html and “AcroForm Field Name Generators”:http://blogs.adobe.com/formbuilder/2006/06/acroform_field_name_generator.html if you don’t take the time to play with them? Today felt like the right day to do just that and I came-up with a sample form where invalid fields flash red until the user has entered valid values into them. Only once all fields are valid can the form be submitted.

%{color:red} *Update:* Check-out the newer version on the new “Invalid Flashing Fields 2.0″:http://blogs.adobe.com/formbuilder/2006/08/invalid_flashing_fields_2.html post. %

“Download Sample [pdf]“:http://blogs.adobe.com/formbuilder/samples/AcroFormObjects/InvalidFlashingFields.pdf

*Minimum Requirements:* Designer 7.1, Acrobat 7.0.5.

*Note:* A basic understanding of “AcroForm Objects”:http://blogs.adobe.com/formbuilder/2006/06/acroform_objects.html is required for this sample.

Continue reading…

AcroForm Field Name Generator

So you’ve read my previous post about “AcroForm Objects”:http://blogs.adobe.com/formbuilder/2006/06/acroform_objects.html and now you’re wondering what you do with that stuff. Those more adventurous might even have tried to use the _event.target.getField_ method to do something cool.

If you’re going to do things on the application or the document without attempting to affect a specific field, it’s pretty straight-forward: You just call methods on the _app_ (Acrobat Application) or _event.target_ (Acrobat Document) objects. Getting an AcroForm Field object, however, isn’t as simple as you may think because of the naming conventions used when the Acrobat Form objects are created, based on the XFA Form objects.

Let’s say you have a field, named “MyField”, parented to the second page, named “Page2″, of your form, named “form1″. For some reason, you need to access that field’s pertaining AcroForm Field object. If you tried

bc. event.target.getField(“MyField”)

you wouldn’t get very far because the actual name of the field is:

bc. form1[0].Page2[0].MyField[0]

Basically, each AcroForm Field object is named with a _verbose_ form of the “XFA SOM Expression”:http://blogs.adobe.com/formbuilder/2006/06/som_expression_generator.html of its pertaining XFA Form object (also known as a *Fully-Qualified SOM Expression*).

Continue reading…

Adobe Developer Week

I just got word of this *free* online event this week at “Adobe”:http://www.adobe.com.

Here’s the blurb:

bq. Join us to learn about the Adobe engagement platform, including Flex, and other Adobe technologies by attending “Adobe Developer Week”:http://www.adobe.com/cfusion/event/index.cfm?event=detail&id=452429&loc=en_us. This free, week-long event features live, online sessions presented by Adobe technology experts. See live demos and get your questions answered by the experts during interactive Q & A sessions. Register online at the “Adobe website”:http://www.adobe.com/cfusion/event/index.cfm?event=detail&id=452429&loc=en_us.

While there are lots of very interesting sessions, these are the ones I found, after a quick search, which are related to *LiveCycle*:

* “Increase Efficiencies by Automating Form-Based Processes”:http://www.adobe.com/cfusion/event/index.cfm?event=detail&id=456344&loc=en_us
* “An Introduction to Adobe LiveCycle Workflow and QPAC Development”:http://www.adobe.com/cfusion/event/index.cfm?event=session&id=452730&loc=en_us
* “Building Applications Using LiveCycle and Flex”:http://www.adobe.com/cfusion/event/index.cfm?event=session&id=452738&loc=en_us

Don’t wait to sign-up for sessions — spots are limited and they’re going fast!

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.

Continue reading…

XFA SOM Expression Generator

Have you ever had trouble figuring-out what the SOM expression is for a particular object which you’re trying to address within your script?

If so, here’s a tip that might come in handy the next time you’re stumped:

With the input focus (the “I” beam) set within the event you’re scripting on the Script Editor palette in Designer, hold-down the Control key and move your mouse over the canvas. Notice that as you hover over objects, the mouse pointer switches to a “V” cursor. If you click, the full SOM expression for the object you clicked will be automatically inserted into your script. But that’s not all! The generated SOM expression will be automatically formatted to work with your script’s language settings:

If you haven’t named the “page 1″ subform and you pick an object on it, you’ll get the following code if your script’s language is FormCalc:

bc. form1.#subform[0].myField

If your script’s language is JavaScript, you’ll get the following code (for the same object):

bc. xfa.resolveNode(“form1.#subform[0].myField”)

Note that if you click on the object on which you’re scripting the event, “$” will be inserted for a FormCalc script and “this” will be inserted for a JavaScript script.