Function Criteria Operators

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:

Operator	Description	Examples
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)

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.

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:
- Function Operator's arguments should be OperandValue or OperandProperty.
- Nested Function Operators are not supported.
- Custom Function Criteria Operators should be evaluable on the server-side (except the IsInstanceOfType Operator). This means that they should be OperandValue.
- The Iif 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 Ascii, Char, Abs, Sqr, Cos, Sin, Atn, Exp, Log, Rnd, Tan, Power, Sign, Round, Ceiling, Floor, Max, Min, Acos, Asin, Atn2, BigMul, Cosh, Log10, Sinh, Tanh, UtcNow Function Criteria Operators are not supported.

Built-in Function Criteria Operators cover the most common data management scenarios. Additionally, you can define custom Function Criteria Operators for those situations when the built-in Operators do not suit your needs. For example, if you are frequently using a particular expression, and do not want to type it over and over again, you can implement a custom Function Criteria Operator. A custom Function Criteria Operator is defined by a class implementing the ICustomFunctionOperator interface. The interface exposes three members allowing you to specify a custom function and evaluate its value on the client side. The Name property specifies the name of the custom Operator. The ResultType method calculates the return type of the custom Function Criteria Operator, based on the types of passed arguments. The Evaluatemethod calculates the Function Criteria Operator's value based on the passed arguments.

public class WeekAgoOperator : ICustomFunctionOperator {
    public string Name {
        get { return "WeekAgo"; }
    }
    public object Evaluate(params object[] operands) {
        return DateTime.Today.AddDays(-7);
    }
    public Type ResultType(params Type[] operands) {
        return typeof(DateTime);
    }
}

To use a custom Function Criteria Operator, you need to register it. For this purpose, first add a static constructor to the Operator. In the constructor, invoke the CriteriaOperator.RegisterCustomFunctionmethod. Placing this method call into the static constructor ensures that the Operator will not be registered twice accidentally.

using DevExpress.Data.Filtering;
//... 
public class WeekAgoOperator : ICustomFunctionOperator {
    //... 
    static WeekAgoOperator() {
        WeekAgoOperator instance = new WeekAgoOperator();
        if (CriteriaOperator.GetCustomFunction(instance.Name) == null) {
            CriteriaOperator.RegisterCustomFunction(instance);
        }
    }
    public static void Register() { }
}

Then, invoke this constructor in a module constructor.

public sealed partial class MyModule : ModuleBase {
    public MyModule() {
        WeekAgoOperator.Register();
    }
}

After registering a Function Criteria Operator, you can use it anywhere it is required - in List View filters, Validation and Appearance rules, object-level security permissions, etc. For example, you can create a List View filter via the Filter Action that will use your Operator, i.e. select only the objects that were shipped within the last seven days.

ShippingDate > WeekAgo()

If your custom Function Criteria Operator is going to be used in a server-side filtering, support the ICustomFunctionOperatorFormattable interface as well.

Note that a custom Function Criteria Operator can be used in several applications. So, it is recommended that you implement all necessary custom Function Criteria Operators in a separate module.

Note

There is an example of how to create a custom Function Criteria Operator in the DevExpress Code Central database at http://www.devexpress.com/example=E3945. Depending on the target platform type (ASP.NET, WinForms, etc), you can either run this example online or download an auto-executable sample.

FXFE

Tuesday, March 20, 2018