oneOfChild Scripting Property

Sometimes it’s necessary to access the properties contained within a field object’s UI property. For example, you might want to highlight only the content area (the value portion as opposed to the caption portion) of a text field. The problem with doing that is that you need to access the UI property’s one-of property in order to get at the Border object that it contains. The "ui.{one-of property}.border" object controls the appearance of the field’s content area. (Tip: It’s also the object that’s affected when you use the Appearance property on the Field tab in the Object palette).

If you were to look at the XFA specification supported by Designer 7.1, you would find, on page 664, that the UI element contains various one-of properties (which describe a set of properties from which only one may be specified at any given time) which vary depending on the type of field you’ve created on your form. For example, if it’s a text field, it has a

field.ui.#textField

property whereas a drop down list would have a

field.ui.#choiceList

property.

Based on the various definitions of XFA fields, you would have to write the following script to change a text field‘s content area color (shown here in FormCalc):

$.ui.#textField.border.fill.color = "255,0,0"

But what about a drop down list? Because it uses a different UI one-of property ("choiceList" instead of "textField"), you would have to write the following script (shown here in JavaScript) to change its content area color:

this.ui.resolveNode("#choiceList").border.fill.color.value = "255,0,0"

This is all fine as long as you know the type of object on which the script will be executed but what if you wanted to change the content area color of all fields on your form? You might decide to define multiple arrays that contain references to text fields, numeric fields, etc. (one array for each type) but that wouldn’t be very practical because you would have to remember to keep that list up-to-date for every change you made to your form.

A much easier way to do this is simply by using the oneOfChild scripting property: It’s designed to return a reference to the one-of property that has been specified in the Object Model on the object on which it is used. In other words, if you used it on a text field‘s UI property, it would represent the "#textField" property whereas on a drop down list, it would represent the "#choiceList" property.

If we put this in practice, it means you could use the following script to change the content area color of any field object you find on your form (shown here in FormCalc):

FieldObject.ui.oneOfChild.border.fill.color = "255,0,0"

where "FieldObject" would be a variable holding a reference to a field object on your form.

Of course, the use of the oneOfChild property also works because the Border property is common to all UI one-of properties. There are some cases where some properties are specific to a certain "UI type" (like the "#choiceList.textEntry" property). In those cases, you may need to verify that you are, in fact, attempting to access those properties on the right kind of UI one-of property or else you’ll get a scripting runtime exception.

Bug: Unable to Set Caption or Value Font Separately

Description

I was showing someone how to use Designer 7.0 today and came across a bug in the Font palette. I was trying to show them how to make the caption of a text field bold without making the value bold using the Bold (“B”) button on the Font palette however I could only change both the caption and value fonts together, not separately as one should be able to do using the selector control located at the top of the palette (which reads, “Currently editing Caption and Value…” by default).

Using the selector control, you should be able to set it to “Currently editing Caption properties…”, press the bold button and make only the caption font bold. Unfortunately, that’s not what happens. Instead, both fonts (or, the entire field) is changed to bold.

Rest assured, this bug was immediately fixed in Designer 7.1 — a highly-recommended upgrade because tables were introduced in that version, amongst other things.

Workaround

The good news is that there’s a simple workaround using script. All you need to do is use the Font palette to make sure that the Bold button isn’t activated (that the field isn’t bolded) and then set the following FormCalc script statements on field’s Initialize event using the Script Editor palette:

$.caption.font.typeface = "Myriad Pro"
$.caption.font.weight = "bold"
$.caption.font.size = "10pt"

Feel free to specify a different font name or point size if you like although I would recommend using the same font name and point size as you specified in the Font palette so that the result doesn’t differ too much from what you see on the canvas.

Finally, preview the form as PDF using the canvas’s PDF Preview tab. When the form is initialized (loaded) in Acrobat, the field’s caption font will be set to the type, weight and size you specified.

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.

Expanding to Fit the Entire Value

A while ago, I posted an article detailing a trick to make the value of a field be displayed entirely within the field’s content area. Essentially, by setting the value font size to zero, this tells Acrobat to shrink the field’s content area (value) font at will to make the entire value entered fit horizontally. This can certainly be useful but there’s one significant drawback: the value font may shrink such that it becomes too small for anyone to read depending on how much data the user enters into the field.

Fortunately, there’s an alternative method to making a value fit within a field’s content area when you don’t know how long the value will be: Making the field’s width and/or height expandable!

