Skip to end of metadata
Go to start of metadata

UXQueryBuilder is an advanced data filtering control for Silverlight and WPF that allows user to visually build complex filter definitions. Designed with a sleek user interface, UXQueryBuilder lets users easily understand complex condition hierarchy and allow users to intuitively interact with each condition. Comes with full MVVM support and integration with all ClientUI data controls, adding the query builder functionality to your business applications is truly a breeze.

On this page:

Understanding UXQueryBuilder

The QueryDescriptor class provides powerful and flexible creation of data filters through the use of CompositeFilterDescriptor or CompositeFilterDescription. Consider the following code that represents a composite nested filters:


As the hierarchy of composite filters gets more complex, it will be significantly more difficult to maintain the codes or manipulate the composite filters in an intuitive manner during runtime. Compare the same code used to produce the visual representation of the filters using UXQueryBuilder:

UXQueryBuilder provides graphical representation and ultimate ease-of-use to interact with complex filters through a sleek and intuitive user interface. UXQueryBuilder serves as a client-side control that translates complex queries in the form of a visual representation and sends the designated filters to QueryDescriptor without writing any code. UXQueryBuilder is a fully customizable query editor which supports industry-standard WCF RIA and DevForce data sources.

Using UXQueryBuilder

This section provides a quick start on how to use UXQueryBuilder in the simplest scenario. To learn more about the user interface of UXQueryBuilder, see UI Highlights section below.

Server and Client Side Operation

UXQueryBuilder is designed to be able to handle both server and client side operations. The server side operation takes advantage of QueryDescriptor class while the client side operation takes advantage of the PagedCollectionView.

For more information on how to configure UXQueryBuilder to handle server-side operation, see How-to: Use UXQueryBuilder for server side operation. Also, to configure UXQueryBuilder to handle client-side operation, see How-to: Use UXQueryBuilder for client side operation.

Customizing UXQueryBuilder

There are three main parts in UXQueryBuilder: PropertyName, FilterOperator, and Value. The following section explains in details about the approaches used to customize each of these parts and suit UXQueryBuilder to your business model.

Listing Properties

Listing properties in property name in UXQueryBuilder can be done in two ways: using ObjectType or FilterPropertiesSource.

Using ObjectType

ObjectType provides a way to list properties by specifying the type of the model directly into UXQueryBuilder .

Take the following object model as an example.



The DisplayAttribute determines the display name of the property. If DisplayAttribute does not exist, then the property name will be listed as display name. Bind the object model to the ObjectType property of UXQueryBuilder. The ObjectType takes the Type property of the object model.



Using FilterPropertiesSource

You can also achieve the same result by binding an IEnumerable<CustomClass> to FilterPropertiesSource property of UXQueryBuilder in the view model and providing the respective member path in the view.


Customizing Property Generation and Editors

UXQueryBuilder allows room for further customization for generation of property names through the use of IncludeNavigationProperties and PropertyListMode properties. These properties give developers refined control over UXQueryBuilder property generation.

Include Navigation Properties

The IncludeNavigationProperties property enables UXQueryBuilder to list nested navigation properties in the object model. You can enable it by setting IncludeNavigationProperties to true.

Using ObjectType

Using the previous object model:


Using FilterPropertiesSource


To use navigation properties in conjunction with FilterPropertiesSource, you need to specify the ParentNameMemberPath.


Property List Mode

PropertyListMode allows UXQueryBuilder to generate properties based on the FilterMemberAttributeIgnoreFilterMemberAttribute, DataMemberAttribute and IgnoreDataMemberAtrtibutePropertyListMode consists of three modes: All, FilterMemberOnly, and FilterMemberAndDataMember. You can specify which properties not to be included during property generation by utilizing the IgnoreFilterMemberAttribute or IgnoreDataMemberAttribute and set the PropertyListMode accordingly.


By setting PropertyListMode to PropertyListMode.AllUXQueryBuilder will list all properties related to the object model. However, this may cause UXQueryBuilder to list unwanted properties.


Setting PropertyListMode to PropertyListMode.FilterMemberOnly will cause UXQueryBuilder to list all properties with the FilterMemberAttribute.


UXQueryBuilder will list all properties with either FilterMemberAttribute or DataMemberAttribute when PropertyListMode is set to PropertyListMode.FilterMemberAndDataMember.

Using ObjectType

You can customize which properties will be listed by specifying FilterMemberAttribute as follows:


Using FilterPropertiesSource

FilterPropertiesSource is not affected by PropertyListMode. Simply do not include unwanted properties in the view model.

Filter Operator Customization

This section elaborates how developers can customize the filter operator generated by the selected property.

Default Operators

By default, UXQueryBuilder provides predefined operators for common property types.

Numeric types and DateTimeIsEqualTo, IsGreaterThanIsGreaterThanOrEqualTo, IsLessThanIsLessThanOrEqualTo, IsNotEqualTo.

String type: Contains, DoesNotContainEndsWith, IsContainedInIsEqualTo, StartsWithIsNullOrEmpty.

Other types: IsEqualTo, IsNotEqualTo.

Exclude Operator

UXQueryBuilder provides the option for developers to include a specific set of filter operators by excluding undesired filter operators. The following example will demonstrate how to exclude specific set of operators in both ObjectType and FilterPropertiesSource scenario.

