Posts in Category "Scripting"

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.

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".

Setting JavaScript as the Default for New Forms

If you’ve ever written scripts in Designer, you will have noticed that the default scripting language is FormCalc which is a problem if you need to (or prefer) to write your scripts in JavaScript.

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

New Scripting Basics Guide

I was looking around in the LiveCycle Developer Center today and came across a great beginner’s guide to scripting in Designer that Alex Mitchell, a colleague of mine here at Adobe, recently posted to the site.

Even though it’s labelled as "beginner", there’s some great stuff in there regardless of your level of expertise. For example, there are some really nice flow charts illustrating the order of execution of form and field events and the section on Creating and Resuing JavaScript Functions should come-in handy for those complex forms. There are also some examples of common scripting tasks which could be useful in all types of forms.

Databases: Inserting, Updating and Deleting Records

Since all of the previous tutorials I’ve posted with regards to data connections have dealt with searching for records and displaying the results, I thought I should post a little tutorial on how to use data connections for inserting, updating and deleting records as well.

You may recall that the tutorial on connecting a form to a database did demonstrate one method of inserting, updating and deleting records from a database. The problem with using bindings to fields in order to modify records in a data connection is that you must set those fields to the values for the current record and then you have to use the data connection object scripting methods like "addNew()", "update()" or "delete()". This can get really awkward if all you’re wanting to do is insert a new record, for instance, and just doesn’t cut it if you want to avoid having to load-in data when the form is opened (the only purpose for the data connection may be such that new records can be inserted or existing ones can be deleted yet displaying existing records is not required).

This small tutorial uses a basic ODBC data connection defined in the form and then modifies it, via script, in order to be able to execute SQL statements which either insert, update or delete records from any table in the database for which the data connection was setup to work with. It then uses a separate data connection to the same database for query purposes only since there’s no sense complicating things with an all-purpose data connection — especially when it comes to running "select" SQL statements in order to iterate through records returned by the query.

Key Concept

The key concept with this tutorial is the fact that the <query> node inside an ODBC data connection (as we saw in the tutorial on selecting specific database records) can be used to execute all sorts of SQL statements — not just "select" queries. This means that if you set the <select> node (inside the <query> node) to be an "insert" SQL statement and open the data connection, the result will be a new record in the database as per the insert statement’s parameters (and the same goes for "update" and "delete" SQL statements). In fact, the XFA 2.4 Specification states, on page 772, that "despite the name [of the <query> node], this element can also be used to delete, insert, and update records."

BOF and EOF Actions

One very important thing to note is that the "Beginning of File" and "End of File" actions on the <query> node’s <recordSet> child node (which describes how records in the data connection are navigated) must be set to "stayBOF" and "stayEOF", respectively, otherwise you may run into serious problems. That is, the result of reaching the beginning or end of the record set when opening the data connection must be to "stay" where you (the record set navigator) are when the SQL statement is one or more of "insert", "update" and "delete".

See the script in the "Database" script object in the sample form for more details on how to specify this. Use the Hierarchy palette to locate it under the root subform.

Sample Form

I’ve designed a form that should put this all into perspective for you as well as give you a very useful script object which you can place in your Custom Library tab and re-use in other forms.

In short, these are the steps I followed to design this form:

  1. I created the "RunSQLDataConnection" ODBC data connection to my "FormBuilder" database, specifying a short SQL query to the new "movie_comments" table (although any other table would’ve been just fine).
  2. I created the second "ListComments" ODBC data connection to my "FormBuilder" database, specifying an SQL query that exposes the "username", "title" (movie title obtained from a join on the movie table) and "comment" columns.
  3. I inserted the various buttons and fields and wrote the scripts.

I’ve included lots of comments through the scripts to detail what’s going on at each stage as well as why certain things are being done so please have look at the sample (note that you don’t have to have the data connections setup in order to open the form and look at the script) and let me know if you have any questions.

