About forms with collections

A form's definition can include zero, one, or multiple IDO collections. Most forms include at least one IDO collection.

The first IDO specified for a form returns the primary collection. Additional IDOs return secondary collections or subcollections. Both primary collections and secondary collections are considered "top-level" collections. Both top-level collections can also use subcollections.

About the current collection

At runtime, a collection becomes the "current collection" when the user clicks on a component that is bound to it, or when an event handler, code, or other internal logic makes it the current collection. When a collection becomes the current collection, then the toolbar and events refer to that collection.

About the primary collection

The primary collection is the first collection defined (if any). It is distinct from other types of collections in these ways:

A form can be defined with an Initial Command that executes when the form is launched. This initial command for a form applies only to the primary collection. For example, if the initial command for a form is Refresh, then, when the form opens, a query is run to return and display the contents of the primary collection.
Note: To accomplish the same results for a secondary collection, you must use some form of logic—for instance, event handlers, or form scripts.
Unbound components are validated upon navigation of the primary collection.
Components bound to collections are, as a matter of course, validated when the collection to which they are bound is navigated or saved. For unbound or variable-bound components, though, the primary collection provides that functionality.
Similarly, when the user puts focus on an unbound component, the primary collection becomes the current collection.
The linked parent/child form mechanism is restricted to primary collections in certain respects.
The scripting APIs have a shortcut to this collection: ThisForm.PrimaryCollection
For secondary collections and subcollections, the APIs are slightly more complex.

About secondary collections

Optionally, forms can include one or more secondary collections. As top-level collections, they function much like primary collections, with the exception of the differences noted in the previous section.

Secondary collections are useful when you need to create a form that works with multiple collections, and when some of those do not have parent-child relationships characteristic of subcollections. Since it is easier to implement forms with subcollections than forms with secondary collections, you should use secondary collections only in those cases where subcollections will not work.

About subcollections

Subcollections contain "child data"; that is, data that is related to "parent data" in a top-level collection, and linked by specifying one ore more parent property=child property clauses.

For each parent collection row that the user has "visited" since the last time the parent collection was refreshed, the application caches the the subcollection rows ("child data") automatically. This data is sent to the application server, then, whenever the parent collection is saved.

Note: By contrast, even though it is possible to implement a parent/child relationship between top-level collections (for example, primary > secondary) by filtering one by the values of another, users will need to proactively save changes to the "child" data when navigating the parent collection.

A word about parent/child collections

A Mongoose-based application supports two cases of parent/child collections:

Subcollections within a single form
Linked parent/child forms

In both cases, a LinkBy expression is used to construct a filter for querying the child collection, based on the current values of properties in the parent collection.

Also in both cases, when the parent collection is refreshed, navigated, or saved, the default behavior is to requery the child collection.

Collection-level commit and the IDO Request Interface

One of the more unique features of the Mongoose UI model, which provides significant end-user productivity but also significant internal complexity, is the collection-level-commit model. This means that rows in a collection can have a status of modified, deleted, or new, and the user can continue to navigate rows, updating, inserting, deleting, and sorting, before finally saving the collection.

The IDO Request Interface UpdateCollection verb accepts an arbitrary number of rows, marked for insert, update, or delete, potentially nested with child collection rows, and then, by default, processes all this together in a single transaction. This means that end-users can treat such data much like a spreadsheet, sorting and mass-updating values, without being forced to commit each row before moving to another (row-level commit).