DHTMLX Docs & Samples Explorer

Index
dhtmlxgrid

## Filtering in Grid

To activate filtering functionality, the user should include dhtmlxgrid_filter.js into the page.

Starting from dhtmlxGrid 1.5, the grid supports filtering API that works in the normal, paging, and smart rendering modes (filtering in smart rendering mode is the fastest one, that's why it is recommended to be used with relatively big datasets).

### Creating Filter for Grid

The user can define any textbox or selectbox as the filter for a grid column. The following code snippet shows how to add a textbox as a filter for the first column of the grid:

        <input type="text" id="textobject">
        <script>
            grid.makeFilter("textobject",0);

The parameters of makeFilter() method are:

- id - {string|object} input id or input html object;
- column - {number} index of the column.

        <input id='some_el' type='text'>
            //....
            grid.makeFilter("some_el",index);    // will create a text filter linked to the specified column in the grid
        <select id='some_el' type='text'></select> // the options of select will be added automatically
            //....
            grid.makeFilter("some_el",index);    // will create a select filter linked to the specified column in the grid

If the user specifies id of the <div> element as the first parameter, the grid will create a combox based on that <div> and make it filter of autocomplete type with values taken from the specified column. ( dhtmlxcombo.js required )

### Adding Filters into Grid Header

Since v1.5, there is the ability to add predefined types of filters into the grid header. See Adding Filters to Grid Header section. Built-in filters are grouped by AND logic in such a way that if the user creates filters for 3 columns, the data will be shown only if it is accepted by all 3 sorting criteria.

### Filtering API

The third way to create some filtering is to use API calls. The grid provides a simple way to filter the grid by any column:

            grid.filterBy(column,value);

- column - zero based column index;
- value - value by which the column will be filtered.

The user can apply simple values for filtering:

            grid.filterBy(1,"alf");

Or complex JavaScript rules:

            grid.filterBy(1,function(data){
                return   data.toString().indexOf("alf")!=-1;  // true - show the related row , false - hide the related row
            });

Every next call of filterBy() will reset the grid to its initial state and filter it from the start. There is the possibility to use the following additional parameters here:

            grid.filterBy(1,"alf");
            grid.filterBy(2,"Omega"); // the first rule will be ignored

            grid.filterBy(1,"alf");
            grid.filterBy(2,"Omega",true); // the grid will be filtered by both rules

There is no way to use several filters with OR logic between them.

There is also the possibility to force grid filtering by registered inputs (created by # starting shortcuts, or by makeFilter() method):

            grid.filterByAll();

### Filtering by Many Values

There is the possibility to filter the grid using values from different controls. This can be done in the following way:

        <input type="text" id="textobject1">
        <input type="text" id="textobject2">
        <button type="button" onclick="doFilter()">Filter</button>
        <script>
            function doFilter(){
                grid.filterBy(0,document.getElementById("textobject1").value);
                grid.filterBy(0,document.getElementById("textobject2").value, true); }

As it is seen, filterBy() method is called passing there values from different controls.

Note: all calls starting from the second one should have the third argument set to true, which means this filter parameter should be added to exiting parameters.

### Additonal Filtering API

The following API methods are rarely used, but they may be also useful in some situation:

            grid.refreshFilters(); // refresh lists of values in all the filters created by shortcuts or by makeFilter() calls
            grid.collectValues(index); // return alphabetically sorted list of unique values in the column defined by index
            grid.getFilterElement(index); //return input object of filter linked to column in question

Note, getFilterElement() method works only for filter-elements, so it will not work for #text_search.

### Filtering Related Events

onFilterStart - occurs when filtering triggered in some input, not occurs for direct filterBy calls, event can be blocked by returning false from event handler.

- array of column indexes;
- array of filtering values.

onFilterEnd - occurs after filtering finished, not occurs for direct filterBy calls:

- array of linked inputs.

onCollectValues - event occurs when select filter collect values for the option list, event can be used to customize list of options, if custom code attached to event, returns array of data - it will be used for options generation, instead of actual data in grid:

- index of column.

         grid.attachEvent("onCollectValues",function(ind){
                if (ind == 2 ) return ["one","two","three"];
                return true;
         })

### Adding|Deleting Rows in Filtering Mode

Grid will not preserve row changes ( adding , deleting ) , which was done when grid was in filtered state. After resetting back to not-filtered state, grid will restore deleted rows and remove newly created ones. To work around issue you can use next order or actions:

- unfilter grid;
- add|delete row;
- reset filter back.

         grid.filterBy(0,""); //unfilter
         grid._f_rowsBuffer = null; //clear cache

         grid.addRow(...);

         grid.filterByAll();  //reset filters back