Download Sample [pdf]

Download FormBuilder Database Definition [sql]

Minimum Requirements: Designer 8.0, Acrobat Pro/Std 8.0

Better Form Design with XFA 2.5

You may have noticed that the new version of Designer and Acrobat that Adobe recently released uses a new version of XFA (2.5 to be exact). While the language has many new features in and of its own, the version of the language (2.5 vs 2.4 or older) also dictates how your forms will behave in Acrobat 8+ with respect to certification (digital signatures) and ubiquitization (Reader-enablement).

Background

Since this new behaviour, which is geared to encourage better form design going forward, will ultimately change the way you write certain scripts, I believe it’s important to start with some basic knowledge of XFA forms, see what happens when they get certified/ubiquitized, examine how each used to behave in Acrobat 7 and then how they’ll behave in Acrobat 8+.

XFA Primer

Simply said, an XFA form is described inside an XDP file. When it’s saved as a PDF file, the XDP is actually embedded into the PDF so that it can be processed by Acrobat.

If you look at the XDP (via Designer’s XML Source view), you’ll see that it’s simply a collection of packets that describe the form’s various components. For example, <template> describes the form’s layout and behaviour while <sourceSet> contains a collection of data connection descriptions you’ve defined using the Data View palette. When the form is loaded as a PDF into Acrobat, each packet is loaded into its own in-memory (temporary) model and that’s what you actually reference in your scripts. For example, you access the sourceSet packet via the sourceSet model with "xfa.sourceSet". Changes to these models are reflected directly into their pertaining packets.

Form Certification/Ubiquitization

Without going into more details than are necessary, once a form is either certified and/or ubiquitized, modifications to any of the protected content (the various models) should be prevented. Modifying the form’s protected content post-certification/ubiquitization would invalidate the certification/ubiquitization status. Such modifications mean that the document is no longer in the state in which it was when it was digitally signed and therefore can no longer be trusted by the recipient as being authentic. Even though the modification may have been caused by authored script in the form, no distinction is made between those kinds of modifications and malicious attacks by an unknown party to, for instance, cause form data to be submitted to an alternate server.

Acrobat 7 and XFA 2.4

Acrobat 7 supported XFA forms up to XFA 2.4 (which Designer 7.1 would author). Once an XFA 2.4 form would be either certified and/or ubiquitized, Acrobat 7 would detect modifications to the form’s protected content and would invalidate its certification/ubiquitization status if such modifications occurred. It didn’t, however, prevent the sourceSet model from being modified post-certification/ubiquitization even though the <sourceSet> packet was included as part of the certification/ubiquitization process.

The inherent danger in this was that while any form that would do common things like display all the records in a database or select specific records in a database (filter records) — which required the modification of data connection nodes contained within the sourceSet model — would function happily at first, problems would ensue later on when a form’s certification/ubiquitization status would be inadvertently invalidated, for example, because of an unauthorized modification to a certified/ubiquitized model (sourceSet).

Acrobat 8 and XFA 2.4

In order to address the problem of inadvertent modifications (by form scripts) to certified/ubiquitized XFA 2.4 forms, Acrobat 8 was designed to prevent the sourceSet model (and any other certified and/or ubiquitized content) from being modified post-certification/ubiquitization. This means that if an XFA 2.4 form, loaded in Acrobat 8+, becomes certified and/or ubiquitized, any attempt by a form script to modify the sourceSet model (as in the two examples I mentioned earlier) will result in a security exception:

GeneralError: Operation failed.
XFAObject.setAttribute:25:XFA:form1[0]:initialize
This operation violates your permissions configuration.

One could argue, of course, that this change effectively "breaks" XFA 2.4 forms in Acrobat 8+ but in the end, inadvertently invalidating a form’s certification/ubiquitization status is likely just as bad as a security failure in a form’s script (because it attempted to modify a now-protected model) from a user experience point-of-view. As I mentioned earlier, Acrobat makes no distinction between authored scripts and malicious attacks when certified/ubiquitized content is modified — and neither does the user (in their minds, the content simply can’t be trusted any longer)!

