Property Browser Details: Object-Related Options

The property Browser presents numerous options related to the selection of an object instance and a specific property value within that instance. This includes both the selection of a value from the object in the current context and also the selection of an object within a collection. Many of the more sophisticated options are related to the selection of an object instance within a collection. These options include:

Selection of a property within the object instance in the current context
Selection of an object instance within a collection based on it’s position (first or last)
Selection of an object instance within a collection based on a rule definition
Selection of an object instance within a collection based on the key property value of that object

The specific layout of the module’s data structure within the Property Browser depends on the context in which the target path being selected will be evaluated at run time. In some cases the object is displayed as the first root node. In other contexts a collection is presented. In addition to these options, others may be available for screen sets, complex tables, data tables, and other options. These are addressed elsewhere, with the focus here on the target paths selected solely based on the object instances.

Target Path for an Object Property - No Collection

When setting the target path of an attribute, and when the context of the path to be evaluated includes a single object instance, the Property Browser is presented similar to the following:

In this example the target object property of an edit transaction property is being set. The object in context is the object to be modified by the transaction. In the Property browser, the Customer object is displayed as the first root node and is expanded, as shown in the above example. If the proper option for selection is one of the properties under the Customer object, then it is likely that the Property Browser is not needed, as in almost all contexts the properties of the customer object would be displayed in the context menu of the attribute.

However, if the target paths should reference a collection property within the object, the Property Browser is needed. Collection properties are not displayed in the context menu of a transaction property’s target object attribute. The collection is a valid selection if the edit transaction should replace the object collection in the object with values captured by the transaction.

It is also possible to reference the parent object of the one in the current context. Again in the previous example, the Customer object is expanded. Note the last child node under the Customer, which is MainObject. The description indicates this is the parent object of Customer, meaning the object instance is stored in a collection property of the MainObject. To select another property within the MainObject, that node can be expanded and the property selected from it. This same general procedure is available to all objects stored in collections to access the parent object containing that collection.

Target Path for an Object Instance - Selected From a Collection

In many contexts the object to be selected exists in a collection of objects of the same type. The specific object instance to be targeted must be specified. In almost all cases once the specific object instance is determined, a property of that instance is then the actual target being selected. When working with an object collection property, the Property Browser provides several options to select the specific object instance:

When the node for a collection property is expanded in the Property Browser, the following items are available:

The first object in the collection
Select the object from collection by rule
Select the object from the collection by the key field
The last object in the collection
Object child collections

The First Object in the Collection: The first object in a collection is the first object instance added to that collection. This may be the first one retrieved from the back end system during synchronization; or if the collection is empty after synchronization, it is the first object instance added to the collection on the client.

In the case of data synchronization, the order in which the objects are stored in the collection is not guaranteed by the Agentry Client. The synchronization logic itself can include ordering of the data retrieved, which then provides an order to the objects stored in the collection. However, there are few use cases in real world applications where a target path is needed to select the first object instance in a collection.

The one real-world example of such a target path is when the collection is known to contain only a single object in all situations. One situation where this occurs is when an object exists in a collection of the MainObject to store user-related information. Typically the synchronization retrieves only a single object instance for this user information. When it is needed, a target path to that object must be created. Target paths for object collections always assume the possibility that multiple object instances can or will exist within a given collection. Therefore, selecting the first object in the collection in a situation where it is known that only one instance will ever exist is an acceptable manner in which to select this object.

Select the Object from the Collection By Rule: Selection this option requires the definition of a rule to evaluate the objects found in the collection. The default behavior at run time is for the rule to be evaluated once for each object instance in the collection until the rule returns true, at which point that object instance is returned, or until all objects have been evaluated. The rule is evaluated in the context of each object instance in turn, allowing access to the property values of each object.

As optional behaviors the object selected can be the first one for which the rule returns false; the last one for which the rule returns true; or the last one for which the rule returns false.

To select or define a new rule for this purpose, as well as to select options to change the default behavior, right click on the node in the Property Browser to display a context menu. Here a context menu is displayed with the following selections available:

