Search plug-in development

Search is a core part of DataTables as it allows the end user to very quickly find the data that they are looking for in a table. By default DataTables presents a text based global search for rapid searching of all information in the table. There are also the search() and column().search() API methods which provide the ability to perform programmatic global and column based search.

These built in search methods are text based and simply search for the input string in the table's data - there is little "intelligence" in how the search is performed (for example a mistake in the spelling of a search term will cause an unexpected result set to be returned).

The custom search options in DataTables provide the ability to extend the search abilities of any DataTable using virtually any logic you wish to apply to the data set. This is done by simply providing a search function that is called by DataTables for each row in the table whenever it needs to search the data. The search function must return true or false to indicate if the row in question should be included in the result set or not.

Plug-in structure

Plug-in search functions for DataTables should be attached to the $.fn.dataTable.ext.search array.

Inputs

The function takes five input parameters:

  1. object - DataTables settings object (see settings()).
  2. array - Array of the search data for the row. The array has one element for each column in the table.
  3. integer - The index for the row in question (see row().index()).
  4. object or array - The original data source for the row. This will be the array or object that was given to DataTables as the data source for the row.
  5. integer - Search counter. This is the loop index that DataTables uses internally to loop over the rows in the table. This is likely to be most useful when it is 0 which indicates that a new search is occurring and any cached search values could be updated.

It is important to note the difference between parameters 2 and 4 as they are potentially similar and can carry the same data. The array given as the second parameter is the search data for the row, while the fourth parameter is the original data object for the row. The difference is important for if you are using orthogonal data or objects as a data source.

Return

The plug-in search function should return a boolean value:

  • true - The row should be included in the search results
  • false - The row should be removed from the search results

Examples

The following example shows a range search taking data from two input elements (#min and #max) into which an end user would enter numeric data to search the table. Some logic operation is performed (in this case a numeric range check) and the boolean value is returned.

$.fn.dataTable.ext.search.push(
    function( settings, searchData, index, rowData, counter ) {
        var min = parseInt( $('#min').val(), 10 );
        var max = parseInt( $('#max').val(), 10 );
        var age = parseFloat( searchData[3] ) || 0; // using the data from the 4th column
 
        if ( ( isNaN( min ) && isNaN( max ) ) ||
             ( isNaN( min ) && age <= max ) ||
             ( min <= age   && isNaN( max ) ) ||
             ( min <= age   && age <= max ) )
        {
            return true;
        }
        return false;
    }
);

This example can be viewed in the DataTables examples section.

The following example shows how the previous search plugin example can be set to only apply to a specific DataTable by checking that the id of the table is as expected.

$.fn.dataTable.ext.search.push(
    function( settings, searchData, index, rowData, counter ) {
        if (settings.nTable.id !== 'myTarget'){
            return true;
        }

        var min = parseInt( $('#min').val(), 10 );
        var max = parseInt( $('#max').val(), 10 );
        var age = parseFloat( searchData[3] ) || 0; // using the data from the 4th column
 
        if ( ( isNaN( min ) && isNaN( max ) ) ||
             ( isNaN( min ) && age <= max ) ||
             ( min <= age   && isNaN( max ) ) ||
             ( min <= age   && age <= max ) )
        {
            return true;
        }
        return false;
    }
);

This is particularly useful when working with searchPanes. SearchPanes uses DataTables to display the options to the user, therefore any search plug-in that is applied generally to DataTables will also be applied to SearchPanes. This can often result in SearchPanes displaying no options to the user and is best avoided.