This blog has moved

Fellow Readers and Commenters,

I have finally completed the transition to my new WordPress blog: Stefan Cameron on Forms.

Thank you for being patient during the migration. The process took a little longer than I anticipated and I apologize if you’ve had to wait to ask me some questions.

This new installation will hopefully provide better performance as well as cut down on the inordinate amount of spam I was getting here (with no tools at my disposal to reduce it!). You will also find that each post now has its own comment feed so it should be easier for you to keep track of the posts that interest you and get notified when I answer a question you might have posted.

Porting to my new blog

Fellow Readers and Commenters,

In order to make it easier for me to manage my blog (thereby saving me valuable time so that I can keep replying to your comments and writing new posts), I’ve decided to move to my own blog service.

To make the transition quicker and to ensure I don’t miss any comments, I have now disabled commenting on all posts and will re-open commenting on my new blog once it is setup. I’ll do my very best to be back-up and running within the next few days.

I will post one more time here to announce the URL of my new blog.

While I’m busy working on this, you can always try the Adobe LiveCycle Designer Forums.

Merging Text Objects

Here are two really convenient features I thought I should highlight since it can really save you time, especially if you’re cleaning-up a form after importing it as "editable objects" or "flowable layout" (which usually produces dozens, if not hundreds of small text and field).

Since Designer 7.1, there are features available to you which are capable of merging text objects with other text objects or fields.

Merge Selected Text Objects

If you select multiple text objects, you’ll get a command in the context menu and in the top-level Layout menu which reads, "Merge Selected Text Objects". If you select it, all the selected text objects will be combined into one. This is useful if you have multiple text objects each pertaining to a specific sentence which you’d like to combine into a single text object:

Before the merge:

After the merge:

Notice that all formatting is retained and that the order of the sentences depends on the original location of the various text objects with respect to each other, not the order in which they were selected.

Merge As Caption

This feature makes it really easy to set a text object as a field’s caption when that field does not have a caption. When you select a single text object along with a single field which doesn’t have a caption, you’ll get a "Merge As Caption" command in the context menu as well as in the top-level Layout menu. When you select this command, the text object will become the field’s caption, retaining all original formatting:

Before the merge:

After the merge:

As with the "Merge Selected Text Objects" feature, the placement of the resulting caption depends on the location of the text object with respect to the captionless field. Here’s an example where the text object is located below the field:

Before the merge:

After the merge:

Where did that border come from?

Have you ever wondered to yourself, "where did that border come from?", when you simply wanted to set a field’s fill color? I know I did for a while until I learned about how the quirkiness of borders in XFA.

For example, if I wanted to set a field’s background (fill) color to green in a button’s Click event, the first thing I would do is:

this.fillColor = "0,255,0";

or

this.border.fill.color.value = "0,255,0";

Both methods amount to the same result which is the following:

Notice the black edge that appears around the perimeter of the field. What is that doing there? All I wanted to do was set the background color to highlight the field!

What I really wanted was this:

Is that too much to ask? All I did was set the fill color; I never messed with the edge, honestly!

In order to understand where that black edge came from and how to make it go away, we’ll need a better understanding of how borders are specified in XFA.

XFA Borders

First of all, the term "border" signifies all elements that compose the rectangular area that surrounds the entire field or the field’s value (two distinct borders). That means it’s made-up of corner, edge and fill properties, amongst others. In Designer, the field’s border is edited via the Border palette and the field value’s border is edited via the Appearance property on the Object palette’s Field tab.

Next is the fact that unlike most other XFA elements, the mere presence of the <border> element, and of some of its child elements such a <fill>, determine what the field’s border will look like. For instance, if no <border> element is specified, the field does not have a border even if the <border> element has a presence attribute with a default value of "visible". Likewise, if the <fill> element isn’t specified, the border has a transparent fill (i.e. no fill) even though it, too, has a presence attribute with a default value of "visible".

