Target Paths and the Property Browser

Target paths are an important concept to understand when creating or working with an application project using the Agentry Editor. Target paths are selected using either a short list of likely options from a context menu for a given attribute field, or by using the Property Browser for more sophisticated paths.

To understand target paths it is first important to understand the concepts of target definition instances and referenced definition instances. A target is a definition instance that is affected by some other definition at run time on the client. The specific impact on a target is typically setting a value in that definition. Targeted definitions are almost always a property.

A referenced definition instance is one whose value, or in certain circumstances the definition instance itself, is returned to the definition referencing it. What is done with the value or definition instance returned depends entirely on the referring definition.

A target path is then used to specify the definition instance to be targeted or referenced. Target paths always deal with a specific definition instance. A target path is a path evaluated in the context of the definition in which it is contained at run time on the Agentry Client.

A basic example of a target path is the value of a property to be displayed by a detail screen field. As a part of a detail screen field’s definition the property to be displayed by the field is specified. This property is specified using a target path. This path may take the basic form:

:>"CompanyName" Property

In this basic example, the field is defined to display the property named CompanyName found in the definition being displayed by the detail screen containing the field. At run time this path is evaluated by the Agentry Client and the value of that property at that time is displayed in the field.

Target paths can retrieve data values from numerous definitions, including properties, the current value of a screen field, complex table fields, data table fields, and other definitions. The path itself can be as basic as the previous example, or far more complex and include rule evaluation and currently selected items in a list to determine the desired value. The complexity of the target path depends on numerous factors, including the context of the definition containing the target path and how that context relates to the logical location of the value to be retrieved, the parameters by which the value should be selected (e.g. a currently selected item in a list, a record from a complex table, etc.), and the nature of the definition in which the target value is located. Consider the following more sophisticated target path:

:>Main Screen Set>"ShowCustomers_List_PPC" List Screen>Current Object>"CustomerID" Property

This path returns the CustomerID property of the object that is currently selected in the ShowCustomers_List_PPC list screen, which is contained in the main screen of the current module. Such a path would be needed in a situation where the context of the definition needing this value is one where the module main screen set is not a descendent, for example a transaction definition. The above path may be one used to specify the initial value of a transaction property that must be initialized from the currently selected item in the list screen specified. Transactions are child definitions of the module, just as screen sets are. This means the transaction and screen set are siblings and the transaction is, therefore, not a descendent of the screen set.

Creating Target Paths: Attribute Field Context Menus

The first option when setting the target path for an attribute is to use the context menu displayed by the ellipses button for that attribute field. A basic example of this is a transaction property’s target Object Property. This attribute is common among all transaction properties and specifies the object property whose value is to be set to the value of the transaction property when the transaction is applied.

When setting this attribute, the ellipses button is clicked in the Editor for this attribute to display the context menu. Included in this menu is a list of all properties found in the object definition targeted by the transaction. These items are displayed by the Editor as they are the most likely candidates for selection when defining a transaction property’s target:

Selecting an item from this menu creates a target path like the first example shown previously for the CompanyName property. Though not created using the Property Browser, this is still a target path. The Editor provides this list of likely options for the attribute as a shortcut to defining the application.

Creating Target Paths: The Property Browser

The selection of more involved paths is made supported by the Property Browser. The Property Browser can be displayed to set any attribute within the application project where a target path is allowed or required. In most cases, the menu displayed for such an attribute will include a list of likely definitions to be targeted by the attribute (based on the current context) and an additional menu item of Browse... or Browse Objects... This menu item displays the Property Browser, which provides a tree control of the various definitions in the structure of the application project that are valid selections for the attribute:

The available items in the property browser will vary from one definition to the next, depending on what the valid definition types are for the attribute and the definition containing that attribute. As with other aspects of the target paths behavior, this is driven by context.

An important concept to understand when using the Property Browser is that definitions are organized within it based on the data structure defined within the application project as it will exist on the Agentry Client at run time. This is a different structure than the one presented in the main Project Explorer View of the Agentry Editor.

Consider the example of two of the object definitions Customer and Order found in the Mobile Northwind application. When viewing this project in the main Project Explorer view, both of these definitions are listed under the module as its child definitions. Customer and Order are sibling definitions within the application project and are therefore presented at the same level in the hierarchy. By contrast, when viewing the Property Browser these definitions are presented differently. The Customer object may be presented as a root node in the tree (as in the previous example). Expanding it reveals all of that objects properties, including the Orders collection property which will contain the Order object instances for a given Customer at run time. While the Project Explorer View also lists this collection property, the Property Browser goes further in that the Orders collection can be expanded to reveal several child nodes related to selecting a specific Order object instance based on some condition. Furthermore, under the selection criteria for an object instance in a collection, additional child nodes are displayed to allow for the selection of a specific property within that object.

