- The object collection to be searched must be defined.
- The definition containing the value to be compared to the property value of the object must exist. This could be a property, a screen field, a global, or any other definition from which a value can be retrieved.
- It is strongly recommended that the value to be searched on is the key property of the object type contained in the collection.
- The module’s object data structure is Customer -> Orders Collection -> OrderItems Collection.
- OrderItems is a collection of OrderItem objects that represent items within a given order. OrderItems can be added to the Order object using the AddOrderItem transaction and related wizard screen set.
- When adding an OrderItem, the complex table Products is used to select the item to be added. The key property of the OrderItem object and the key field of the Products complex table are both the ProductID value.
- The AddOrderItem screen set displays a complex table search field for the Products complex table. When a record is selected in this field it displays the ProductID value of the selected record.
- A field of edit type Label is present on the detail screen in the AddOrderItem wizard. The field is defined to display the label text DUPLICATE. The RedText style has been applied to this field to display the label text in red and in a larger font size than other field on the screen.
- Other fields not directly related to this procedure displayed on this screen are the unit price, quantity being ordered, and discount percentage.
This procedure provides instructions and an example on how to create a target path that returns an object instance from a collection property where a property of that object instance matches some value. The value to be compared against the collection must be accessible in the current context and therefore must be defined prior to performing this procedure. For this example, a detail screen field displaying a string will be used.
At run time the behavior of the Agentry Client will be to evaluate the target path and to compare the selected property in each instance the object in the collection property to the selected search value until a match is found. The first matching object instance is then returned. Note that this iterative processing can include up to as many iterations as their are object instances stored in the collection property. Typically this is not an issue for performance unless the collection contains an exceptionally large number of object instances (hundreds or thousands). However, if this target path is itself evaluated as a part of some outer loop of iterative processing, a performance issue could be encountered. For example, if the collection contains 100 object instances, and the outer loop iterates as little as 10 times, the total number of evaluations could be as many as 1,000.
Such a situation could also be encountered if the target path is evaluated in an update rule for a detail screen field. Update rules are evaluated numerous times during the initial presentation of the parent screen, and additionally whenever the user interacts with the detail screen. On a wizard screen, this would result in the target path being evaluated each time the user enters a character in a string field, or makes a selection in some list or drop down field on the same screen.
In this example the Property Browser is used to create a path that searches the OrderItems collection of an Order object for an OrderItem with a ProductID (key property) that matches the one currently selected in the AddOrderItem wizard. The goal is to display a clear indicator on the AddOrderItem wizard screen when a product is being selected that has already been added to the OrderItems collection. While the Agentry Client would prevent a second object with the same key property from being added to the collection, and an error message is displayed, this does not occur until the Agentry Client attempts to apply the transaction. A cleaner user interface is possible that displays a message as soon as the duplicate product is selected.
The label field contain the text DUPLICATE is to be modified with it’s Hidden Rule attribute set to a rule that checks the OrderItems collection for an object with a ProductID value equal to the one currently selected in the Product ID field of the AddOrderItem wizard. The rule will contain a target path that makes this check and returns the property ProductID from the object found. If no object is found, then a null value is returned by the target path. The return from this path is to be passed as a parameter to the rule function NOT, which treats any parameters as Boolean values and inverts them. The Hidden Rule evaluates the rule it contains in a Boolean context. When such a rule returns true, the field containing the attribute is hidden from the user. When it is false, the field is displayed.
The overall logic, then, will be that the user selects a product from the complex table. The Hidden Rule for the label field DuplicateFlag will be evaluated. This rule contains the target path that compares the selected ProductID value to the ProductID property of each object in the OrderItems collection. If a match is found, the ProductID value of that object is returned to the NOT function within the rule. This is treated by the NOT function as true, since the path is evaluated in a Boolean context and any non-null value is true. NOT inverts this value, thus returning false to the Hidden Rule attribute. This results in the DuplicateFlag field being displayed. On the wizard screen the text DUPLCIATE is displayed in large red text. If the user selects a product that is not currently found in the OrderItems collection, the target path in the Hidden Rule will not find a matching object. The value returned by the path will be NULL. The NOT function treats NULL as false. It will then invert this value, returning true to the Hidden Rule attribute. This will hide the DuplicateFlag field on the screen.
- In our Mobile Northwind application we select
the DuplicateFlag field definition in the AddOrderItem_Detail_PPC
detail screen. In the Properties View we view the Rules / Hyperlink
/ Special Value tab:
- Clicking the ellipses field to the right of the Hidden
Rule attribute displays a context menu. Selecting the menu item Add
Rule displays the Rule Editor. Here the name can be left set
to the default of DuplicateFlag_HiddenRule. Advancing the wizard
displays the main Rule Editor screen. The first term to be added
to this term is the NOT function:
- The first and only expression parameter for this function
is to be the target path to search the collection. With the Expression
1 field selected in the Rule Editor, we click the Properties list
and select Browse Properties... This displays the Property
Browser. In this browser we will build the target path to search
the OrderItems collection targeted by the transaction. We select
the path AddOrderItem Transaction | Targeted collection of OrderItems
Objects | Select the OrderItem Object from the collection by its
Key Field. Right clicking the last item in this path displays
a context menu:
This selection creates the first part of the target path, which indicates the OrderItems collection targeted by the transaction. We are then specifying that we want a single object instance from this collection. There are multiple options for choosing the object instance. For this use case the proper selection is to look for the object by its key property.
- In the context menu, first note that the key property
ProductID is selected by default. The other properties are also
listed, but typically the key property is used as it is the only
value guaranteed to be unique within the collection. We now select
the last item in the menu is equal to (Browse for Property)... This
selection is where the value to be compared to the key properties
of the object instances is selected. This selection displays a second
Property Browser. The value we wish to search on is the current
value in the Product ID field of the detail screen. So, the path
we select is Current (“AddOrderItem_Detail_PPC”) Detail Screen
| ProductID Field:
This selection creates a target path that returns the value currently displayed in the Product ID field of the detail screen. This path can be thought of as one that is contained within the path selected in the first Property Browser. This “inner path” is evaluated once for each object in the OrderItems collection until the value it returns matches the ProductID property of an object in that collection, or until all objects have been searched.
- Click the OK button in this second Property Browser screen.
We must now make one final selection in the first Property Browser,
which is the property value to be returned from the OrderItem object found
in the collection. This could not be selected previously as this
selection cannot be made until the search criteria is specified.
Now that it is selected, the node indicating search by key property
can be expanded, revealing the properties within the OrderItem object.
Here, the property to be returned is selected. The safe selection
for our use case is the ProductID, as it will always contain a value. Other
properties can be selected in other use cases, depending on what
data is needed from the object found:
- Close this Property Browser by clicking OK. We are returned
to the Rule Editor, where the rule now appears as follows:
Clicking [Finish] returns us to the Properties View for the DuplicateFlag label field. The changes are saved in this view and the modification is complete in the Application Project.
At this point, the changes made are complete. We will now publish and test this modification. the following examples are from the Agentry Test Environment.
When the user adds an OrderItem
for an Order, the AddOrderItem wizard is initially displayed:
When the user makes
a selection in the ID field, the Hidden Rule for the currently hidden
DuplicateFlag field, the target path built in the previous procedure
is evaluated within the rule definition. The value displayed in
the ID field is compared to the ProductID property in each OrderItem
object in the collection targeted by the AddOrderItem transaction.
If a match is found, the path returns the ProductID of that object
instance, which is treated as true. The NOT function inverts the
value within the rule, returning false. A false Hidden Rule value
indicates the field should not be hidden, and the field’s label
text is displayed:
The user has now
been informed that the product currently selected is already a part
of the Order. If the user then makes another selection, the Hidden
Rule, including the target path it contains, is evaluated again.
If no matching OrderItem is found, the DuplicateFlag field is hidden
and the user knows the product can be ordered: