The time has come for me to focus my extra energy on other goals and projects at Adobe and at home.

I have thoroughly enjoyed helping the XFA community for these past 4.5 years. All of the content on this blog was a direct result of your questions and I learned a great deal about Adobe’s XFA technology and its LiveCycle Enterprise Suite along the way. Thank you!

I leave you now with a final “form to end all forms” (in my mind, anyway): A version of the classic Tank Wars game implemented entirely in XFA + JavaScript.

Why do this, you wonder? Well, it was a good challenge, you couldn’t embed Flash in an XFA form back then and I wanted to do something that would really put LiveCycle Designer’s Script Editor through its usability paces.

Comments are now closed on all posts and pages except for this one and the XFA Tank Wars page which will close on December 31, 2010. I will continue to host this blog for your reference and bookmarks however I cannot guarantee it will be available forever.

Good luck on all your present and future form development projects.

Stefan

Last February, I announced the release of a new Designer book titled, “PDF Forms Using Acrobat and LiveCycle Designer Bible”.

Over the past few months, I had the opportunity to review it and I thought I would share my comments, with respect to the second-half of the book, which deals with LiveCycle Designer ES and XFA forms, to help you decide if it would be a good book for you*. (The first-half deals with authoring PDF forms, a.k.a. AcroForms, in Acrobat and is beyond the scope of my blog.)

If you work in an enterprise setting, chances are you may have already had to deal with corporate data schemas that define how that data is structured. The goal, when connecting a form to a schema, is to ensure that the data consumed and output by the form adheres to a specific structure. Any fields bound to data nodes that aren’t inside the schema space are basically ignored at time of submission.

To help put things in context, I decided to define a schema for movie rentals to stay on the movie theme for the data I used in my other data connection tutorials.

Before we get started, I wanted to point-out that there are so many features related to schema handling and the Data View palette that I won’t be able to cover them all in a single tutorial. It would be information overload. Instead, I’ll try to point-out the basics along with a few interesting things that I think would be useful.

Creating the Connection

Right-click in the Data View palette and choose “New Data Connection”. In the first step, set the name for the connection (I set it to “SchemaConnection” so it’s easy to identify amongst any other connections that might be defined) and choose “XML Schema” as the type.

Note that while you may have multiple ODBC and web service data connections, a form may be connected to only one schema. As of XFA 3.0 (Designer ES2, Acrobat/Reader 9.1), however, you can inject foreign data nodes into the Data DOM even if they aren’t in the schema, which may help if you need to get extra data into/out of your form (a topic for another post; for now, have a look at the new “File > Form Properties > Data Binding tab” in the Designer ES2 Beta). You can also merge schemas into a single, larger schema (<import/> nodes are supported which can make importing multiple schemas into a single one relatively easy).

The next and final steps are to choose the schema file and root element. Depending on how your schema is defined, you may have a choice of elements to use as the root. In the Movie Rental schema, there is only one root: “movieRental”.

There are other options that let you embed the schema definition into your form (good if you don’t want to have to keep the schema file along with your form; otherwise, whenever you edit your form, you will need to ensure that the schema file is available) as well as specify XSLT files for incoming and outgoing data transformations (also a topic for another post).

Data View Palette

The initial view of the connection in the palette shows the data structure specified by the schema as represented in XFA. Each node in the schema gets an associated XFA object type depending on its description.

For example:

• Complex types (such as {customer} and {movie}) are usually mapped to subforms since they are elements that contain child elements.
• Simple types (such as {customer.firstName} and {customer.prov}) are typically mapped to XFA fields. As you can see, the Schema Data Connection Wizard detected various types and assigned specific XFA fields to each data node: The {customer.prov} node is set to a drop down list because that element is defined as an enumeration of specific values in the schema while {movie.cost} is set to a decimal field because it’s type is “xs:decimal”.

Root Subform Name

When the connection was created, there was a change to your form’s root subform name. Note how it has changed to movieRental:

The name of the root subform is always the name of the root data element in the Data DOM. This ensures that data submitted from the form has the correct root element to match the schema and data merged into the form will be bound first by the root subform, then by child form objects.

Inserting New Fields

The Data View palette can be used to insert fields into your form. This makes it really easy to create new fields with the proper settings and bindings. You can customize how fields are created by choosing “Palette menu button > Options”:

• Generate Validation Scripts: If enabled, field Validate events will be generated for elements that have certain restraints defined in the schema.
• Generate Descriptive Information: If enabled, particular forms of metadata in the schema will be inserted into the field definitions in your form (more on this in another post).
• Allow Tables to be Generated: If enabled, tables, rather than plain subforms, will be generated where appropriate.
• Show Binding Properties Dialog Box: If enabled and you drag & drop an element onto an existing field, a customization dialog will be displayed (more on this later).