The advantage of this solution is that the value font’s size remains constant (the same as which you specified it to be when you designed the form). When a field is make expandable, its "w" (width) and/or "h" (height) attributes are replaced by "minW" (minimum width) and/or "minH" (minimum height) attributes, respectively. These attributes define the initial and minimum size of the entire field (that is, its caption and content areas combined). When the width is extended, however, only the field’s content area is increased in width. Its caption area remains the same width. On the other hand, causing the height of a field’s content area to be extended will also cause the caption area’s height to be extended.

Making a Field Expandable

Specifying that a field’s width and/or height is to expand to fit its content is quite simple: You just need to check the "Expand to fit" check box that pertains to the width and/or height property on the Layout palette.

Getting a Tight Fit

So far, you’ve learned how to make a field’s width and/or height expandable, essentially by specify a minimum width and/or height instead of a set width and/or height. Now what if you wanted to ensure that the field’s width and/or height was always just wide enough to contain whatever value was entered? For example, you don’t want a whole bunch of empty space if you set a minimum width of 2 inches to have a nice initial size to enter a value into the field but the user only entered a value that required 1 inch to be entirely displayed.

In that case, you could simply set the minimum width to zero when the user leaves the field, if they’ve entered a value. This is done by scripting the field’s Exit event (shown here in FormCalc):

$.minW = "0"

Look-out for Long Values!

One thing you have to look-out for is extra long values — especially if you haven’t specified a maximum length for the field. If the user enters too much data, the field might simply run off the page.

If you don’t want to set a maximum data length for the field but you don’t want it to expand beyond a certain width, you can set a maximum width and/or height. Since Designer’s UI doesn’t let you set this property directly, you can use the field’s Initialize script to set it (shown here in JavaScript):

this.maxW = "4.5in"; // max width of 4.5 inches

Note, however, that if the user enters more data than can fit within the specified maximum dimensions, the value will be cut-off and won’t print so you may consider setting a maximum data length or resorting to the previous solution (setting the font size to zero).

Sample

This sample form implements the solution I’ve described in this post.

Download Sample [pdf]

Minimum Requirements: Designer 7.x, Acrobat 7.x.

Scripting Table Columns

A few days ago, Sergio, one of my regular commenters, posted a question about programmatically adding new columns to a table. My reply to his comment quickly turned into something that I thought should be promoted to a blog post so here it is.

This question required some investigation because it led me to the discovery of a bug related to adding/removing instances of a table column in a form viewed in a version of Acrobat prior to 8.0. More on that later in this post.

The short answer to Sergio’s question is that yes, in fact, you can modify the set of columns in a table programmatically at runtime. You can do this by either using the presence attribute — although this isn’t recommended because it can lead to data merging problems — or you can use Instance Managers to do it, which is the recommended method to use.

Here’s a sample form that contains a table with a “repeatable column”. Using the add and remove buttons that are provided, you can add and remove instances of the 3rd column.

Download Sample [pdf]

Minimum Requirements: Designer 7.1, Acrobat 7.0.5.

Continue reading…

Using URL Requests in PDF Forms

Here’s a sample in response to “Ernest’s question”:http://blogs.adobe.com/formbuilder/2006/09/selecting_specific_database_records.html#comment-49371 on passing values to PDF forms via URL. His intent is to use it to provide a key to a PDF form such that it can be used to filter records from an “ODBC Data Connection”:http://blogs.adobe.com/formbuilder/2006/09/selecting_specific_database_records.html in order to pre-populate the form with data.

I love these kinds of questions because they challenge me to find answers!

Of course, this is quite specific but there are many other uses for this. In fact, you could have a whole lot of fun with it too! You could even use this to alter the appearance of your form: Say you had one form that you were using for multiple departments in your company and every department had its own header. You could place each header in a subform, make them all hidden and then, based on the URL request which would include a department code, decide which one to show — no XML Data file, database connection or web service needed!

Beware, however, that URL request strings are *not secure* because they get posted in plain text for anyone to read so be careful of the information you pass-in to your form this way.

This sample form looks for a “message” and a “color” key in the URL request in order to show a message in a text field and change the text field content area’s color (an RGB value). For example:

* == //URLRequests.pdf?message=Isn’t%20this%20cool%3F == — Shows the message “Isn’t this cool?” in the text field.
* “//URLRequests.pdf?message=Think%20of%20the%20possibilities…&color=0%2C255%2C0″:http://blogs.adobe.com/formbuilder/samples/URLRequests.pdf?message=Think%20of%20the%20possibilities…&color=0%2C255%2C0 — Shows the message “Think of the possibilities…” in the text field and makes the text field green.

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

*Minimum Requirements:* Designer 7.0, Acrobat 7.0.

Continue reading…

Displaying All Records from an ODBC Data Connection

So far, I’ve covered two ways of connecting forms to ODBC data sources:

# “Connecting a Form to a Database”:http://blogs.adobe.com/formbuilder/2006/09/connecting_a_form_to_a_database.html — explains how to design a form which lets the user iterate through each record one at a time; and
# “Selecting Specific Database Records”:http://blogs.adobe.com/formbuilder/2006/09/selecting_specific_database_records.html — takes the first tutorial one step further by providing a means to specify which record(s) to view.

This time, in response to “Y. Gautham’s recent comments”:http://blogs.adobe.com/formbuilder/2006/08/importing_data_in_acrobat.html#comment-39853, I’ve decided to post a little tutorial on *displaying all records* from an ODBC data connection for reporting purposes (as opposed to editing).

Continue reading…

FormCalc Expressions (Foreach)

A couple of weeks ago, I started a series of posts on FormCalc Expressions. The first ones I convered were the “If and For expressions”:http://blogs.adobe.com/formbuilder/2006/09/formcalc_expressions_if_and_for.html. This time, I thought I would explain the Foreach expression.

Continue reading…

Image Field Z-Order Problems

h2. Description

If you’ve ever tried to use an image field’s contents (an image) as the background for a form and wanted to let the user change it at run-time, you’ve probably run into problems if you had placed objects on top of this image field. The most common result is the image field’s contents always appears on top of all other fields which are technically higher in z-order (“in front” in the hierarchy) than the image field.

While this may seem like buggy behaviour, it’s not technically a bug and I’ll try to explain why it isn’t.

The behavior occurs because of the way image fields are translated from XFA objects to “AcroForm objects”:http://blogs.adobe.com/formbuilder/2006/06/acroform_objects.html when your form is saved as a PDF and rendered in Acrobat.

The PDF format has a definition for what is called an _Annotation_ object which represents essentially all the “extra” stuff you can add to PDF documents such as comments, stamps, highlighting, etc. When it comes to image fields, their contents is actually an Annotation in the PDF layer as opposed to contents in the XFA layer. Since the PDF layer is above the XFA layer, Annotations can’t be placed behind objects on the XFA layer — hence why the contents of an image field is always displayed above any objects that may be “in front” of it in the XFA hierarchy (z-order).

Continue reading…

Selecting Specific Database Records

Every now and then, someone posts a comment with a question on how to do something and the answer requires more than just a quick response. In this case, it was “Ricardo’s question”:http://blogs.adobe.com/formbuilder/2006/09/connecting_a_form_to_a_database.html#comment-34179 on how to select a specific record from a data connection to a database for editing in a form.

If you read my previous post on “Connecting a Form to a Database”:http://blogs.adobe.com/formbuilder/2006/09/connecting_a_form_to_a_database.html, you might’ve realized that the result was a single live data connection to the entire set of records in a database. This is great if you want to iterate through all records one at a time and update them on an individual basis. You might’ve also realized that you could narrow the scope of the data connection by specifying a more specific SQL statement (with a _WHERE_ clause, for example). But what if you wanted the form to filter, on the spot, the data loaded from the data connection? For example, you might want to let the user pick from the different movie categories (action, comedy or drama) and then let them iterate through only that subset of the Movie Database.

If you’ve been scratching your elbow, pinching your nose and blinking your eyes in hopes that this might “just work”, well, it’s actually scratch your nose, pinch your elbow and roll your eyes — ok, just kidding…

Continue reading…

Getting a List’s New Selection

Have you ever struggled to figure-out what item from a list (list box or drop down list) a user had just selected in the list’s Change event? If so, it’s possible you were trying to use the

bc. rawValue

property in order to get at this information.

Unlike other objects such as exclusion groups, the _rawValue_ property of a list object doesn’t reflect the new selection until the selected value is committed to it (by the user tabbing or clicking away from the list). That means that if you’re trying to, say, make a certain field visible at the moment when a particular item in the list is selected, you can’t use the _rawValue_ property because it still contains the _old_ (previous selection) value.

Instead, you must use the

bc. xfa.event.newText

object/property of the Change event itself and possibly the list object’s

bc. boundItem

function in order to determine the _value_ associated with the new selection.

Continue reading…