Target Path: Selecting All Nested Collections

Prerequisites

Prior to performing this procedure the following general items must be addressed:

The object data structure must be defined, including the parent object and the collection property within that object.
The functionality described here is only available on Agentry v. 6.0 and later.

The following items and definitions are a part of the example application project used in this procedure:

The module object structure is defined as Customers -> Orders -> OrderItems. Each of these is a collection property of objects and are nested as listed. Customers is a top-level collection and thus is stored in the module main object.
The main screen set named ShowCustomers is already defined. It includes a list screen displaying the top level collection Customers.

Task

In many applications the desired user interface layout includes displaying object top-level collections and also all instances of objects stored in nested collections regardless of the parent object instance. As an example, it is desirable to display a list of all work orders in a work management application on the main screen set of the module. Additionally, a common change is to also display all of the equipment objects, which are stored in a nested collection of the work order object, in a single list regardless of the parent work order object.

Prior to version 6.0 of the Agentry Mobile Platform, in order to support this user interface layout, the equipment objects would need to be retrieved separately from the work orders and stored in a top-level collection of equipment objects. A list screen or a detail screen containing one of the list type fields was then defined to display this collection. The challenge with this approach was that in order to also display a list of equipment objects to the user for a single work order, one of two approaches was needed.

One option was to have a top-level collection of equipment objects, and a second, nested collection within the work order object. The issue with this approach was, of course, that the same data was retrieved twice, that being the objects for both collections. Both would then be stored on the Agentry Client. This was a waste of resources on the device, in essence doubling the amount of storage required to store the equipment information. The logic needed to retrieve all equipment for the work orders assigned to a given user was also sometimes challenging to write in an efficient manner.

The other option was to store all equipment objects in only the top level collection. To then display the equipment objects for a given work order, it was necessary to define an include rule for the list in which these equipment records were displayed that would only return the equipment objects from the collection for the currently selected work order. This could cause performance issues if there was a large number of objects stored in the top-level collection of equipment. Also, if this behavior was desired for what would otherwise be nested collections, numerous rule definitions were needed, making the maintenance of the application project more cumbersome.

Fortunately this issue has been addressed in the 6.0 release of Agentry. A new target path option is now available in the Property Browser that allows for the selection of all objects in all instances of a given collection property definition. So, building on the previous example of work orders and equipment, the work order object is defined to contain a collection property for equipment. There is no top-level equipment collection, only the nested collection in the work order object. A list can now be defined to display all of the equipment objects found in all of the collection properties of all work order objects by selecting the proper target path to return this data.

In the following procedure this behavior is defined for the Mobile Northwind application. A list screen is added to the module main screen set ShowCustomers, which initially contains a list screen for the Customers collection. The second list screen to be added will display all order objects for all customers. The data, however, will only be stored in the nested collections, meaning a given instance of the Customer object will contain an Orders collection property of just that customer’s previous orders. The Agentry Client will merge all instances of the Orders collection from all Customer object instances and display them as a single list in the list screen.

Note that while a list screen is used in this example, the option to display all nested collection instances for a given parent object type is available in numerous cases and contexts. This includes other list controls, such as a list view or list tile view detail screen field, and also in non-user interface contexts for operations that affect a collection.

We begin by creating the list screen (or one of the list type fields for detail screens, where applicable) and setting the attributes as normal.
When setting the Collection attribute, click the ellipses button to the right and select Browse Properties... from the context menu. This displays the Property Browser. Here, select the path MainObject Object | Customers (collection of “Customer” Objects) | “Customer” Object child collections | All “Orders” (combined collection of all “Order” Objects in all “Customer” Objects):
Close the Property Browser and return to the wizard (or Properties View if editing an existing definition). Complete the definition as normal.

When this procedure is complete a list screen (or other list control) is created that will display all object instances from all of the selection collection property instances in the parent object type. In the above example this results in a list screen listing all orders placed by all customers: