Tuesday, March 20, 2018

Function Criteria Operators

Function Criteria Operators

The eXpressApp Framework provides various approaches to filter List Views: on the data source levelvia the Application Model and special methods for filtering Lookup Property Editors' List Views. In each approach, you may need to set static variables as filter criteria values. For example, the filter "Task.DueDate must be set to the current date" needs the CurrentDate variable (calculated each time it is required). For this purpose, use the Function Criteria Operators which represent functions that return a particular value (such as the current date or the current user) or a result of handling the specified arguments (such as the concatenation function). This topic describes Function Criteria Operators, shows how to use them when filtering, and explains how to implement Custom Function Operators.

Expanded Function Criteria Operators Basics

Function Criteria Operators are a part of the criteria language. In criteria strings, a Function Criteria Operator name should be followed by brackets containing operands that represent function arguments, or empty brackets if it does not take arguments. The following criterion demonstrates how to use the LocalDateTimeToday Operator:
[Task.DueDate] = LocalDateTimeToday()
Multiple Function Criteria Operators, such as LocalDateTimeAfterTomorrow or Replace, are available out of the box. Refer to the FunctionOperatorType help topic for a complete list. The following table lists the XAF-specific Function Criteria Operators available in XAF applications:
Operator                        DescriptionExamples
CurrentUserId()Returns the current user's identifier. This custom Function Criteria Operator is registered in the SystemModule's ModuleBase.CustomizeTypesInfo method override. This Operator's Evaluate method returns the SecuritySystem.CurrentUserId property value.
User.Oid = CurrentUserId()
IsCurrentUserInRole(roleName)Determines whether the currently logged on user is assigned to a specified role. Returns false when no user is currently logged on. The SecurityModule registers this custom Function Criteria Operator in the XafApplication.LoggedOn event handler if SecuritySystem.CurrentUser implements the IUserWithRoles or ISecurityUserWithRoles interfaces. This Operator's Evaluate method casts the SecuritySystem.CurrentUser property value to the IUserWithRoles and ISecurityUserWithRoles interfaces and checks that the Roles collection contains the specified role.
IsCurrentUserInRole('Admin')
IsNewObject(obj)Applicable to XPO objects only. Indicates whether a specified object has been created but not saved to the database. This operator's Evaluate method gets the current Object Space using the static XPObjectSpace.FindObjectSpaceByObject method and then returns the XPObjectSpace.IsNewObject result, and returns false if the Object Space is not found. You can use this Operator on the client-side only; do not use it in security permissions criteria.
IsNewObject(This)
IsNewObject(Manager)

Expanded Important Remark on the DateTime Function Criteria Operators

The DateTime parameters do not support the addition and subtraction operations. The following expression is incorrect:
[Task.DueDate] > (LocalDateTimeToday() - 3) AND [Task.DueDate] < (LocalDateTimeToday() + 3)
To add or subtract values from the DateTime parameters, use the DateTime management functions the XPO exposes, such as AddDays and AddYears. For instance, this is the correct way to write the previous criterion:
[Task.DueDate] > ADDDAYS(LocalDateTimeToday(), -3) AND [Task.DueDate] < ADDDAYS(LocalDateTimeToday(), 3)
For a complete list of functions with descriptions, refer to the Criteria Language Syntax help topic.
Note
DateTime parameters support plain addition and subtraction operations in certain database management systems (DBMS) – there are no errors when such an expression is evaluated on the server side. For example, when filtering a List Viewvia the ListViewFilterAttribute, the criterion is processed on the server. If the server supports addition and subtraction operations for the DateTime parameters (for example, MS SQL Server or MS Jet Database Engine), the criterion is correctly processed.

Expanded Limitations of Function Criteria Operators used in Mobile Applications

Note the following limitations when using Function Criteria Operators in Mobile applications:
  • When filtering a data source:
  • When configuring a UI using the Conditional Appearance Module:
    • Custom Function Criteria Operators should be evaluable on the server-side.
    • The AsciiCharAbsSqrCosSinAtnExpLogRndTanPowerSignRoundCeilingFloorMaxMinAcosAsinAtn2BigMulCoshLog10SinhTanhUtcNow Function Criteria Operators are not supported.

Expanded See Also

No comments: