Criteria Properties
- 5 minutes to read
A string property that stores a Criteria Language Syntax expression can be displayed from:
- a Filter Builder control;
- an editor that allows end users to type a criteria manually and display a Filter Builder in a pop-up.
Note
To see an example of using Criteria Property Editors, refer to the How to: Use Criteria Property Editors topic.
To see Criteria Property Editors in action, refer to 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 18.2\Components\eXpressApp Framework\FeatureCenter by default. The ASP.NET version of this demo is available online at https://demos.devexpress.com/XAF/FeatureCenter/.
Examples
- Criteria Properties in XPO
- Criteria Properties in Entity Framework
- Criteria Properties in Domain Components
WinForms Property Editors for Criteria Properties
Each WinForms Property Editor has a control that displays a corresponding property in a Detail View, and a repository item that displays a property in a List Editor that supports in-place editing. Both the control and repository item are shown below.
CriteriaPropertyEditor
Control: FilterEditorControl.
Repository Item: There is no specific repository item.
Description:
Intended for string properties that store filter criteria. This Property Editor allows end-users to construct the filter criteria using a Filter Builder control in a Filter tab, or by typing text in the Text tab.
String properties that store filter criteria must be decorated with CriteriaOptionsAttribute. By default, in Windows Forms applications, these properties are represented by this Property Editor.
PopupCriteriaPropertyEditor
Control: FilterEditorControl.
Repository Item: RepositoryItemPopupCriteriaEdit - a descendant of the RepositoryItemButtonEdit repository item from the XtraEditors Library.
Description:
Intended for string properties that store filter criteria. This Property Editor allows end-users to construct filter criteria in a separate window to conserve space in the detail form. This window displays the CriteriaPropertyEditor.
To use this Property Editor, assign it to the PropertyEditorType property of the required BOModel | <Class> | OwnMembers | <Member> node or Views | <DetailView> | Items | <PropertyEditor> node.
The property that is displayed by this Property Editor must be decorated with CriteriaOptionsAttribute.
PopupCriteriaPropertyEditor creates a pop-up Detail View with the CriteriaPropertyEditor item, which uses the FilterEditorControl component internally. To access FilterEditorControl options, use the approach similar to described in the Access Editor Settings tutorial - implement a View Controller for the Detail View of the DevExpress.ExpressApp.Editors.CriteriaProvider type and access the CriteriaPropertyEditor.Control property.
ASP.NET Property Editors for Criteria Properties
Each ASP.NET Property Editor has controls that display a property in a Detail View‘s View and Edit mode (see DetailView.ViewEditMode). These controls are listed below.
ASPxCriteriaPropertyEditor
View mode control: System.Web.UI.WebControls.Label.
Edit mode control: ASPxFilterControl.
Description:
Intended for string properties that store filter criteria. This Property Editor allows end-users to construct the filter criteria using a Filter Builder control in a Filter tab, or by typing text in the Text tab.
String properties that store filter criteria must be decorated with CriteriaOptionsAttribute. By default, these properties are represented by this Property Editor in ASP.NET Web applications.
ASPxPopupCriteriaPropertyEditor
View mode control: System.Web.UI.WebControls.Label.
Edit mode control: ASPxButtonEdit.
Description:
Intended for string properties that store filter criteria. This Property Editor allows end-users to construct filter criteria in a separate window to conserve space in a detail form. This window displays ASPxCriteriaPropertyEditor. To use this Property Editor, set it for the PropertyEditorType property of the required BOModel | <Class> | OwnMembers | <Member> node or Views | <DetailView> | Items | <PropertyEditor> node.
String properties that store filter criteria must be decorated with CriteriaOptionsAttribute.
Criteria Property Editors Options in ASP.NET Applications
When you edit criteria using the Visual tab, you can either select object properties in a plain list or in the tree-like structure (which makes referenced objects’ properties available).
Both ASPxCriteriaPropertyEditor and ASPxPopupCriteriaPropertyEditor editors expose the following properties.
| Property | Type | Description |
|---|---|---|
| AllowFilterControlHierarchy | Boolean | Specifies whether or not the hierarchy tree is displayed for the reference properties. |
| MaxHierarchyDepth | Int32 | Specifies the maximum hierarchy depth level that can be displayed when AllowFilterControlHierarchy is enabled. |
Note
You can also use similar options of the ASPxGridListEditor to adjust the behavior of the grid’s filter control:
To change these options for an individual editor, use the following Controller:
using DevExpress.ExpressApp;
using DevExpress.ExpressApp.Web.Editors.ASPx;
// ...
public class CriteriaEditorController : ViewController<DetailView> {
protected override void OnActivated() {
base.OnActivated();
ASPxCriteriaPropertyEditor propertyEditor =
View.FindItem("MyCriteriaProperty") as ASPxCriteriaPropertyEditor;
if(propertyEditor != null) {
propertyEditor.AllowFilterControlHierarchy = true;
propertyEditor.MaxHierarchyDepth = 4;
}
}
}
To change these options globally, for all ASPxCriteriaPropertyEditor and ASPxPopupCriteriaPropertyEditor editors in your application, use the following static properties.
- ASPxCriteriaPropertyEditor.AllowFilterControlHierarchyDefault
- ASPxCriteriaPropertyEditor.MaxHierarchyDepthDefault
Additionally, you can use the static ASPxCriteriaPropertyEditor.AlwaysShowKeyPropertyInFilterControl property. It specifies if the key property is visible in the ASPxFilterControl even if the Browsable(false) attribute is applied. The default value is true.
As these properties are static, you can access them from any appropriate location in your code (e.g., from the WebApplication constructor).
using DevExpress.ExpressApp.Web.Editors.ASPx;
// ...
ASPxCriteriaPropertyEditor.AllowFilterControlHierarchyDefault = true;
ASPxCriteriaPropertyEditor.MaxHierarchyDepthDefault = 3;
ASPxCriteriaPropertyEditor.AlwaysShowKeyPropertyInFilterControl = false;
Criteria Property Editors Limitations in ASP.NET Applications
The persistent objects can be used in the criteria construction (in this example it is the Manager reference property of the Person type). Reference properties are displayed using a Lookup Property Editor in the Windows Forms application. By default, this Lookup List View contains a single column with the object’s default property. You can add more columns by decorating the required properties with the VisibleInLookupListViewAttribute, or by adding columns to the corresponding Lookup List View in the Model Editor. However, in an ASP.NET application, lookup property editors are represented by combo boxes, by default. Currently, you cannot use a complex lookup editor within the ASP.NET Criteria Editors:
- You cannot use the Equals operator and choose reference property values from a lookup when the AllowFilterControlHierarchy property is set to true.
- In ASP.NET Criteria Property Editors, certain Function Criteria Operators can be used in the Text tab only.