Stefan Cameron on Forms
Building intelligent forms using Adobe LiveCycle Designer

'Instance Manager' Category Archive

New book: Acrobat and Designer Bible

PDF Forms Using Acrobat and LiveCycle Designer Bible

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.


Posted by Stefan Cameron on February 5th, 2009
Filed under Acrobat,Books,Data Binding,Designer,Instance Manager,Scripting,Tables,Tutorials,XFA

MAX 2008 Tutorial – Part 2 – Flex Code

Welcome to the second in a three-part post series on importing data into a form guide (and, by extension, a PDF form). In the first part, we designed the XFA form that will provide us with the print/archive view of the movies retrieved from the Movie Service. The second part will focus on the special Flex code we will need to include in the form which will ultimately be executed by Flash when it runs in the form guide which we’ll design in part 3.

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.

Continue reading…


Posted by Stefan Cameron on November 18th, 2008
Filed under Conferences,Designer,Form Guides,Instance Manager,Scripting,Tables,Tutorials,XFA

Book now available: Creating Dynamic Forms with Adobe LiveCycle Designer

That’s right: The day has finally come! Designer officially has its very first book on the market, thanks to J.P. Terry at SmartDoc Technologies.

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

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.


Posted by Stefan Cameron on August 30th, 2007
Filed under Books,Designer,Instance Manager,Scripting,Tables,Tutorials

It's almost here: A book on Designer!

I’ve lost count of how many times, over the past year, I’ve been asked if there was a good book on designing forms using LiveCycle Designer. Until now, the answer was always an unfortunate “no”.

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?


Posted by Stefan Cameron on May 18th, 2007
Filed under Books,Designer,Instance Manager,Scripting,Tables,Tutorials

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 <occur> 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


Posted by Stefan Cameron on November 11th, 2006
Filed under Instance Manager,Scripting