Instantiating Subforms at Runtime

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:bc.. // append a new instance of DynSubform within its parent containerDynSubform.instanceManager.addInstance(true);// ensure that the new instance is included in// subsequent calculationsxfa.form.recalculate(true);p. The second is by using the shortcut “underscore” syntax (note that this syntax is supported if the form is rendered to PDF):bc.. // 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 removeInstancexfa.form.remerge();p. 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,bc.. // get the minimum number of instances that can be instantiated_DynSubform.minp. 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.