Acrobat 8 and XFA 2.5

With a new version of Acrobat and XFA, there was an opportunity to further improve on the user experience of both certified/ubiquitized and non-certified/ubiquitized forms going forward. It was done simply by ensuring that modifications to any model that becomes protected post-certification/ubiquitization are now prevented from the start (whether the form is certified and/or ubiquitized or not) and by using XFA 2.5 as Acrobat 8+’s “trigger” for imposing the new behaviour.

The result is that we’re now forced to think about security from the very beginning of the form design process by opting to work with copies of the in-memory models (which is achieved by cloning models) rather than with the base models such that our forms don’t fail regardless of their certified/ubiquitized state. With XFA 2.5’s support for "on-the-fly" certification/ubiquitization, a form may become secured and locked-down at any point in its "live cycle" which makes it imperative to use scripting techniques which won’t fail post-certification/ubiquitization.

Legacy Mode

New forms authored in Designer 8.0 will be XFA 2.5 forms by default and you’ll need to use the new cloning technique described later in this article. That being said, if you need things to be back the way they were, there is a way that you can still use Designer 8.0 to design XFA 2.4 forms and that’s by using what’s called the Legacy Mode processing instruction.

Put simply, switch to the XML Source view for an XFA 2.5 form in Designer 8.0 and insert the following processing instruction under the <template> node (as a child element):

<?originalXFAVersion http://www.xfa.org/schema/xfa-template/2.4/?>

The result will be that Acrobat 8.0 will run your form as though it was an XFA 2.4 form — but be aware that this will also prevent you from using any of the new language extensions and APIs that come with XFA 2.5 (more on those in later posts).

(By the way, when you load an older form — earlier than XFA 2.5 — into Designer 8.0, even though the form’s version is upgraded to XFA 2.5, the Legacy Mode processing instruction specifying the form’s original XFA version is automatically added so that your form continues to work properly with respect to the XFA version is was originally designed for.)

Modifying sourceSet in XFA 2.5+ Forms

In order to avoid unexpected security exceptions in your forms after they get certified and/or ubiquitized and to handle the fact that you may not necessarily know for sure at which point in the form’s workflow that it’ll happen (if ever), you need to make sure that when you’re working with the sourceSet model, you’re actually using a cloned in-memory copy of the original sourceSet model rather than using the original sourceSet model directly.

Cloning Form Nodes

Don’t worry: You don’t have to be a scientist to use this simple technique. Using the

clone(deep)

method on the node that defines the particular data connection you’re wanting to modify within the SourceSet model and making sure your script keeps using the clone instead of the actual definition will do the trick. This method accepts a boolean parameter which, when set to 1 (or true), will clone the node and all its children (which is definitely what you want to do or else you will only get a shell instead of the full data connection) and return a reference to the in-memory copy.

As an example, let’s consider the following script taken from the Data Drop Down List object (found in the Library palette’s Custom tab):

...
var oDB = xfa.sourceSet.nodes.item(nIndex);
...
// Search node with the class name "command"
var nDBIndex = 0;
while(oDB.nodes.item(nDBIndex).className != "command")
nDBIndex++;

oDB.nodes.item(nDBIndex).query.recordSet.setAttribute("stayBOF", "bofAction");
oDB.nodes.item(nDBIndex).query.recordSet.setAttribute("stayEOF", "eofAction");

Notice that the script first obtains a reference to a data connection node found within the original sourceSet model and then goes on to modify some of its properties. In an XFA 2.4 form loaded in Acrobat 8+, prior to certification/ubiquitization, this will function properly although it’ll stop functioning if the form ever gets certified/ubiquitized. In an XFA 2.5 form, however, it’ll immediately fail with a security exception simply because Acrobat 8+ determines that the sourceSet model may eventually become protected and protects it from the start.

