Filtering Data

The library provides a special extension for filtering dhtmlxGrid data on the client side (for server-side filtering, use the dhtmlxConnector library).

Filters in the header

You can define a built-in auto filter in the header or in the footer of a column. The following types of filters are available:

  • text_filter - a text filter. Retrieves values which contain mask defined through text field.
  • select_filter - a select filter. Retrieves values which contain mask defined through dropdown list of possible values.
  • combo_filter - a filter based on the dhtmlxCombo component. Retrieves values which contain mask defined through combo box.
  • text_search - an input box. Doesn't filter the grid but moves the selection to the nearest row containing a text input.
  • numeric_filter - a text filter that allows using comparison operators in it. Retrieves values which contain mask defined through text field.
    The possible comparison operators are:
    • '=' - equal to;
    • '>' - greater than;
    • '<' - less than;
    • '?' - less or equal to;
    • '>=' - greater or equal to;
    • 'n1..n2' - a range of values.

Built-in filters are set by the method attachHeader(). Note, when specifying a filter you should write '#' before its name.

General specifying auto filters for columns

mygrid = new dhtmlXGridObject('gridbox');
 
mygrid.setHeader("Book Title,Author,Price");
mygrid.attachHeader("#text_filter, #select_filter,#numeric_filter");
...

In order not to specify a filter for some of columns use the null value:

Specifying an auto filter for a particular column of the header

mygrid.setHeader("Book Title,Author,Price");
mygrid.attachHeader("#text_filter, , ,");

Note, each time you start typing text in such a filter, dhtmlxGrid invokes the filterByAll() method. Each time the method is called, all data is re-filtered (previous results aren't preserved).

AND logic

When you specify filters in several columns, dhtmlxGrid applies the AND logic to them by default, i.e. the grid will display just the records that meet all criteria at once.

OR logic

In case you want to apply OR logic (display records that meet at least one of the criteria) you should redefine the filterByAll() method. For example, it can look like this:

Implementing OR logic for filters

mygrid = new dhtmlXGridObject('gridbox');
 
mygrid.setHeader("Book Title,Released");
mygrid.attachHeader("#text_filter, #select_filter");
mygrid.setColumnIds("title,year");
...
mygrid.init();
 
mygrid.filterByAll=function(){
    //gets filter values
        var title = this.getFilterElement(0).value;
        var year = this.getFilterElement(1).value;
    //unfilters if values were not selected
        if (!title  && !year) return this.filter();
    //filters using OR logic
        this.filter(function(data){
            if (data == year) return true;
            if (data!=-1) return true;
            return false;
        });
};

In order to programmatically simulate entering specific data in a header filter you can use the following technique:

var inp = mygrid.getFilterElement(3); // '3'-index of the column (zero-based numbering)
inp.value = 12.99; // inputted value
mygrid.filterByAll();// invokes re-filtering

HTML input as a filter for the grid

An HTML input can act as an auto filter for a specific column of the grid. It's achieved with the help of the makeFilter() method.

In addition to 'input', you can use 'select' and 'div' HTML elements.

'input' and 'select' serve as text and select filters.
When you specify the id of the 'div' element, the grid creates a combo filter based on that 'div' and populated with unique values from the specified column. Note, to use 'div' as a filter you should include on the page the dhtmlxcombo.js file.

In case of the auto filter, filtering will be invoked automatically as soon as you start typing something in the input.

<input type="text" id="textFilter"></input>
<select type="text" id="selectFilter"></select>
 
<script>
mygrid = new dhtmlXGridObject('gridbox');
mygrid.setHeader("Book Title,Author,Price");
...
mygrid.init();
 
mygrid.makeFilter("textFilter",0);//params:input's id, column's index(0-based numbering)
//items for options list added automatically according to column the control assigned to
mygrid.makeFilter("selectFilter",1);
</script>

Programmatic Filtering

If you want to invoke filtering programmatically, you may use 2 methods:

  • filterBy() - filters the specified column by some value (string or function);
  • filterByAll() - invokes auto filters (defined in the header of set by the method makeFilter()).

Method filterBy()

The method filterBy(column, value) allows you to filter the specific column of the grid by the specified value:

The second parameter can be both a string and a function.

mygrid = new dhtmlXGridObject('gridbox');
mygrid.setHeader("Sales, Book Title,Author");
...
mygrid.filterBy(1, "John Grisham"); // filters the 2nd column by value "John Grisham"
mygrid.filterBy(0,function(a){ return (a<500);}) // true/false - shows/hides a row

Note, every next call of the filterBy() method will reset the grid to its initial state and filter it from the start. To specify several rules (of AND logic) for one and the same column you should specify an additional parameter in the method.

Programmatic filtering of the column by several criteria

mygrid = new dhtmlXGridObject('gridbox');
mygrid.setHeader("Sales, Book Title,Author");
...
 
mygrid.filterBy(3,"John Grisham");// filters the 2nd column by value "John Grisham"
mygrid.filterBy(3,"Stephen King",true);//each next method's call has 3rd param - true

Method filterByAll()

The method allows you to programmatically invoke filtering by auto filters.

You can use this method to redefine the default logic of the built-in filters. For example, to define OR logic or simulate entering some data in the filter.

Redefining default filter logic

Any filter you assign to the grid (both by adding it to the header and by creating through the makeFilter() function) can use a custom logic instead of the default one.

To change the filtering logic of a filter assigned to the grid you should redefine its _filter function as in:

grid.getFilterElement(col_index)._filter = function(){
     // your custom logic
}

For example, you can use the following definition to create a filter (based on text_filter) that makes a search in all columns of the grid:

mygrid.getFilterElement(0)._filter = function(){
    var input = this.value; // gets the text of the filter input
    return function(value, id){
        for(var i=0;i<mygrid.getColumnsNum();i++){ // iterating through the columns
            var val=mygrid.cells(id,i).getValue() // gets the value of the current cell
            // checks if the value of a cell has the text from the filter 
            if (val.toLowerCase().indexOf(input.toLowerCase())!==-1){ 
                return true;
            }
        }
        return false;
    }
}

Filtering events

The library provides the following filtering-related events:

  • onFilterStart - fires when filtering is triggered in some input (doesn't occur for direct filterBy() calls);
  • onFilterEnd - fires after filtering is finished (doesn't occur for direct filterBy() calls);
  • onCollectValues - fires when the select filter collects values for the options list.

Adding/deleting rows in the filtered grid

The grid doesn't preserve row changes (adding, deleting), which are made when the grid is filtered. After resetting back to the not-filtered state, the grid restores deleted rows and removes the newly created ones. To work around the issue you can use the following order of actions:

  1. Unfilter the grid;
  2. Add/remove the desired rows;
  3. Filter the grid back.

Adding rows in the filtered grid

mygrid.filterBy(0,""); //unfilters the grid
mygrid._f_rowsBuffer = null; //clears the cache
 
grid.addRow(...);// adds some row
 
grid.filterByAll();// filters the grid back

Related sample:  Filtering

Back to top