Using ObjectType


You can specify multiple ExcludeFilterOperator by using the ^ (caret) sign.

Using FilterPropertiesSource

Currently, ExcludeFilterOperator is not available in FilterPropertiesSource.

Preferred Filter Operator

PreferredFilterOperator is used to auto-select a filter operator when a property is selected, giving a more intuitive experience in using the UXQueryBuilder.

Using ObjectType


Using FilterPropertiesSource

Simply add ExcludeFilterOperator property in the your custom class and specify the PropertyPreferredFilterOperatorMemberPath in the view.


Value Customization

Default Editors

By default, UXQueryBuilder provides four value editors for common data types as follows:

String/Other : UXTextBox

DateTime : UXDateTimePicker

Boolean/Enum : UXComboBox

Numeric : UXCurrencyEditor

Data List Provider

DataListProvider provides a convenient way to enhance the filter experience by providing a predefined set of values to the value editor in the object model. Suppose the user would like to search for SupplierID. It will be quite an unpleasant experience if the user would have to type the ID of the Supplier to execute the filter process. In this scenario, DataListProvider can be used to enhance the filter experience.


The following illustration shows the value editor automatically changed to UXComboBox when DataListProvider is used. When users select a value from the combobox control, the actual value (usually the unique ID) of the selection will be set to the filter descriptor behind the scene. This powerful feature is particularly useful to address common business applications such as in master-detail scenarios.

Customizing Default Editors

Using Explicit Styles

You can customize the default editors provided by UXQueryBuilder by specifying explicit styles and target the appropriate value editor.


Using Editor Definitions

The following snippet code shows how to customize the default editor using EditorDefinition.


Using Editor Selector

IEditorSelector provides a way to customize the default editor programmatically.


Overriding Default Editors

Using Editor Template

You can use DataTemplate to override the default value editor.


Using Editor Definitions

You can use EditorDefinition to override the default editor.

Example Title

Using Editor Selector

You can also override the default value editors programmatically using IEditorSelector.


Using Editor Type

You can also specify EditorType in the model to override the default editor.


UX Features

Enable Nested Filter

When EnableNestedFilter property is set to true, UXQueryBuilder enables the creation of nested filters. You can set EnableNestedFilter to false if you do not need the user to create complex nested filters. EnableNestedFilter will not have any effect if there is only one filter item in the filter collection.

Predefined Composite Filter

UXQueryBuilder enables predefined composite filter to take effect upon first load by simply creating a composite filter and bind the composite filter to the CompositeFilter property.


Save / Load Filters

UXQueryBuilder features save and loading of filters for future reusability. After creating a complex set of filters, users are able to save the filter into industry-standard JSON (JavaScript Object Notation) format and load them. This feature is not enabled by default. For example, you can create a UXButton with command that calls UXQueryBuilderCommands.Save or UXQueryBuilderCommands.Load accordingly.


Edit Mouse Gestures

EditMouseGesture property defines the mouse gesture needed for UXQueryBuilder to enter editing mode, consisting of SingleClick, DoubleClick and SecondClick.


Localization is available to UXQueryBuilder by utilizing the ResourceOverride and overriding each string, shown as follows:


UI Highlights

The following section highlights the UI elements in UXQueryBuilder.

If there is only one item, UXQueryBuilder will hide the composite logical operator button, as this element is considered to have no use when there is not at least two filter items.

Add Condition

When the Add Condition button is clicked, UXQueryBuilder will smooth animate to show the composite logical operator button, as well as adding one more item to the filter items collection. You can also use Ctrl+Shift+A to add condition.

Enable Nested Filter

If EnableNestedFilter is set to true and there is more than one filter item, then Add Nested Condition button will appear. You cannot add a nested filter when there is only one item in the collection.

Add Nested Condition

If the Add Group button is pressed, UXQueryBuilder will convert the current filter item to a composite filter, retaining the previous filter.

The nested condition will also be added with a smooth animation.

Composite Logical Operator

The composite logical operator is used to change the logical operator for the currently selected composite filter. You can also Add Condition, Add Group and Delete inside the dropdown.


When Delete button is pressed, UXQueryBuilder will delete the current filter item. You can also press Delete on the keyboard to delete the filter item.

If there is only one filter item, UXQueryBuilder will revert to its original state, with composite logical operator button hidden.


When Clear button is pressed, UXQueryBuilder will automatically clear all filter items and restore UXQueryBuilder to initial state.


When Filter button is pressed, the filter process takes place. UXQueryBuilder automatically validates when either PropertyName or Value is not specified. You can also use Shift+Enter to execute the filter process anytime.

If all filters are considered valid, then the filter process will continue.

Keyboard Navigation

Despite its nature to handle complex queries, UXQueryBuilder is designed to give an intuitive keyboard navigation experience.

Tab Cycles

The following figure will illustrate how Tab cycles is handle in UXQueryBuilder.

Filter Items Cycles

Pressing Up and Down key when focused on a filter item will intuitively cycle between filter items.

Shortcut Keys

Pressing Delete will delete the current filter item. Pressing Ctrl+Shift+A will either Add Condition (when focused to an item) or Add Nested Condition (when focused to composite logical operator button or add condition button).


Related Topics