Function Criteria Operators
- 4 minutes to read
The eXpressApp Framework provides various approaches to filter List Views: on the data source level, via 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.
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:
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.
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.
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.
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.
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 View via 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.
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:
- Custom Function Criteria Operators should implement the ICustomFunctionOperatorConvertibleToExpression interface.
- The IsInstanceOfType and IsExactType Function Criteria Operators are not supported.
When configuring a UI using the Conditional Appearance Module:
- Custom Function Criteria Operators should be evaluable on the server-side.
- The Abs, Acos, Ascii, Asin, Atn2, Atn, BigMul, Ceiling, Char, Cos, Cosh, Exp, Floor, Log10, Log, Max, Min, Power, Rnd, Round, Sign, Sin, Sinh, Sqr, Tan, Tanh, UtcNow Function Criteria Operators are not supported.