There’s a bug currently logged against Acrobat 7.x where removing an instance of a dynamic subform, using the Instance Manager (IM)’s removeInstance(int) method, doesn’t cause an update to the IM’s count of currently instantiated subforms.

OK, so maybe that was a little too technical so I’ll try to simplify: In Acrobat 7.x, when you remove an instance of a dynamic subform using the IM’s removeInstance(int) method and then check the number of remaining instances using the count property, the number you’ll get won’t reflect the number that remains.

Adobe is aware of this bug and will hopefully be providing a fix for it in an up-coming release.

Fortunately, there’s a simple work-around (and even if the bug gets fixed in a future release, you should probably be checking the version of Acrobat that’s running your form to determine whether you need to be using the work-around or not):

_DynamicSubformInstanceManager.removeInstance(3);

// Force a remerge of the form's current data set with its template
//  to cause an update to the "count" property of all IMs
xfa.form.remerge();

Calling the Form object’s remerge() method will “force the remerging of the data model and template model to re-create the form model”, as explained in the Adobe XML Form Object Model Reference. This means that the form’s current data set will be remerged with the template (the form objects like dynamic subforms, fields, etc.). The result will be a form that looks exactly the same as it did in its state just prior to calling xfa.form.remerge() but with all IMs properly updated to the current number of dynamic subforms which they’re managing, thus correctly updating each IM’s count property.

Even if this problem is addressed in a future release, you’ll want to check the version of Acrobat that’s running your form in order to know whether it has the fix or not (in JavaScript as follows):

// get the host's version as a string and split it into an array
var oVerArray = xfa.host.version.split(".");

if (oVerArray[0] == "7")
  xfa.form.remerge();

Or more simply:

if (xfa.host.version.split(".")[0] == "7")
  xfa.form.remerge();

---

Posted by Stefan Cameron on May 25th, 2006
Filed under Instance Manager, Scripting

---

Here’s a little something that very important to know when working with dynamic subforms and using their Instance Managers (IMs) to add instances of them to a form: New subform instances aren’t automatically incorporated into the form’s calculations!

You would immediately notice this problem if you had a form which calculated a total based on line items which can be added or removed from the form. When you add a new line item using the IM’s addInstance(bool) method, the grand total of, say, the cost of all line items isn’t updated to reflect the data you enter into the new line item. This is because the new line item hasn’t been made part of the form’s set of calculation dependencies and is therefore not accounted for by your “grand total” calculation. As a matter of fact, until a call to xfa.form.recalculate() is made, none of the new instances added will be included in the form’s calculations.

To demonstrate this, I’ve created a sample form which has a “line item” section to which line items can be added. As line items are added and their costs changed, the grand total fields at the bottom calculate the total cost of the order: One grand total field performs its calculation using the FormCalc SUM function and a SOM Expression identifying the collection of fields to total while the other uses the LineItem dynamic subform’s IM object to calculate the grand total. Finally, there’s a check box at the top of the repeating “line item” section which, when checked, will cause the “Add Item” button to execute the xfa.form.recalculate(true) statement after adding a new line item. To see the difference, play around with the form by adding line items with the check box both checked and unchecked.

Download Sample [zip]

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

---

Posted by Stefan Cameron on May 20th, 2006
Filed under Instance Manager, Scripting, Tutorials

---

Something that’s often desired, when working with dynamic forms, is to let the user specify, at run time (in Acrobat), how many lines of information are required to specify what they want.

The classic example is a Purchase Order form on which there are objects (usually buttons) which let you add and remove item lines from the section of the form which calculates the total cost of the order based on how many items are being ordered and the quantity and cost of each item.

In order to achieve this, the use of the Instance Manager is required. The Instance Manager is an object which exists only on repeatable subforms (this could be a subform which is parented to a flowed subform and set to repeat for each data item or it could be a row in a table — since rows and tables are, essentially, subforms). With this special object, you can modify the set of instances of a repeatable (dynamic) subform.

You can access the Instance Manager in two ways. The first is by accessing the object from the dynamic (repeatable) subform:

// append a new instance of DynSubform within its parent container
DynSubform.instanceManager.addInstance(true);

// ensure that the new instance is included in
//  subsequent calculations
xfa.form.recalculate(true);

The second is by using the shortcut “underscore” syntax (note that this syntax is supported if the form is rendered to PDF):

// remove the third instance (zero-based) of DynSubform
_DynSubform.removeInstance(2);

// work-around for Acrobat 7.x bug (reported) where number of
//  instances isn't properly updated after calling removeInstance
xfa.form.remerge();

The drawback to using the first syntax is that there must always be at least one instance of the dynamic subform which exists. If you have a form which must initially not have any instances of a particular dynamic subform, then you need to use the second syntax with the underscore since that special object is always “available” to you regardless of the current number of instances of the dynamic subform in question.

It’s also important to pay special attention to the minimum, maximum and initial number of instances of a dynamic subform. This is set on the Object palette’s Binding tab once you’ve specified that the subform is to Repeat for Each Data Item. The min and max limits must be repected at all times when using the Instance Manager. For example, if you set a min count of 1 and attempt to remove the last instance of a dynamic subform, an exception will be thrown which will result in a script error. You can check the current number of instances by using the Instance Manager’s count property and compare it to, for example,

// get the minimum number of instances that can be instantiated
_DynSubform.min

There are other things you can do with the Instance Manager such as setting the number of instances (using its setInstance(int) method), move instances around (using its moveInstance(int, int) method) etc. These are covered in detail in the Adobe XML Form Object Model Reference (located in the XML section). Check-out the Manipulating instances of a subform section on page 675.

---

Posted by Stefan Cameron on May 18th, 2006
Filed under Instance Manager, Scripting

---