To insert a new field configured according to an element in the schema, just drag & drop the element from the connection tree (in the Data View palette) into your form. You can add an entire group in a single operation by dragging a container element (e.g. {customer}). When a field in your form is bound to an element in the schema, a binding icon is displayed next to the element in the connection tree.

Start by dragging and dropping the {customer} element into your form. The result should be a new subform named “customer” containing 8 fields named according to the schema’s {customer} element and the elements it contains.

New fields on the form.

New structure in the hierarchy.

Notice how each leaf element in the connection now has a binding icon next to it in the connection tree (indicating that fields on the form are bound to those schema elements). The inserted fields were also customized according to their schema element counterparts. For example:

• All fields have appropriate data bindings (see “Object palette > Bindings tab > Data Binding property”).
• The {customer.prov} element became a drop down list which has a list of items, as well as a default value of “ON”, as specified in the schema.
• All new form objects have names that match their schema element names (though these could be altered, if better suited to any scripting requirements you may have, without affecting the data bindings).
• All new form objects have captions that are derived from their schema element names (e.g. the field bound to {customer.firstName} has a caption of “First Name”).

Next, drag and drop the {movie} element from the connection into your form.
This element is special because the schema specifies it may have multiple occurrences:

<xs:element
    name="movie"
    type="movieDef"
    minOccurs="1"
    maxOccurs="unbounded"/>

The result is a repeatable subform, as you can see by the Binding properties that were automatically set on the new “movie” subform (bound to movie[*] with Min Count set to 1 and no specified Max Count (unbounded)):

(Note that if the properties on the “Object palette > Binding tab” are partially disabled, it’s most likely because the movie subform is not inside a flowed container. Though it isn’t an XFA requirement, Designer requires it in order to enable the repeatable properties. We’ll fix this shortly.)

Binding to Existing Fields

There are two ways to bind an existing field to an element in the schema connection:

1. Simply choose the element to which the field should bind by using the “Object palette > Binding tab > Data Binding property” pop-out menu (button to the right-hand side of the property) and selecting it from within the schema connection’s sub menu.
2. Drag an element from the connection tree, in the Data View palette, and drop it on top of a field in your form. Doing so will — if it’s enabled — cause the Binding Properties Dialog Box to be displayed, giving you some options to further customize the existing field with information from the schema.

Binding Properties Dialog Box

Add a new text field to your form. This will be for the {returnBy} schema element. Ensure that the “Show Binding Properties Dialog Box” option is checked in the “Data View palette > Palette menu button > Options” dialog. Now drag the {returnBy} element from the connection and drop it on top of the new text field.

The above dialog will be displayed, giving you the option to update the following properties of the field on which the schema element was dropped:

• Name: Updates the name of the field to match the name of the schema element (from “TextField1″ to “returnBy”).
• Caption: Updates the caption of the field to one derived from the schema (from “Text Field” to “Return By”).
• Type: Updates the field’s object type to match the kind of data represented by the schema element (from text field to date/time field).
• Type > Default Value: Updates the field’s default value to that specified in the schema, if any (in the case of {returnBy}, the schema does not specify a default value).
• Type > Data Pattern: Updates the field’s patterns (display, edit, validate, data) according to the schema (in the case of {returnBy}, no pattern restrictions are specified in the schema, though a “date{YYYY-MM-DD}” data pattern will be set by default).

Choose the “Update all related properties” option and click on the “OK” button. The text field you previously inserted will be updated to a date/time field with various properties matching the {returnBy} schema element’s specifications (as detailed above).

Finishing Touches

At this point, your form should look something like this (the positioning of the objects may differ depending on where you dropped them):

Here are a few steps you can take to make things look a little nicer (in my opinion) as well as enable instances of the movie subform to be added for new movies to rent:

1. Place the movie subform in a flowed subform so that multiple instances can be added, flowed one after the other.
2. Place an “add” button next to the movie subform to add instances as well as a “remove” button inside the movie subform to remove specific instances.
3. Add an unbound decimal field that shows the running total cost for the movie rental order.
4. Add script to the returnBy field to automatically set the date 30 days in the future.
5. Add a submit button to submit the order.

Following the steps above should yield a more functional movie rental form. The only thing missing is the ability to pull-in movies to choose from. For one thing, this would avoid having to specify the movie ID, title and cost when choosing a movie to rent. To accomplish this, you could connect the form to a movie database (note that the database in the linked tutorial doesn’t have a “cost” column associated to a movie so you’ll have to add one) or, the more secure and recommended way, to a movie web service.