For example, the following field definition has no border:

<field></field>

If the <border> element is specified, then you also get the default <edge> element which is a thin black line and since specifying only a single <edge> element affects all sides of the border, you end-up with a black edge surrounding the border — just like in the first image above (without the green fill).

In this case, the field’s definition is simply this:

<field><border/></field>

When you use the script I proposed earlier for setting a field’s background (fill) color to green, this is what you get in the XFA syntax which describes the field:

<field>
    <border>
        <fill>
            <color value="0,255,0"/>
        </fill>
    </border>
</field>

As you can see, the <border> element has been specified and therefore the border gets the default thin black edge (even though an <edge> element wasn’t explicitly specified since an edge is implied when not explicitly specified).

Finally, edges and corners are a little tricky because there can be as little as none or as many as 4 <edge> and <corner> elements specified. What you need to remember is that they’re defined in clockwise order:

  • No <edge> element is the same as a single <edge> element which defines all edges at once (all 4 edges are identical).
  • Two <edge> elements define the top/bottom (edge 0) and left/right (edge 1) edges.
  • Three <edge> elements define the top (edge 0), left/right (edge 1) and bottom (edge 2) edges.
  • Four <edge> elements define the top (edge 0), right (edge 1), bottom (edge 2) and left (edge 3) edges.

The same goes for the <corner> element.

The Solution

So just how is it that we get rid of that edge? Well, given that the edge is implied (as mentioned earlier), all we have to do is hide it! It’s quite simple, in the end, yet quite frustrating if you don’t understand how borders work in XFA.

The <edge> element has a presence property which you can set to "hidden" in order to hide it. Therefore, the following script would set the field’s background (fill) color to green and ensure that the default black edge doesn’t appear along with it:

this.fillColor = "0,255,0";
border.edge.presence = "hidden";

That JavaScript, on a button’s Click event, will yield the border as I intended it to be (in the second image mentioned earlier).

Fun With Borders

In order to demonstrate a few things that can be done with borders using script (you may use similar scripts to show/hide borders on fields or field values for all kinds of purposes), I’ve provided this sample form. I encourage you to open it up in Designer and look at the script in order to get an idea for how you might implement your own border solution.

Download Sample [pdf]

Minimum Requirements: Designer 7.1, Acrobat 7.0.5.

ADBC Now Disabled by Default

Ever since the release of Acrobat 8.0 last November and, more recently, the Acrobat 7.0.9 update (for those still using Acrobat 7.x), I’ve had a few inquires about forms using ADBC (Acrobat DataBase Connectivity) that suddenly stop working.

The source of the problem is likely the fact that Acrobat 7.0.9 and 8.0 now disable ADBC by default, regardless of whether you were using it prior to the update or not. The reason behind this change is that ADBC poses a sizeable security risk as it doesn’t provide any mechanism to protect the databases it accesses from malicious use.

Although I wish the installation programs for Acrobat 7.0.9 and 8.0 would’ve warned users that ADBC was being disabled and provided them with information on re-enabling it rather than silently disabling it and causing people a lot of grief, I think disabling ADBC when it isn’t needed is much safer than leaving it enabled in case you ever need it.

Alternatively, you may choose to migrate to ODBC data connections in XFA forms (which you can save as PDF files for use in Acrobat). Since these are still enabled in Acrobat 7.0.9/8.0 and also make use of DSNs to locate and access databases, the migration should be relatively seamless to the people using your forms. Please note, however, that exposing a database to any type of audience always creates a certain security risk which should be assessed and addressed accordingly. You might consider creating a web service to act as the bridge between the database and your form (where your form retrieves data from and pushes data into a database via methods provided by a web service), thereby restricting access to your database’s structure and data.

For those needing to (re-)enable ADBC, the Acrobat 8 SDK Readme contains information on how to do that.
For your convenience, here is the excerpt which contains the instructions (as they were stated on December 13, 2006):

