Criteria Properties
- 8 minutes to read
When you build an XAF application, you may need a property that stores filter criteria (an expression that follows Criteria Language Syntax). You can display such properties using the following editors:
- a Filter Builder control
- an editor that allows users to type criteria 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 default location of the application is %PUBLIC%\Documents\DevExpress Demos 23.2\Components\XAF\FeatureCenter.NETFramework.XPO.
Examples
ASP.NET Core Blazor
XAF’s ASP.NET Core Blazor UI supports several Property Editors that works with filter criteria.
Note
Apply CriteriaOptionsAttribute to properties that store filter criteria. XAF generates FilterPropertyEditor controls for such properties. If necessary, you can change the editor type. See available options below.
In ASP.NET Core Blazor, BlazorPropertyEditorBase.ComponentModel returns an IComponentModel descendant that wraps properties and events of a corresponding ASP.NET Core Blazor Editor.
FilterPropertyEditor
IComponentContentHolder descendant: DevExpress.ExpressApp.Blazor.Editors.Adapters.FilterEditorAdapter.
Component: DevExpress.ExpressApp.Blazor.Components.FilterEditor. This internal component initializes and configures the JavaScript Filter Editor. It does not have public API.
The default Property Editor with tree-like and text-based criteria construction.
PopupFilterPropertyEditor
IComponentContentHolder descendant: DevExpress.ExpressApp.Blazor.Editors.Adapters.PopupFilterEditorAdapter.
Component: DxTextBox shipped with the DevExpress ASP.NET Core Blazor Library.
A Property Editor for string properties that store filter criteria. It creates a pop-up Detail View with a FilterPropertyEditor item.
To access the FilterPropertyEditor in the pop-up Detail View, implement a View Controller for the DevExpress.ExpressApp.Editors.CriteriaProvider type. For more information on how to access a Property Editor in a Detail View, refer to the following topic: Access the Settings of a Property Editor in a Detail View.
To enable this Property Editor, use either of the following techniques:
- In the Model Editor
- Specify it in the
PropertyEditorTypeproperty of the required BOModel | <Class> | OwnMembers | <Member> node or Views | <DetailView> | Items | <PropertyEditor> node. - In code
- Decorate the property with EditorAliasAttribute and pass
EditorAliases.PopupCriteriaPropertyEditoras the attribute’s parameter.
CriteriaPropertyEditor
Class: DevExpress.ExpressApp.Blazor.Editors.CriteriaPropertyEditor.
CriteriaPropertyEditor displays a text box and supports expression validation. The knowledge of Criteria Language Syntax is required to work with this Property Editor.
For information on how to enable this editor in your application, refer to the following article: How to specify an XAF Property Editor for properties and types.
Property Visibility Customization In Filter Editors
You can use the FilterEditorModel.CustomizePropertyVisibility delegate to control property visibility in filter editors. The following example demonstrates how to hide key members in Filter Editors. The change applies to grids and PopupFilterPropertyEditor controls:
using DevExpress.ExpressApp;
using DevExpress.ExpressApp.Blazor.Components;
using DevExpress.ExpressApp.Blazor.Editors;
using DevExpress.ExpressApp.Editors;
using Microsoft.AspNetCore.Components;
namespace YourSolutionName.Blazor.Server.Controllers {
public class KeyPropertyInFilterEditorController : ObjectViewController<DetailView, CriteriaProvider> {
protected override void OnActivated() {
base.OnActivated();
View.CustomizeViewItemControl<FilterPropertyEditor>(this, editor => {
editor.ComponentModel.CustomizePropertyVisibility =
EventCallback.Factory.Create<CustomizePropertyVisibilityEventArgs>(this, (e) => {
if (e.MemberInfo.Owner.KeyMember == e.MemberInfo) {
e.Visible = false;
}
});
});
}
}
}
Windows Forms
XAF’s Windows Forms UI supports several Property Editors that works with filter criteria.
Note
Apply CriteriaOptionsAttribute to properties that store filter criteria. XAF generates FilterPropertyEditor controls for such properties. If necessary, you can change the editor type. See available options below.
Each Windows Forms Property Editor is available in two forms:
- A standalone control (displays property value in a Detail View)
- A repository item (displays property value in a List Editor that supports in-place editing)
AdvancedCriteriaPropertyEditor
Control: DevExpress.DataAccess.UI.FilterEditorControl.
Repository Item: None.
The default Property Editor with tree-like and text-based criteria construction.
To display AdvancedCriteriaPropertyEditor for criteria properties, set the static UseAdvancedFilterEditorControl property value to True or Default.
CriteriaPropertyEditor
Control: DevExpress.XtraFilterEditor.FilterEditorControl.
Repository Item: None.
This Property Editor displays a Filter Builder control with two tabs. The Filter tab allows users to construct conditions via an easy-to-use UI. The Text tab allows users to type the criteria.
To display CriteriaPropertyEditor for criteria properties, set the static UseAdvancedFilterEditorControl property value to False.
PopupCriteriaPropertyEditor
Control: DevExpress.ExpressApp.Win.Editors.PopupCriteriaEdit.
Repository Item: RepositoryItemPopupCriteriaEdit, a descendant of the RepositoryItemButtonEdit repository item from the XtraEditors Library.
Use this Property Editor to display a CriteriaPropertyEditor in a separate window and thus save space on the Detail form.
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.
PopupCriteriaPropertyEditor creates a pop-up Detail View with the CriteriaPropertyEditor item that uses the DevExpress.DataAccess.UI.FilterEditorControl or DevExpress.XtraFilterEditor.FilterEditorControl component internally (depending on the static UseAdvancedFilterEditorControl property value). To access FilterEditorControl options, use the technique described in the following article: Access the Settings of a Property Editor in a Detail View. Implement a View Controller for the Detail View of the DevExpress.ExpressApp.Editors.CriteriaProvider type and access the CriteriaPropertyEditor.Control property.
Syntax Limitations in ASP.NET Core Blazor and Windows Forms Criteria Property Editors
The tree-like criteria construction in Criteria Property Editors does not support advanced syntaxes, such as:
- Function Criteria Operators
- Object Parameters
- Current Object Parameter in XPO applications
- Free Joins
If a criteria should contain such elements, users can switch to the Text tab and type in the expression. XAF validates the expressions on the server side and applies the filter.
ASP.NET Web Forms
Each ASP.NET Web Forms Property Editor includes controls that display a property in a Detail View in View and Edit mode.
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 Forms 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 Web Forms 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 Web Forms 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 Web Forms application, lookup property editors are represented by combo boxes, by default. Currently, you cannot use a complex lookup editor within the ASP.NET Web Forms 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 Web Forms Criteria Property Editors, certain Function Criteria Operators can be used in the Text tab only.