Download Sample Form [pdf]

Download Schema [xsd]

Download Sample Data [xml]

Minimum Requirements: I designed this form using Designer ES2 Beta and Acrobat 9.1 however the principals should work all the way back to Designer 7.1 and Acrobat 7.0.5. There may be a few features lacking from the Data View palette if you go back that far but the concept of connecting the form to a schema remains the same.

Aug 28, 2009 — Added link to Schema Metadata tutorial.

Nov 4, 2009 — Fixed a couple of syntax errors in the sample PDF form that were preventing the addition and removal of movie subform instances.

Creating Data Nodes

In a similar article, John Brinkman showed how to create form variable nodes at runtime however what’s not obvious about data nodes is that you don’t create them using

a class name of your choice.

For example, say you wanted to create the following data node structure:

<custom>
    <message>Hello World!</message>
</custom>

Given the following syntax for the createNode() function (see page 367 in the LC Designer 8.2 Scripting Reference):

{model}.createNode(className [, name, namespace]);

you might try the following, using “custom” as the class name for the first group/container node <custom>:

var n = createNode("custom");

Doing the above would generate an error stating that “custom” is an invalid node type.

The trick here is that only specific XFA class names are allowed, such as “text”, “decimal”, “integer”, etc., as well as two special types for data nodes: “dataGroup” and “dataValue”. When you need a data node that will contain other data nodes, you use the “dataGroup” class. When you need a data node to which you will assign a value, you use the “dataValue” node.

The JavaScript code to create the above XML structure then becomes:

// <custom> data group to contain <message>
var c = xfa.datasets.createNode("dataGroup", "custom");
// <message> data value for "Hello World!"
var m = xfa.datasets.createNode("dataValue", "message");
// set value of data value node
m.value = "Hello World!";
// add <message> into <custom> data group node
c.nodes.append(m);
// print result to JavaScript Console (Ctrl + J in Acrobat)
console.println(c.saveXML("pretty"));

// output from above:

<custom>
    <message>Hello World!</message>
</custom>

Note that the createNode() function must be called on an object of type “model” and since we’re creating nodes in the Data DOM, we use the xfa.datasets object since it is a model object.

At this point, the <custom> node (and the nodes/values it contains) is not part of the Data DOM. To add it to the Data DOM so that it gets submitted with the rest of the form’s data, you would have to append it to a node inside the root subform (the top-most subform in the Hierarchy palette). For example, if your root subform’s name was “form1″, you would do the following to add the <custom> node to the form’s data:

xfa.datasets.data.form1.nodes.append(c);

This can be very useful. In fact, this technique is used in Correspondence Management letter template scripts to flag a selection list’s default selection as having been processed. Since the data merged into the list to print the letter based on the template may not match the default selection in the list, the scripts generate a special node directly in the Data DOM to indicate whether the list’s data value should be processed instead of its default selection (i.e. no need for a hidden checkbox field for each list, keeping the form/PDF file size down).

The “Custom Node Example” section in my sample form demonstrates the above technique.

Loading Data Nodes

Another use for creating data nodes is they give you the ability to load existing XML in order to parse it without having to modify the Data DOM. If you create a new, orphaned (un-parented) data group node, you can use its loadXML() function to load an XML string into it, thereby giving you a handy XML node structure for parsing.

One example use of this would be in a form that retrieves various settings from a web service data connection where the structure of the returned data is determined by the input parameters (i.e. you have a single data connection which you can use to retrieve various data). You can return the XML data as a string and load it into a new data group node in order to parse-out the value you’re looking for without ever touching the Data DOM.

Another example would be an extension of my URL Request article. In this case, you could pass some XML data into your form via the URL request if your PDF form was available on a website. Warning: This is a not a secure method to pass data to your form.

Clicking the following link will load some movie data into the “Movies loadXML() Example” section of my sample form:

CreateLoadDataNodes.pdf?data=%3Cmovies%3E%3Cmovie%3E%3Ctitle%3ENacho%20Libre%3C%2Ftitle%3E%3Ccost%3E21.00%3C%2Fcost%3E%3CactorName%3EJack%20Black%3C%2FactorName%3E%3CcatName%3EComedy%3C%2FcatName%3E%3C%2Fmovie%3E%3Cmovie%3E%3Ctitle%3EMI%3AI%3C%2Ftitle%3E%3Ccost%3E20.00%3C%2Fcost%3E%3CactorName%3ETom%20Cruise%3C%2FactorName%3E%3CcatName%3EAction%3C%2FcatName%3E%3C%2Fmovie%3E%3C%2Fmovies%3E