ADBC Support

Acrobat Database Connectivity (ADBC) can now be turned on and off via a registry setting. To activate ADBC, create a registry key of type DWORD with the name “bJSEnable” and a value of “true” (1) in the following location:

HKEY_CURRENT_USER\SOFTWARE\Adobe\Adobe Acrobat\8.0\ADBC

This activates ADBC in Acrobat 8.0. In previous releases of Acrobat, ADBC was active by default. In Acrobat 8.0, this setting has been changed to require user intervention to activate ADBC because most users do not want to have ADBC accessible from PDF.

Windows shell command to activate ADBC:

reg add “HKEY_CURRENT_USER\SOFTWARE\Adobe\Adobe Acrobat\8.0\ADBC” /v bJSEnable /t REG_DWORD /d 1

For Acrobat 7.0.9 users, simply change all instances of "8.0" to "7.0" in the above instructions.

Please note that since ADBC poses a security risk (as outlined earlier), Adobe does not recommend modifying the registry to re-enable this feature. Also note that ADBC is still only available via Acrobat Standard or Professional and on Windows only. The Adobe Reader does not have the ability to use ADBC.

xForms to XFA Converter on Adobe Labs

Jeff Stanier recently posted an article on LiveCycle Product Blog announcing the availability of a utility for converting xForms into XFA forms for those who are currently using xForms but would like to "leverage Adobe’s presentation capabilities."

Check it out and let us know what you think!

Accessing Objects with Periods in their Names

Did you know that periods (.) are valid characters in XFA object names? On the surface, this may seem innocent but it’s really kind of strange when you think about it — especially when it comes to writing scripts: How would you access the properties or methods of an object if had a period in its name?

Consider a simple form with a button and a text field which is named "TheText.Field". Notice the period in the text field’s name. If you wanted to write a little line of script in the button’s Click event which set the text field’s value to some arbitrary text, you would not be able to write the following:

TheText.Field = "text" // FormCalc

It would produce an error because the script engine would think that you’re referencing an object named "Field" which is a child of a parent object named "TheText" when you’re actually trying to reference the "TheText.Field" object.

If XFA allows for periods in object names, there must be a way to access them correctly. To find the answer, one of the things you can do is a little test which exposes the text field’s SOM expression (say, in the text field’s Enter event):

xfa.host.messageBox($.somExpression) // FormCalc

Doing this for the text field would give the following result:

xfa[0].form[0].form1[0].#subform[0].TheText\.Field[0]

Notice the backslash which precedes the period in the "TheText.Field" name: Backslashes are used to escape period characters in XFA names in SOM expressions.

Knowing this important detail, you could change the earlier script to the following:

$.parent.resolveNode("TheText\.Field") = "text" // FormCalc

and everything would work just fine. The resolveNode method is necessary in this case since the script engine doesn’t support backslashes in statements in FormCalc (and neither in JavaScript for that matter).

Finally, don’t forget that backslashes in strings in JavaScript are used to escape other characters such as "\n" for a new line character. This means that when you write the object’s name in the resolveNode method call, be sure to escape the backslash itself in order to give the correct expression to the resolveNode method:

this.parent.resolveNode("TheText\\.Field").rawValue = "text"; // JavaScript

New List Object Properties and Methods

Some of you may recall my tutorial on sorting lists at runtime which I posted last June. Oh how I wish I had waited until the release of Designer and Acrobat 8.0 in order to write it! With the new release of these two products comes a new API for list objects that would’ve significantly simplified things: Rather than having to know details about how list object items are represented in XFA (using an <items> node for item text values and an <items save="1"> node for item data values) and manipulating these nodes in script, I could’ve used methods such as getDisplayItem and getSaveItem.

New Properties

  • length: Returns the number of items in the list object. This property is read-only.
  • selectedIndex: Returns the zero-based index of the first-found item which is selected or -1 if the list has no selection. You may set this property in order to set a new selection in the list or set it to -1 in order to remove the selection entirely. Note that setting this property will first de-select any currently-selected items prior to applying the new selection.

New Methods

  • bool getItemState(int index): Returns true (1 in FormCalc) if the list item specified by the zero-based index parameter is currently selected in the list.
  • setItemState(int index, bool state): Add or remove a list item from the selection by specifying its zero-based index and true to select or false to de-select it (1 or 0, respectively, in FormCalc). Note that if the list object does not support multiple selection (drop down lists typically don’t), using this method will have the same effect as setting the selectedIndex property.
  • string getDisplayItem(int index): Returns a list item’s text value (this pertains to the list’s <items> element in XFA) based on a zero-based index into the list.
  • string getSaveItem(int index): Returns a list item’s data value (this pertains to the list’s <items save="1"> element in XFA) based on a zero-based index into the list.
  • bool deleteItem(int index): Deletes the list item specified by a zero-based index and returns true (1 in FormCalc) to indicate that the item was effectively deleted.

Demo Form

In order to show-off this cool new API (available in both JavaScript and FormCalc), I designed a little form that uses all the new properties and methods. Play with it in Acrobat 8.0 and check out the script in Designer 8.0. I’m certain it’ll make your life a whole lot easier when it comes to scripting list boxes and drop down lists.

Download Sample [pdf]

Minimum Requirements: Designer 8.0, Acrobat 8.0.

Note that you must click away from the "List Box" object after you’ve set a selection since the list is set to commit its selection on exit (as is recommended when supporting multiple selection). You can specify this by setting the "Commit On" property on the Object palette’s Field tab to "Exit".

Barcoded Forms (PDF417) Primer

Lee Sutton has posted a what looks like a really good introduction to LiveCycle Barcoded Forms along with some tips and best practices for using 2D barcodes (PDF417 in particular) on your forms and in your workflows.

Bug: Images aren’t always embedded into PDFs

Description

Image objects (images and image fields) have a property which you can set to specify whether the image should be embedded or linked (the "Embed Image Data" check box on the Object palette’s Field tab).

When the property is checked, the result is that the image file loaded into the image object is embedded into the XFA Data that’s stored in the form. When the property is unchecked, only the URI (file path or URL) is stored in the XFA Data.

I put emphasis on XFA Data above because it’s important to understand the difference between the XFA layer and the PDF layer of a PDF form in order to understand what this bug is all about: Essentially, an XFA form saved as a PDF file results in a PDF container with the XFA inside (as opposed to saving the form as an XDP where the XFA form is at the top layer). When the PDF form is subsequently filled and saved within Acrobat (Standard or Pro), the image loaded into an image field object is supposed to be saved on one layer or the other depending on the setting of the "Embed Image Data" property on the image field.

When you save a PDF form in Acrobat, what gets saved in the XFA Data (in the XFA layer) depends on the value of the "Embed Image Data" property (which maps to the //field/ui/imageEdit@data attribute). If it’s set to "link" (unchecked), then only the original path to the image file is saved. If it’s set to "embed", then the image file is text-encoded and saved in the data instead of the original file path. In either case, however, the image should always be embedded into the PDF layer (don’t worry, it doesn’t actually get embedded twice, once on each layer, I’m just simplifying things a little here) such that the PDF is self-contained and can be re-distributed without having to ensure that the linked image file remains accessible from any location.

Unfortunately, there are cases when the image file doesn’t get embedded into the PDF layer when it should be. For example, if you have an image field object which is set to link to its image file and you load the image by importing data that contains the file path then save the PDF, the image won’t be embedded into the PDF as expected.

Workaround

At this time, I’m not aware of any workarounds to the specific issue I stated above (when importing the image’s file path).

The only way to consistently get image files to be embedded into the PDF as they should be — regardless of the image field object’s setting to link or embed its data — is to manually click on the image field object in Acrobat and pick the image file.

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.