How to: Use Criteria Property Editors
- 7 minutes to read
This topic details the specifics of using Criteria Property Editors in an XAF application. An application that allows end-users to design and save filtering criteria at runtime is demonstrated here.
Note
Mobile applications do not provide any Criteria Property Editor, so the approach described in this topic cannot be implemented in the Mobile platform.
Tip
A complete sample project is available in the DevExpress Code Examples database at https://supportcenter.devexpress.com/ticket/details/e932/how-to-use-criteria-property-editors.
To create the sample application, do the following:
- Define business classes whose List Views will later be filtered.
- Define the FilteringCriterion business class that represents filtering criteria for the Product‘s List View.
- Create a custom View Controller that contains an Action used to filter the List View.
To begin building the sample application, create a new XAF application solution named HowToUseCriteriaPropertyEditors using the DevExpress v19.1 XAF Solution Wizard Template Gallery.Built-in Visual Studio Templates.
Step 1 - Add the Product and Person Business Classes
Right-click the HowToUseCriteriaPropertyEditors.Module project, and choose Add DevExpress Item | New Item… to invoke Template Gallery. Then select the XAF Business Object | XPO Business Object project item, name it Product, and press Add Item. You will get an automatically generated code file with a single class declaration. Replace the automatically generated class declaration with the following code, defining a class with four persistent properties of different types:
[DefaultClassOptions, ImageName("BO_Product")]
public class Product : BaseObject {
public Product(Session session) : base(session) { }
public string Name {
get { return GetPropertyValue<string>("Name"); }
set { SetPropertyValue<string>("Name", value); }
}
public double Price {
get { return GetPropertyValue<double>("Price"); }
set { SetPropertyValue<double>("Price", value); }
}
public int Quantity {
get { return GetPropertyValue<int>("Quantity"); }
set { SetPropertyValue<int>("Quantity", value); }
}
public Person Manager {
get { return GetPropertyValue<Person>("Manager"); }
set { SetPropertyValue<Person>("Manager", value); }
}
}
The Manager reference property is of the Person type, that is the class from the Business Class Library. Add a Person item to the ShowNavigationItem and to the New action, via the Model Editor (see Add an Item to the Navigation Control and Add an Item to the New Action).
Step 2 - Define the FilteringCriterion Business Class
Add the Domain Object named FilteringCriterion to the HowToUseCriteriaPropertyEditors.Module project, and replace the automatically generated class declaration with the following code:
using DevExpress.ExpressApp.Editors;
using DevExpress.ExpressApp.Utils;
using DevExpress.Persistent.Base;
using DevExpress.Persistent.BaseImpl;
using DevExpress.Xpo;
using System;
using System.ComponentModel;
//...
[DefaultClassOptions, ImageName("Action_Filter")]
public class FilteringCriterion : BaseObject {
public FilteringCriterion(Session session) : base(session) { }
public string Description {
get { return GetPropertyValue<string>("Description"); }
set { SetPropertyValue<string>("Description", value); }
}
[ValueConverter(typeof(TypeToStringConverter)), ImmediatePostData]
[TypeConverter(typeof(LocalizedClassInfoTypeConverter))]
public Type ObjectType {
get { return GetPropertyValue<Type>("ObjectType"); }
set {
SetPropertyValue<Type>("ObjectType", value);
Criterion = String.Empty;
}
}
[CriteriaOptions("ObjectType"), Size(SizeAttribute.Unlimited)]
[EditorAlias(EditorAliases.PopupCriteriaPropertyEditor)]
public string Criterion {
get { return GetPropertyValue<string>("Criterion"); }
set { SetPropertyValue<string>("Criterion", value); }
}
}
Objects of this class represent filtering criteria. The Description field contains the text that describes a criterion. These descriptions will be used to fill a drop-down list of possible filters. The Criterion property holds a criterion. To use the built-in XAF Criteria Property Editors, the property that holds a criterion must have the CriteriaOptionsAttribute applied. The attribute’s parameter is the name of an additional Type property, which specifies the objects’ type used in the construction of the criterion. In this sample, it is the ObjectType property. Additionally, the CriteriaOptions attribute changes the default Property Editor for the property:
- CriteriaPropertyEditor is used in Windows Forms applications
- ASPxCriteriaPropertyEditor is used in ASP.NET Web applications
Step 3 - Create a Custom List View Controller
Add the following CriteriaController class to the HowToUseCriteriaPropertyEditors.Module project.
using DevExpress.ExpressApp;
using DevExpress.ExpressApp.Actions;
using DevExpress.Persistent.Base;
using DevExpress.ExpressApp.Editors;
using DevExpress.Data.Filtering;
using DevExpress.ExpressApp.Templates;
// ...
public class CriteriaController : ObjectViewController {
private SingleChoiceAction filteringCriterionAction;
public CriteriaController() {
filteringCriterionAction = new SingleChoiceAction(
this, "FilteringCriterion", PredefinedCategory.Filters);
filteringCriterionAction.Execute += new DevExpress.ExpressApp.Actions.SingleChoiceActionExecuteEventHandler(this.FilteringCriterionAction_Execute);
TargetViewType = ViewType.ListView;
}
protected override void OnActivated() {
filteringCriterionAction.Items.Clear();
foreach (FilteringCriterion criterion in ObjectSpace.GetObjects<FilteringCriterion>())
if (criterion.ObjectType.IsAssignableFrom(View.ObjectTypeInfo.Type)) {
filteringCriterionAction.Items.Add(
new ChoiceActionItem(criterion.Description, criterion.Criterion));
}
if (filteringCriterionAction.Items.Count > 0)
filteringCriterionAction.Items.Add(new ChoiceActionItem("All", null));
}
private void FilteringCriterionAction_Execute(
object sender, SingleChoiceActionExecuteEventArgs e) {
((ListView)View).CollectionSource.BeginUpdateCriteria();
((ListView)View).CollectionSource.Criteria.Clear();
((ListView)View).CollectionSource.Criteria[e.SelectedChoiceActionItem.Caption] =
CriteriaEditorHelper.GetCriteriaOperator(
e.SelectedChoiceActionItem.Data as string, View.ObjectTypeInfo.Type, ObjectSpace);
((ListView)View).CollectionSource.EndUpdateCriteria();
}
}
This Controller adds the FilteringCriterion SingleChoiceAction and populates the Action’s dropdown list with all the existing FilterCriterion objects whose ObjectType matches the type of objects displayed in the current List View.
The FilteringCriterion Action applies the criterion selected in the dropdown list to the List View. Note that to convert the Criterion property’s value of a FilterCriterion object to the DevExpress.Data.Filtering.CriteriaOperator object, you need to call the static CriteriaEditorHelper.GetCriteriaOperator method. This method takes three parameters. The string parameter represents the criterion to be converted. The Type parameter specifies the object type for which the criterion is constructed. The ObjectSpace parameter specifies any IObjectSpace that contains objects of the specified type.
Note
You should not use the CriteriaOperator.Parse method in this scenario. Criteria Property Editors can generate Criteria Strings containing Object Parameters, which are specific to XAF and cannot be parsed by CriteriaOperator.Parse.
Now you can run the Windows Forms or ASP.NET application, create several Person, Product and FilterCriteria objects, and then try the FilteringCriterion action.
The Criteria Property Editors are also demonstrated in the Property Editors | Criteria Properties section in the Feature Center demo installed with XAF. The Feature Center demo is installed in %PUBLIC%\Documents\DevExpress Demos 19.1\Components\eXpressApp Framework\FeatureCenter by default. The ASP.NET version of this demo is available online at https://demos.devexpress.com/XAF/FeatureCenter/.