Finally, my sample form also has a handy “URI Encoding Tool” section which you can use to encode various strings to include in a website address (as above).

Samples

Download Sample [pdf]

Minimum Sample Requirements: I created this sample using Designer 8.2 and Acrobat 9 however it should work fine back to Acrobat 7.0.5.

There is also a great example on creating data nodes on page 438 of the LiveCycle Designer ES Scripting Reference for Designer 8.2 — an excellent XFA form scripting reference.

Angie Okamoto, Director of Enterprise Development at Easel Solutions, and Ted Padova, the "PDF Guru" and author of the "Adobe Acrobat PDF Bible" series, have published a new book titled, "PDF Forms Using Acrobat and LiveCycle Designer Bible". I’m sure it’ll be a great reference!

Their book is available now on Amazon.com and Wiley.com.

Flex Code in XFA Forms

The key to today’s tutorial is understanding when and where the script you write in an XFA form (JavaScript or FormCalc) is compiled or interpreted.

For starters, form guides don’t support the FormCalc language so that just isn’t an option.

JavaScript, on the other hand, has the nice property of looking a lot like ActionScript. In fact, the two languages have enough similarities that with very little modification, any JavaScript you write in an XFA form can be converted into ActionScript which runs in a Flex form guide (in the Flash Player).

Normally, when you write JavaScript code in your forms and you run the form in Acrobat, the script isn’t compiled when the XFA form is converted into the PDF file format and it’s only interpreted when the interpreter attempts to execute it (i.e. if there’s a syntax error somewhere in your script and you never run that code, you’ll never know about the error). When you generate a form guide based on your form, however, your JavaScript is actually compiled by the Flex compiler that generates the SWC (Flash Library) which defines your form guide.

Warning: Script object code seems to be loaded and interpreted by Acrobat in one shot, instead of on a per-access basis as in form object event scripts, and any syntax errors anywhere in the script object will cause all of the script in the script object to basically be ignored. If you have functions defined in a script object and you know you’re calling a function properly but you keep getting a “function is not defined” error, use the Script Editor’s Syntax Checker tool — you’ll probably find a syntax error somewhere. After you fix it, you should be able to access your script object functions.

It also appears that Acrobat/Reader 9.0 may now be attempting to parse (but not execute) all scripts on form load which may produce syntax errors in the JavaScript Console due to the differences between JavaScript and ActionScript syntax however in my experience so far, I haven’t hit a situation where my JavaScript stops executing because of this. Nonetheless, if you’re seeing strange behaviour, it might be a good idea to check the console to make sure things are running smoothly.

What you might not have realized is that if you know that a particular portion of script will only be executed within the context of a form guide, you can actually write Flex code in your XFA form! When you generate the form guide (either by previewing using GuideBuilder or by rendering the form as a form guide via LiveCycle Forms), your Flex code will be compiled as any other Flex code would be and it’ll be executed in the same way.

That opens-up a world of possibilities and the one we’re going to explore in this tutorial is the use of the mx.rpc.http.HTTPService class to fetch data from the Movie Service and insert the results into the Listing table within the form guide, thereby causing the data to be inserted into the Listing table within the PDF form when the user switches from the form guide to the PDF.

XFA Host Name = Flash

You might recall, in yesterday’s tutorial, that I talked about the xfa.host.name property returning “Flash” when your XFA code is executing within the context of a form guide (it returns “Acrobat” when its executed within the PDF because the form’s “host” is “Acrobat”).

This is the indicator we’ll use to “protect” the Flex code we’re going to write to make sure that it’s not executed within the PDF:

if (xfa.host.name == "Flash")
{
    // do some cool stuff in Flex/ActionScript
}

Note that the XFA model in a form guide works just the same as it does within the PDF with the exception that the form guide environment only supports a subset of XFA functionality (less than in the PDF but more than in HTML).

Our Own HTTPService

Since there will 3 requests made to the Movie Service, one for the actor list, one for the category list and another for the movie listings resulting from the chosen actor and/or category (if any), the first step to take is to create some reusable code within our form that makes use of the HTTPService object.

Open the form you designed yesterday and add a new script object by right-clicking on the root subform (“movieList”) and choosing the “Insert Script Object” command.

Name your script object “FlexHttpService” and paste the code from this text file into the script object.

You’ll notice that there are some statements in this script that aren’t regular JavaScript (namely the “import” statements to get access to the HTTPService and its result and fault event classes as well as the typing of variables like “service:HTTPService”). That’s because it’s ActionScript!

I’m assuming you know enough about Flex to be able to understand what’s going on but the gist of it is that the script object’s send() function takes a URL (to the Movie Service) and two functions, the first called when the request is successful and the second called if the request fails. If the request is successful, the result handler function is called with an XML variable as its parameter. This XML variable contains the movie listing we want to insert into the Listing table.

