Gary's Blog

In 10.2 we’ve re-written a lot of the XAF internals and as a result, we now have complete support for function criteria operators in all areas of XAF; for example, when specifying criteria for reports (FilterString property), List Views (SetFilterAction, ListView.Criteria property), KPI criteria, CriteriaEditor, Analysis objects, etc. And the best part? Since it is the internal components that were rewritten, there should not be any breaking changes! You can simply start using function criteria operators anywhere you need.

It’s all pretty straight forward, perhaps the only area where it’s a little tricky is where we implemented support for function criteria operators in built-in validation rules

You can already use criteria operators when specifying criteria for the vast majority of built-in validation rules. The only exceptions are the RuleRange and RuleValueComparison validation rules. For compatibility reasons we have decided to introduce a new mode of operation for these rules. Now the rule constructors can take an additional mode parameter specifying how other parameter values are treated. If the parameter value is ParametersMode.Expression then criteria strings are treated as expressions and you can use criteria operators. If the parameter value is ParametersMode.Value then criteria strings are treated as strings and you can use read-only parameters. Here’s an example of what I mean:

In 10.1, if you want to declare a rule using the CurrentDate read-only parameter you would write something like this…

[RuleValueComparison("MyRule1", DefaultContexts.Save, ValueComparisonType.LessThan, "@CurrentDate")]

Now it 10.2 you’d can use the LocalDateTimeToday function criteria operator like this…

[RuleValueComparison("MyRule1", DefaultContexts.Save, ValueComparisonType.LessThan, "LocalDateTimeToday()", ParametersMode.Expression)]

Here’s another example:

In 10.1, using WeekAgo and CurrentDate:

[RuleRange("MyRule2", "Save", "@WeekAgo", "@CurrentDate")]

And in 10.2 using AddDays and LocalDataTime:

[RuleRange("MyRule2", "Save", "AddDays(LocalDateTimeToday(), -7)", "LocalDateTimeToday()", ParametersMode.Expression)]

As you can see, function criteria operators are much more powerful and flexible than read-only parameters. If you are thinking that the mode parameter looks a little odd then don’t worry, in the future, when we completely abandon XAF parameters, we will probably remove the mode parameter in these validation rules.

But what about transitioning from read-only parameters to criteria operators I hear you ask? We had about a dozen read-only operators available out of the box and here are some examples of possible transitions…

To transition from CurrentUserIdParameter use the new CurrentUserId custom function criteria operator available in all XAF applications and to transition from CurrentDateTimeParameter use the standard LocalDateTimeNow function criteria operator. Now transitioning from WeekAgoParameter is a little more tricky as there is no such standard function criteria operator to replace it with. Instead the parameter should be rewritten as an expression, like so: AddDays(LocalDateTimeToday(), -7).

If you find yourself frequently using the WeekAgoParameter, and do not want to type the expression over and over, you can implement a custom function criteria operator like so:

using DevExpress.Data.Filtering;

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);
    }
}

As you can see, writing a custom function criteria operator is just as straightforward as writing a custom read-only parameter. Custom criteria operators have an advantage however, they can take operands. So, while a read-only parameter can only return some value, a criteria operator value can be calculated based on the operand values.

To use a custom function criteria operator, you need to register it. This can be done, for example, in a custom module:

public override void CustomizeTypesInfo(DevExpress.ExpressApp.DC.ITypesInfo typesInfo) {
    base.CustomizeTypesInfo(typesInfo);

    XafTypesInfo.XpoTypeInfoSource.XPDictionary.CustomFunctionOperators.Add(new WeekAgoOperator());
}

After registering a criteria operator, you can use it anywhere you need. For example, you can create a List View filter via the Filter Action, that will use your operator, to, say select only the objects that were shipped within the last seven days:

ShippingDate > WeekAgo()

So to sum up, we now recommend that you use criteria operators instead of read-only parameters, because:

1. They are easier to work with as there are a lot of predefined operators – actually about ten dozen - such as LocalDateTimeAfterTomorrow or Replace (See Criteria Language Syntax and FunctionOperatorType Enumeration). So, in most cases you can save yourself some time by not having to implement a read-only parameter and register it.
2. They are more flexible since they can take operands, and so you can implement some really smart logic in an operator.
3. Unlike read-only parameters, which by their nature are always evaluated on the client side, certain criteria operators can be evaluated on the server side. And this means better performance.

Well that is all from this post, until next time, happy XAF’ing