The presentation of the definitions of the Property Browser is a reflection of the fact that the purpose of a target path is to select an instance of a definition at run time, based on some criteria. The criteria can be as simple as some property in the object instance targeted by a transaction; or it can be more sophisticated, such as a property in the parent object to the one targeted by the transaction, or even based on a rule evaluated at run time. Whereas the Project Explorer View deals with the definitions, the Property Browser details within specific instances of those definitions.

Beyond objects and their properties, the Property Browser can display several other definition types from which data can be retrieved on the Agentry Client at run time. These include items such as screen field values, the selected object in a list, a record in a data table or complex table, as well as specific fields within those records, and properties in transactions or fetches. The specific definition types available depends on the context in which the path will be evaluated at run time. For example, an object read step includes a Read Into attribute that specifies the target collection property into which data is read by that step during synchronization. When the Property Browser is displayed for this attribute there are far fewer options available than for some other attributes. in this situation, the options are limited to only object collection properties nested under the object for which the read step is being defined.

The Property Browser presents numerous options for selecting a specific definition instance, such as an object within a collection or a record within a complex table. Such options include the first or last item in a set, an object where the key property matches some specified value, or a record or object instance returned based on the evaluation of a rule. Understanding how to use the Property Browser to create such target paths is an important concept when developing many real-world applications or modifying existing applications to meet the specific needs of an implementation.

Basic Target Path Syntax

The syntax rules for a target path are important to understand so that when viewing a target path the developer can understand where the value being referenced is located within the application. There is no need, however, for the developer to understand the syntax at such a level as to be able to create such a path by hand. The Agentry Editor does not allow a target path to be entered manually for any attribute.

First, all target paths begin with the symbols :>. This simply denotes the beginning of the path for the target path parser built into the Agentry Client. This symbol is then followed by a definition name and type, or in some cases a generic definition type. A basic target path can end with just a single definition if that definition is found within the definition instance that is currently on context. Other paths contain multiple components, with each separated by the > symbol. Each definition referenced in the path includes the name enclosed in quotes followed by the definition type.

Looking at the previous example, then:

:>Main Screen Set>"ShowCustomers_List_PPC" List Screen>Current Object>"CustomerID" Property

The first component to this path is Main Screen Set. This is a generic component that refers to the main screen for the module. This value does not contain the name of this definition, which allows it to be used and evaluated properly even when the name of this screen set changes. The second component to the path is “ShowCustomers_List_PPC” List Screen. This component specifies the list screen of this name found within the main screen set of the module. Current Object is the next component and this refers to the currently selected object within the list screen. The final component is the “CustomerID” Property. This then specifies the CustomerID property within the currently selected object in the list. To create this path, the following was selected within the Property Browser of the Mobile Northwind application project in the Agentry Editor.

Note the selection, including the nodes above it in the tree control. The root node of the selected item displays “CustomerAccounts” Module’s Main Screen Set (“ShowCustomers”). However, this full description is not the item returned for the target path. Note the line of text displayed above the tree control in the screen header of the Property Browser. This is the actual target path that will be returned to the attribute for which the selection is being made.

In many cases a definition will be replaced in the target path with a more generic value, such as “Current Screen Set”, “Current Property”, etc. At run time, when the target path is evaluated by the Agentry Client, these more generic values allow for the reuse of a target path in multiple contexts. In some cases such paths are required. As shown in an example to be provided shortly, the target paths evaluated in the context of a detail screen that is in turn displayed through one of the tile category of detail screen fields (List Tile View, Tile Edit, and Tile Display) require such generic values in the target path when referencing another value on the same detail screen.

In other situations the target path selected in, for example, a rule definition may be replaced with a more generic value after that rule is saved. A common example of this behavior is when specifying a collection property for the @COUNT function. In many cases when the collection is selected the target path displayed in the rule editor will be something similar to “Customers” Collection Property. However, when the rule is saved and subsequently viewed or edited that same path will be the value “Current Property”. If the context of the rule evaluation includes the previously selected Customers collection, current property will resolve to that collection. Furthermore, the replacement of the name-specific value with the more generic one allows that rule term to be evaluated in the context of a different collection property, such as Orders.