All rule definitions currently defined in the module.
The option to define a new rule
The option to specify if the object instance selected is the first or last to meet the rule’s criteria (the first object found is the default)
The option to specify whether to select the object instance based on a true or false return from the rule (true is the default)

If the option to select the last object meeting the criteria is defined, the rule will always be evaluated once for each object in the collection, as it must check all objects before determining the last one to meet the criteria. This behavior should be considered if the selected collection has the potential to contain a large number of object instances, as it has the potential to increase processing time as the number of objects to evaluate increases.

Once the rule has been either selected or defined, and the optional other settings have been selected, the node can then be expanded to allow for the selection of the specific property within that object instance. The value of this property is then returned, or the property itself is targeted during run time.

Select the Object from the Collection by the Key Field: The object instance can be selected from a collection via the value of it’s key property, or alternately by another property within that object. In most cases the key property should be used as it is the only value guaranteed to be unique for all object instances within the collection.

To set this option, right click on this node in the Property Browser to display a context menu containing the properties in the object definition, as well as the value to which it will be compared. The key property is selected by default, but can be changed to any other non-collection property within the object.

The last item in the context menu is equal to (Browse for Property)... is then selected to display a second Property Browser. In this screen the value to be compared to the key property of each object in the collection is selected. This select is an example of a target path within a target path. This “nested path” is evaluated once for each object in the collection being searched, with the value it returns being compared to the key property of each object instance in the collection, until a match is found or until all objects have been searched.

One alternate selection in this context menu is the Browse... menu item directly below the list of all properties within the object. This can be selected for more complex search criteria, and will display a second Property Browser. Specifically, selecting an object from a collection that contains a nested collection with an object instance that meets some criteria. For example, selecting a Order object from the Orders collection where that Order object contains an OrderItem object with a Product ID value of 70.

To make such a selection, the property to be compared would be the ProductID property of the OrderItem object within the collection property of the Order object. The is equal to (Browse for Property)... menu item is then displayed to select the value to compare against the ProductID property of the child OrderItem objects. Note that such a selection will iterate over each object in the nested collection property of each object instance in the parent collection. So in this example, each OrderItem object is checked in each Order object until a match is found. Therefore, the potential number of iterations performed by the Agentry Client for such a target path is a multiple of the number of objects in the parent collection and the number of objects in the nested collection. This type of searching is rare, but there are a handful of use cases for which it can be applicable.

The Last Object in the Collection: The last object in a collection is the last object instance added to that collection. This may be the last one retrieved from the back end system during synchronization; or it will be the last object instance added to the collection on the client.

A typical use case for building a target path that selects the last object in a collection is in the area of multiple transactions being instantiated and applied on the Agentry Client, where a transaction creates a new object, and a subsequent transaction must modify that new object in some manner. An example from the Mobile Northwind application is the order entry functionality. The Order object represents an order placed by a customer and includes header information such as the order date and the shipping address. It contains a collection of OrderItem objects that represent the products for that order.

From a usability standpoint, it makes sense for the creation of an Order object and the addition of one or more OrderItems to that object to appear as a single operation to the user. To accomplish this an action can be defined that executes two sub-actions. The first instantiates and applies the AddOrder transaction. The second instantiates and applies the AddOrderItem transaction in a loop. Any add transaction must know to which collection property the object it creates will be added. In the order entry scenario, the AddOrder transaction creates an object and adds it to the Orders collection property of the current Customer object. The subsequent AddOrderItem transaction must then target the collection of OrderItems contained in the newly created Order object. To specify this Order object it is safe to select the last Order object in the collection as the parent to the new OrderItem object created by the AddOrderItem transaction.

Object Child Collections: The selection of the Object Child Collections node under a given collection property displays a list of all collection properties nested under the current collection. Selecting one of these nested collections results in the return of all object instances in that collection in all instances of the parent collection.

An example to explain this is the Orders collection property contained in the Customer object of the Mobile Northwind application. If it is desired to define a list (list screen, list tile view field, list selection field, etc.) that displays all of the orders for all customers downloaded to the Agentry Client, the object child collections type of target path can be used. At run time this target path is evaluated by the Client and retrieves all Order objects from every Customer object. It can then display all of these Order objects in a single list regardless of the parent Customer object in which any of them are contained.