Applying the cloning technique to this script is trivial. All you need to do is change the line which accesses the sourceSet model to this:

var oDB = xfa.sourceSet.nodes.item(nIndex).clone(1);

Notice the clone(1) method appended to the end of the statement. At that point, "oDB" now receives a reference to a copy of the original sourceSet model which it’s free to modify regardless of the form’s certification/ubiquitization status. The rest of the script doesn’t need to be modified at all!

Note that you could just as easily store the cloned data connection node into a Form Variable or a variable defined in a Script Object in order to reference it again at a later time if you make modifications to it that you would like to persist while the form is running in Acrobat.

Updated Library Objects

If you had already installed Designer 8.0 and tried using the Data List Box and Data Drop Down List objects under the Custom tab in the Library palette, you more than likely ran into the security exception I described earlier. That’s because those custom objects managed to miss the ever so important update which they required in order to function properly in XFA 2.5+ forms with Acrobat 8+ (as we saw in the previous section).

For your convenience, I’ve posted updated versions of both the Data Drop Down List and Data List Box custom Library objects which you can save to your local system and add to your personal (or shared) Library in Designer 8.0.


Updated: December 11, 2006

Instance Manager Object Reference

It seems lately a lot of my posts and a lot of the comments that you’ve posted had something to do with the Instance Manager: The object available only on repeatable (dynamic) subforms which allows you to manage that subform’s instances (add, remove, etc.).

Since it’s at the core of repeatable subforms which are necessary when designing flowable (dynamic) forms that, say, display one row per record in a table connected to a database, I thought it would be useful to give a quick overview of the Instance Manager Object’s properties and methods.

Accessing the Instance Manager

Before we get to the properties and methods, here’s a refresher on how to get at the Instance Manager for a particular subform (or table row).

Repeatable Subform Required

First, you must make the subform repeatable. To make it repeatable, it must be placed in a flowed container — that is, another subform whose Content type (found on the Object palette’s Subform tab) is set to flowed.

Side Note: The simplest case is a report-style form that simply displays records from a database where each record’s information is displayed in separate fields within a subform. So you have a subform with fields in it that are bound to data nodes in some data connection and the subform itself is bound to a repeating data section in that same data connection. For this scenario, you’ll find it much easier to place your fields on the first page and then shrink the page (which is a subform) such that it’s snug against the fields you placed on it and looks more like a row rather than a page. This is because the page subforms are, by definition, subforms parented to the root subform (named "form1" by default on new forms — check it out at the top of the Hierarchy palette) and the root subform is, by definition, flowed. By using the page subform as your repeatable subform for your data records, you’ll find it much easier to quickly get to a state where all records show-up on your form and new pages get added when previous ones are full (can’t fit any more rows).

Once the subform is placed in a flowed container (parent subform), you must then specify that it’s a repeatable subform by going to the Binding tab on the Object palette and checking the "Repeat subform for each data item" box.

After these two easy steps are complete, you’ll then automagically get an Instance Manager object on the repeatable subform you just defined.

Script Access

It’s nice to have a repeatable subform but unless you’re just using the default behaviour (which may very well be just fine in most cases), you’ll need to write scripts that use it’s Instance Manager’s properties and methods and you’ll need to know how to access the Instance Manager in your scripts.

It turns out there are two ways of doing this:

  1. instanceManager Property: As long as you have at least one existing instance of the repeatable subform, you can access its instanceManager object directly like you would any other property: RepeatableSubform.instanceManager. Note, however, that this property will only be accessible if at least one instance of the RepeatableSubform object exists (which could be a problem if you’ve specified that its minimum allowed number of instances is zero and its initial instance count is zero as well).
  2. Underscore Prefix: The other recommended way to access a repeatable subform’s Instance Manager is to use, for lack of a better term, "the underscore-prefixed repeatable subform name" object. That is, whenever a subform becomes repeatable, its Instance Manager is added to the Script Object Model as a child of the subform’s parent container (remember, that’s the flowed subform from earlier) and is given a name that is the repeatable subform’s name with a "_" prefix. Therefore, if your subform was named "RepeatableSubform", its Instance Manager would get a name of "_RepeatableSubform" and you would access it as a property of the flowed container subform like this: FlowedContainerSubform._RepeatableSubform. The nice thing about accessing it this way is that you always have access to it — even if no instances of the RepeatableSubform object currently exist.

