Demystifying IM.AddInstance

The definition for the Instance Manager’s addInstance method is as follows:

bc. addInstance( [BOOLEAN param] )

Personally, I find the word _param_ a little vague. I think it should be called _merge_ instead because that would give a clearer indication as to what it stands for: Essentially, if the data you’ve merged into your form has a repeating section that you’ve bound to a repeating (dynamic) subform and not all instances of this repeating data section have been merged into the form’s layout, you can control whether the new instance of the dynamic subform pertaining to that repeating data section will get merged with the next section or not by specifying _true_ (merge — the default) or _false_ (don’t merge — show empty instance) as the parameter value.

Usually, this doesn’t make a difference because you typically merge all instances of a repeating data section into your form and once there are no more data instances to merge, addInstance(true) will yield the same results as addInstance(false): an new empty (no data merged-in) instance.

Consider, however, the case where your form is a report and you’d like to show only a glimpse of the data instead of loading all 2000 instances of a repeating section. If your data was sorted from the most important to the least important, you could significantly *improve the performance* of your report (with respect to load time) by limiting the number of instances of that repeating data section that are initially merged into your form. Once your form is loaded, it could provide ways for the reader to get more instances if they wish to do so.

This can be achieved by using the Max property on the dynamic subform’s Binding tab in the Object palette along with addInstance([*true*]).

Here’s a sample which has a data connection to an XML Data File that lists movies. There are 16 movies in total but the form limits the number of movies initially displayed to 10 and provides a _Show More_ button. When this button is pressed, the movie dynamic subform’s Max count property, initially set to 10, is incremented by 1 and a new movie instance is added using _true_ as the parameter.

“Download Sample [zip]”:http://blogs.adobe.com/formbuilder/samples/im/AddInstanceTrueFalse.zip

*Minimum Requirements:* Designer 7.0, Acrobat 7.0.

*Note:* If you open the form in Acrobat, don’t forget to import the data into it using the “File | Form Data” menu.

7 Responses to Demystifying IM.AddInstance

  1. Sergio says:

    Hello,I hope you could help me on this subject:In my pdf form I´m creating instances programatically using the setInstances() function.Each instance of the form has a input field which I would also like to assing programatically.However, despite I´m able to create the instances, I hadn´t figured out a way to assing this values.Do you think this is possible?Thank you

  2. Sergio,Unfortunately, the setInstances method doesn’t return a list of references to the new set of instances that remain after the call so, unlike addInstance which gives you a reference to work with, you have to go looking for them.Let’s say you’re creating instances of a subform named “sub” and each sub object has a field in it named “f”.First, you set the number of instances like this:_sub.setInstances(5);This statement creates 5 instances of the sub object.Now, you need to find the instances (get references to the m) so you can access the f object inside of them (in JavaScript here, within the context of the sub object’s parent subform):for (var i = 0; i < _sub.count; i++){// get a reference to the sub[i] objectvar oSub = this.resolveNode(“sub[” + i + “]”);// set the value of its f objectoSub.f.rawValue = “hello”;}The loop simply obtains the number of instances using the count property of the sub object’s Instance Manager and, for each instance, gets a reference to it in order to set its f object’s value.

  3. Palani says:

    Hi,We are able to convert from Jetform IFD to PDF using Adobe Designer 7.0 through manually(Open “Save As PDF”).The only problem is that I need to do this automatically, without manually opening Adobe Designer 7.0.We are able to convert Jetform IFD to XDP using ConvertIFD.exe through Command line parameter (ConvertIFD.exe in=C:\Sample.ifd” out=”C:\Sample.XDP”). Is there a way I can programmatically generate PDF from XDP?

  4. Palani,I had to do a little investigating to see what the situation was with batch-converting XDPs to PDFs.Unfortunately, neither Designer nor Acrobat ships with a tool that would let you do this. While there are command line programs to convert IFD, Word and PDF documents into XDP, there isn’t one that’ll take an XDP and convert it into a PDF.

  5. Harish Kumar C says:

    Hi Palani & Stefan Cameron,I am also facing the same challenge to convert XDP into PDF.Have you got any solution for this. If so, could you please send it to my id (harish_c_99@yahoo.com).Thanks a lot.-Harish

  6. Deb Mannon says:

    I’ve grown with JetForm/Acellio/Output Designer/Adobe Designer since the mid-90’s but find myself in need of quickly converting a PDF or Word file to an IFD. I simply must find a quick and easy way without jeopardizing the integrety of the document. Is there a tool out there to accomplish this?Thanks for any help.~Deb

  7. Deb,That was a good question! I had to do some digging around to find the answer since those technologies pre-date my arrival at Adobe.Unfortunately, we don’t make a tool to convert IFDs into PDFs but you may be able to find one at texcel.com.