Filtering (igGrid)

Overview

The Filtering feature of the igGrid allows users to do Excel-style filtering of data.

Note: Filtering is implemented as a jQuery UI widget which follows the lifecycle of any jQuery UI widget.

In this topic

This topic contains the following sections:

• Filtering Persistence
• Filtering Modes
• Configuration Considerations
• Enabling Filtering
• Remote Filtering
• Column Settings
• Client-Side events
• API Usage
• Default Conditions List
• List of Filtering Options (Properties)
• Custom Filtering Conditions
• Filtering CSS Classes
• Keyboard Interactions
• Breaking Changes
• Related Content

Filtering Persistence

Persisting Filtering between igGrid re-bindings is made easy in version 14.1 and in fact replaces the previous default behavior.

Note Filtering persistence is true by default. This is a breaking change.

When you enable igGridFiltering you are already using it in a persist mode. This means that after explicitly calls of dataBind(), that persistence is applied for UI and data source view (the filter editors are not cleared and the data source remains filtered)

Filtering persistence is implemented for igHierarchicalGrid too.

The following sample demonstrates the persistance capabilities of the Filtering feature.

If you would like to retain the previous behavior of filtering being cleared after user re-binds the igGrid, you can do this by disabling the feature through the persist option as shown in the code snippet below:

In JavaScript:

features: [
  {
     name: "Filtering",
     persist: false
  }
]

Filtering Modes

The mode option accepts two value values: advanced or simple. When the simple filtering mode is set, all filters are rendered for every column header, below the respective column header cell. When advanced filtering is configured, then an advanced filtering button is rendered next to the column header text (default). Once the advanced button is clicked, the “advanced” filtering dialog appears where more complex filtering conditions are available to the user.

Configuration Considerations

• All filter row conditions are always combined using the “AND” operator.
• The advanced filtering dialog does expose the “AND” or “OR” operators in order to combine multiple filters.
• The advanced filter dialog also allows multiple filters to be set for a single column.
• The actual data filtering is performed solely through the igDataSource control.
• By default if no expression URL keys are set, an oData encoding is assumed – same as in the igDataSource filtering functionality.
• The filter row can be navigated with the keyboard using TAB / SHIFT and TAB.
• When the focus is on a filter dropdown, it can be opened with the ENTER key, and then filter dropdown items can be navigated with the UP and DOWN arrow keys.
• Whenever some other grid feature triggers a “UI dirty” event (for example when the page size is changed when paging is enabled), filtering automatically clears all of the UI presets, if they are different than the defaults.
• In order to have multiple filtering conditions configured for the same column, they should be added through the advanced filter dialog – when the filtering mode is set to advanced.
• Whenever advanced filtering is used, and a column is chosen from the first column (in an advanced dialog filter row), the second column with the conditions is automatically updated depending on the column type. Therefore if the column is a numeric column, only numeric conditions are listed, and so on. Further the third column editor is updated, so if it is a date column, a date picker is rendered instead of a regular input element.
• The filterDelay option combined with mode: “simple” can play an important role for making the end users’ work seamless. The greater the delay, the more time the end user can spend typing in the filter input before a filtering request is triggered.
• It is very important to set the correct column types when filtering is used. If they are not configured properly, some unexpected errors and behaviors may occur, for example when setting a numeric column to be of type “string”, or the reverse.
• Filtering can also be case sensitive, which can be turned on by setting the caseSensitive option to true. This options works only for local filtering.

You can get the current list of expression objects from the dataFiltering event arguments.

In JavaScript:

$(document).delegate("#grid1", "iggridfilteringdatafiltering", function (evt, ui) {
    var expressions = ui.expressions;
}

Figure 1: Simple Filtering (mode: “simple”)

Figure 2: Advanced Filtering (mode: “advanced”)

Figure 3: Advanced Filtering dialog

Figure 4: Filtering tooltips (mode: “advanced”)

Enabling Filtering

In order to get started with Filtering, you first need to include the necessary JavaScript and CSS dependencies. The easiest way to do that is to use the combined / minified version of the scripts and styles.

Listing 1: Necessary CSS and JavaScript references you need to include in your application

In HTML:

<link type="text/css" href="infragistics.theme.css" rel="stylesheet" />
<link type="text/css" href="infragistics.css" rel="stylesheet" />
<script type="text/javascript" src="jquery.min.js"></script>
<script type="text/javascript" src="jquery-ui.min.js"></script>
<script type="text/javascript" src="infragistics.core.js"></script>
<script type="text/javascript" src="infragistics.lob.js"></script>

Listing 2: Minimal set of CSS and JavaScript references (not minified and combined) – needed only for filtering

In HTML:

<script type="text/javascript" src="infragistics.util.js"></script>
<script type="text/javascript" src="infragistics.util.jquery.js"></script>
<script type="text/javascript" src="infragistics.dataSource.js"></script>
<script type="text/javascript" src="infragistics.ui.shared.js"></script>
<script type="text/javascript" src="infragistics.ui.popover.js"></script>
<script type="text/javascript" src="infragistics.ui.editors.js"></script>
<script type="text/javascript" src="infragistics.ui.grid.framework.js"></script>
<script type="text/javascript" src="infragistics.ui.grid.shared.js"></script>
<script type="text/javascript" src="infragistics.ui.grid.filtering.js"></script>

Listing 3 shows sample code used to configure grid filtering.

Listing 3: Sample grid code for filtering

In JavaScript:

//Basic filtering on client
$("#myGrid").igGrid({
    dataSource: "/GetCensusData/",
    columns: [
        { headerText: "State", key: "StateName" },
        { headerText: "Congressional District", key: "CongressionalDistrict" },
        { headerText: "Population", key: "TotalPopulation" }
    ]
    features:[
        {
            name: "Filtering",
            allowFiltering: true,
            caseSensitive: false,
            columnSettings: [
                {columnKey: "StateName", allowFiltering: false}
            ]
        }
    ]
});

Listing 4: Sample JSON response

In JavaScript:

[
   {"AverageFamilySize":3.36, "AverageHouseholdSize":2.91, "CongressionalDistrict":"14", "StateName": "Illinois", "TotalPopulation":720663},
   {"AverageFamilySize":3.00, "AverageHouseholdSize":2.43, "CongressionalDistrict":"15", "StateName": "Illinois", "TotalPopulation":595833},
   {"AverageFamilySize":3.16, "AverageHouseholdSize":2.67, "CongressionalDistrict":"16", "StateName": "Illinois", "TotalPopulation":691356}
]

Listing 5: HTML element required to instantiate the grid

In HTML:

<table id="myGrid"></table>

Running sample with advanced filtering

Listing 6: Razor or CSHTML markup to use with Ignite UI for MVC

In Razor:

@(Html.Infragistics().Grid(Model).ID("grid1").PrimaryKey("ProductID").Height("400px").Columns(column =>
    {
        column.For(x => x.ProductID).HeaderText("Product ID").DataType("number");
        column.For(x => x.Name).HeaderText("Product Name");
        column.For(x => x.ModifiedDate).HeaderText("Modified Date");
        column.For(x => x.ListPrice).HeaderText("List Price");
    }).Features(features => {
        features.Filtering().Mode(FilterMode.Advanced);
    })
    .DataSourceUrl(Url.Action("GridGetData"))
    .DataBind()
    .Render()
)

Remote Filtering

If filtering is configured to be remotely (ie: the type option is set to remote), the URL is automatically configured so that all filtering expressions are encoded automatically based on the end user actions (or based on the parameters passed, if programmatic filtering is performed). If no filterExprUrlKey is specified, oData URI conventions are automatically used in the encoding.

Note: For more information regarding oData URI conventions, please visit: http://www.odata.org/documentation/odata-version-2-0/uri-conventions/

Otherwise, the grid encodes filtering information in the following way (example):

http://<SERVER>/grid/GridGetData? filter(Name)=startsWith(a)&filter(ModifiedDate)=today()&filterLogic=AND

When Ignite UI for MVC is used to bind to server-side data through LINQ (IQueryable), all filtering information that’s encoded in the URL is automatically translated to LINQ expression clauses (Where clause), so you do not need to do anything additional in order to filter the data.

Column Settings

Each column setting can contain custom options that apply for a specific column, that is specified by the columnKey property. Table 1 shows all available properties that can be set in a single object that is part of the columnSettings option.

Note: The columnSettings option is an array of objects listed in Table 1.

Table 1: igGridFiltering columnSettings

Listing 7: Example usage of columnSettings

In JavaScript:

$("#grid1").igGrid({
    columns: [
        { headerText: "Product ID", key: "ProductID", dataType: "number" },
        { headerText: "Product Name", key: "Name", dataType: "string" },
        { headerText: "Product Number", key: "ProductNumber", dataType: "string" },
    ],
    width: '500px',
    dataSource: products,
    features: [
        {
            name: 'Filtering',
            columnSettings: [
                {columnKey: 'ProductID', condition: "startsWith" }
            ]
        }
    ]
});

Client-Side events

You can bind to Filtering client-side events in two ways, which are described in Listing 8 and Listing 9, respectively. If you would like to bind using the approach described in Listing 8, you can use the jQuery on() method.

Listing 8: Binding to client-side events from anywhere in your application

In JavaScript:

$("#grid1").on("iggridfilteringdatafiltered", handler);

Listing 9: Binding to client-side events by specifying the event name as an option when you initialize the filtering feature (case sensitive)

In JavaScript:

    $(function () {
        $("#grid1").igGrid({
            columns: [
                { headerText: "Product ID", key: "ProductID", dataType: "number" },
                { headerText: "Product Name", key: "Name", dataType: "string" },
                { headerText: "Product Number", key: "ProductNumber", dataType: "string" },
            ],
            width: '500px',
            dataSource: products,
            features: [
                {
                    name: 'Filtering',
                    dataFiltering: handler
                }
            ]
        });
    });

    //Handler code
    function handler(event, args) {

    }

Note: All ‘ing’ events are cancellable. In order to cancel an ‘ing’ event, its respective event handler must return false.

Table 2: Filtering Client-side events

API Usage

In order to filter the grid programmatically, you need to call the filter() function on the igGridFiltering widget. The filter function is defined in the following way:

filter(expressions, updateUI)

The expressions argument is an array of expression objects. Listing 10 gives an overview of the structure of each expression object. The updateUI argument is optional and it can be set explicitly to false so that the UI is not updated when the grid is filtered programmatically.

Listing 10: Filtering expression object structure

In JavaScript:

{
    expr: <filter expression string>,
    cond: [<filtering condition>](#default-conditions-list),
    fieldName: [<column key>](https://www.igniteui.com/help/api/2024.1/ui.iggrid#options:columns.key)
}

Listing 11 and Listing 12 show examples of using the filter() function off the igGridFiltering widget.

Listing 11: Filter by ProductID = 1

In JavaScript:

$("#grid1").igGridFiltering('filter', ([{ fieldName: "ProductID", expr: 1, cond: "equals"}]));

Listing 12: Filter by ProductID = 1 and ProductName startsWith “a”:

In JavaScript:

$("#grid1").igGridFiltering('filter', ([{ fieldName: "ProductID", expr: 1, cond: "equals"}, {fieldName: "ProductName", expr: "a", cond: "startsWith"} ]));

Listing 13: Retrieving the applied filtering expressions

In JavaScript:

var expressions = $('#grid1').data('igGrid').dataSource.settings.filtering.expressions;

Default Conditions List

The following conditions (grouped by data type) are available to perform filtering on the grid:

• String
  • startsWith
  • endsWith
  • contains
  • doesNotContain
  • equals
  • doesNotEqual
  • null
  • notNull
  • empty
  • notEmpty
• Number
  • equals
  • doesNotEqual
  • greaterThan
  • lessThan
  • greaterThanOrEqualTo
  • lessThanOrEqualTo
  • null
  • notNull
  • empty
  • notEmpty
• Boolean
  • true
  • false
  • null
  • notNull
  • empty
  • notEmpty
• Date
  • on
  • notOn
  • after
  • before
  • today
  • yesterday
  • thisMonth
  • lastMonth
  • nextMonth
  • thisYear
  • lastYear
  • nextYear
  • null
  • notNull
  • empty
  • notEmpty
• Time
  • at
  • notAt
  • before
  • after
  • atBefore
  • atAfter
• Object
  • null
  • notNull
  • empty
  • notEmpty

List of Filtering Options (Properties)

Option and default value shows in brackets

Custom Filtering Conditions

The Filtering feature when in local mode (type="local") allows the user to define custom filtering conditions per column. The custom conditions are appended to the conditions list (following the default conditions list based on the column data type) for the specific column and allow you to specify a custom comparer filtering function to process the data. The condition needs to be defined in the column settings for the related column via the customConditions option. The assigned value should be an object, where each property name represents an unique condition key and the value represents the custom condition's declaration.

There are additional options that further affect the behavior and visualization of the conditions:

• requireExpr - specifies whether this condition requires the user to input a filtering expression or not.
• labelText - specifies the label text that will appear in the column's condition dropdown.
• expressionText - specifies the text that will display in the editor if requireExpr is false and the condition is selected from the dropdown.
• filterImgIcon - specifies the css class applied to the dropdown item when in simple filtering mode.

• filterFunc - specifies the custom comparing filter function(or name of a function) that will be used when the condition is applied.

  Listing 14: Example usage of custom conditions with running sample

In JavaScript:

$("#grid1").igGrid({
   columns: [
                { headerText: "Employee ID", key: "EmployeeID", dataType: "string", hidden: true },
                { headerText: "First Name", key: "FirstName", dataType: "string" },
                { headerText: "Last Name", key: "LastName", dataType: "string" },
                { headerText: "Register Date", key: "RegistererDate", dataType: "date" },
                { headerText: "Country", key: "Country", dataType: "string" },
                { headerText: "Age", key: "Age", dataType: "number" },
                { headerText: "Is Active", key: "IsActive", dataType: "bool" }
            ],
    dataSource: employees,
    width: '500px',
    dataSource: products,
    features: [
        {
            name: 'Filtering',
            columnSettings: [
               {
                     columnKey: "Country",
                     customConditions: {
                        USA: {
                             labelText: 'USA',
                             expressionText: "USA",
                             filterFunc: function(value, expression, dataType, ignoreCase, preciseDateFormat) {  return value === "USA";}
                        },
                        Canada:{
                              labelText: 'Canada',
                              expressionText: "Canada",
                              filterFunc: function(value, expression, dataType, ignoreCase, preciseDateFormat) {  return value === "Canada";}
                        }
                     }
                }
            ]
        }
    ]
});

Demo:

Filtering CSS Classes

Keyboard Interactions

When simple filtering mode is enabled the following keyboard interactions are available.

When focus is on the grid:

• TAB: Can move focus between the focusable elements of the filtering UI: filtering buttons and editors. When focus is on the filtering button:
• ENTER/SPACE: Opens the filtering conditions drop down. You can then navigate the available items in the drop down with the UP/DOWN keys.
• UP/DOWN: Changes the active filtering condition for the cell.
• TAB: Moves focus to the filtering editor element.

When advanced filtering mode is enabled the following keyboard interactions are available.

When focus is on the grid:

• TAB: Moves focus to the first filter button. When focus is on the filter buttons:
• ENTER: Opens the advanced filter dialog.
• TAB: Moves focus to the next filter button or the next focusable element on the page.

When focus is on the advanced filter dialog:

• TAB: Moves focus between the elements of the dialog.
• ESCAPE: Closes the dialog.

Note: There is a difference between the drop-down for selecting the column and the condition drop-down. One is an igCombo, the other a standard < select > element. The < select > element opens on SPACE/ENTER and its content can be navigated with the UP/DOWN keys and selected with ENTER. The igCombo cannot be opened with enter/space. Its values can be changed directly using the UP/DOWN keys.

Breaking Changes

• Behavioral changes

The default filtering condition (which depends on the column data type) or the one explicitly set via the condition option in the Filtering`s columnSettings is now selected in the drop-down conditions list. The only exceptions are the columns, which default (or explicitly set) condition does not require user's input such as Boolean columns, date columns with conditions "Today", "Yesterday", "This month" etc. In the later the end user should explicitly select them so that they get applied.

• DOM structure changes

The DOM structure for filtering drop down conditions list has changed. In versions prior to 18.2 there was a separate div element rendered for each column's conditions list drop down. With performance in mind, from version 18.2 on, only one div element will be rendered for all columns.

Related Content

Topics

• igGrid Overview

Samples

• Filtering