The FlexHttpService.send() function will be the reusable piece of code that we’ll use in the two listboxes and the button, each providing its own URL and result handlers.

It’s important to note that the actual result and fault handlers given to the HTTPService object instance are inline functions. This is essential since the call to HTTPService.send() is asynchronous. When the result comes back (later), context will be lost and the service won’t be able to find a function you defined in the FlexHttpService script object. Therefore, the handlers must be inline.

ActorList Initialize Script

With the FlexHttpService defined, it’s easier to write the rest of the code to fetch the list of actors.

We want the list of actors to be retrieved when the form guide initializes so we’ll put this script in the Initialize event of the ActorList field. In the result handler, we’ll simply iterate through the items in the XML object returned and, for each actor, add his/her name and ID as an item into the ActorList field in the form guide.

Note that accessing the ActorList field in the form guide within the result handler, which is out-of-context at this point, is done by using the full SOM expression to the field, starting with xfa.form (accessing the Form DOM), followed by the root subform name (“movieList”), followed by the path to the ActorList field.

Edit the ActorList field’s Initialize event and paste the code from this text file into it.

Basically, we first clear any existing list items and call the Movie Service with the appropriate URL. In the result handler, we add items into the ActorList and then enable the list so that the user can make a selection (we don’t want the list accessible until the items have been loaded).

CategoryList Initialize Script

The CategoryList field is much the same as the ActorList field however it’ll fetch the list of categories.

Edit the CategoryList field’s Initialize event and paste the code from this text file into it.

GetMovies Click Script

Finally, we just need to set the Click event script on the GetMovies button that will fetch the movies requested by the user (optionally filtering on actor and/or category).

This script is essentially the same as the first two however it’s a little more complex since the Listing table must be retrieved and then new instances of the MovieRow must be added and their fields (Title, Actor, Category and Cost) populated with data from each movie returned from the service. Additionally, the button is disabled once its clicked and only re-enabled when the result or fault handler is called to prevent the user from clicking multiple times while a request is pending (since HTTPService.send() is asynchronous) and the MatchCount field is populated with the number of rows added to the Listing table (this will be important when we design the form guide in part 3).

Edit the GetMovies button’s Click event and paste the code from this text file into it.

Solution to Part 2

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

Download Part 2 [zip]

Minimum Requirements: The form should work back to Designer 8.0 however it was designed with Designer 8.2.1 SP1.

Updated: November 22, 2008

The book is the result of J.P.’s own expertise and a collaborative effort with the Designer Team in Ottawa. It tackles form design and techniques in building dynamic XML-based PDF forms with Designer.

As Alan Siegel (Founder & Chairman of Siegel+Gale, branding pioneer and champion of simplifying corporate communications) put it,

“J.P. Terry is a rare individual who understands both the design and technical issues involved with effective communications. This book will teach you about LiveCycle Designer but more importantly it will teach you about effective form design.”

How to get the book

The book is now available for immediate ordering at the following sites

• PeachPit Press
• Barnes & Noble

as well as at various local bookstores.

For some reason, it’s still on “pre-order” status at Amazon.com but should be “officially” available shortly.

The Designer book will also be available for purchase at MAX 2007 and I will be giving away a copy or two at my hands-on sessions on Designing PDF Forms and Flex-based Form Guides so be sure to attend if you’re at MAX 2007 North America!

Sample Files Posted

For those of you who already have the book, you can now download the sample files from SmartDocTech.com.

Well, I’m very happy to announce that J.P. Terry from SmartDoc Technologies has been hard at work over the past few months on a book titled, Creating Dynamic Forms with Adobe LiveCycle Designer.

Based on some of the chapters I’ve reviewed so far, this is going to be an excellent resource for those of you who might not know where to start or perhaps would like a few pointers on good form design. I, for one, am really excited about this since it’s the first (of hopefully many more to come) book about the product and technologies I work on every day. It’s almost like a milestone — Designer’s first book.

No word yet on a specific release date but I’ll keep you all posted as I get more details over the coming months.

So how about you? Are you looking forward to a book on Designer and dynamic forms?

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. [A/R 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). [A/R 8.1+] If there’s anything else you need to do (any other script statements) along with removing an instance, make sure that the instance is removed once all other statements have been executed. The new Direct Rendering engine in A/R 8.1 removes the instance, and all objects that it contains, immediately (as opposed to removing it on the next rendering pass as in previous versions) which means that any subsequent statements are not executed.
• 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 A/R 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: June 26, 2009