Properties and Methods

Now that you know how to make a subform repeatable and get access to its Instance Manager object when writing scripts, here are the various properties and methods that you have access to:

Properties

  • count: Returns the number of instances that currently exist. This is very useful when writing loops that do something to each instance.
  • min: Returns the minimum allowed number of instances. When removing instances, you’ll get a scripting error if the resulting number of instances is less than the minimum and the minimum number of instances will still remain (even if you meant to remove them). This can be set using the Min property on the Binding tab of the Object palette or my accessing the subform’s "occur" element and setting its min property: RepeatableSubform.occur.min = "value".
  • max: Returns the maximum allowed number of instances. When adding instances, you’ll get a scripting error if the resulting number of instances is more than the maximum and no additional instances will be added. You can modify this in the Object palette’s Binding tab or with the following property: RepeatableSubform.occur.max = "value".
  • occur: This is a reference to the pertaining subform’s &lt;occur&gt; element which lets you modify its minimum (min), maximum (max) and initial (initial) number of instances.
  • name: This property sets the name of the Instance Manager object itself. I doubt this would ever really be useful but it’s a property nonetheless. Be forewarned, however, that it’ll affect all subsequent scripts. For example, if you were to write "FlowedContainer._RepeatableSubform.name = ‘myIM';" and then write "FlowedContainer._RepeatableSubform.addInstance(0);", you would get a an error stating that "_RepeatableSubform" doesn’t exist. That’s because you’ve changed its name to "myIM" and therefore should write "FlowedContainer.myIM.addInstance(0);".

Methods

  • addInstance(bool merge): Adds a new instance of the repeatable subform and returns a reference to the new instance (or null if no instance was added) . Setting merge to 1 will cause any additional data to be merged with the new instance. Also, don’t forget that new instances aren’t automatically added to the form’s calculation dependencies. Also, be careful not to add more than the maximum number of allowed instances (see the max property).
  • removeInstance(int index): Removes the instance with the specified zero-based index. Remember that if you’re running the form in Acrobat 7.x, you may need to call xfa.form.remerge() after removing an instance. Also, be careful not to remove more than the minimum number of allowed instance (see the min property).
  • moveInstance(int fromIndex, int toIndex): Moves the instance at the zero-based fromIndex such that it becomes the instance at the zero-based toIndex (and other instance in between are shifted up/down as necessary).
  • insertInstance(int position [, bool merge = 0]): [New in Acro 8.0] Inserts a new instance at the zero-based position specified and returns a reference to the new instance (or null if no instance was added). You may optionally specify 0 or 1 for the merge property which, if set to 1, will merge any additional data with the new instance. The same rules and gotchas apply for this method as they do for the addInstance method described above.
  • setInstances(int count): Adds or removes instances to/from the end of the set depending on the difference between the current instance count and the specified instance count. In other words, if there are currently 4 instances and you call "setInstances(6)", two new instances will be added to the end of the set. Conversely, if 3 instances exist and you call "setInstances(2)" the last instance in the set will be removed. Note that this method abides by the currently-specified min and max restrictions.

Recommended Scripting Language

On a last note, I simply wanted to recommend using JavaScript as opposed to FormCalc when scripting the Instance Manager — especially when adding or removing instances. While FormCalc technically fully supports the Instance Manager, I personally find it’s a little flakey. JavaScript support, however, is quite consistent and stable.


Updated: November 15, 2006

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.