Custom Search Functions and Panes

Custom search functions are one of the key features of SearchPanes. They allow the programmer to define their own options to be in the SearchPanes.

Note: Custom search functions are not compatible with stateSave. This is because the state is saved as a JSON object and functions cannot be represented in JSON.

Writing a Custom Function

Custom search functions must be defined within an object in the columns.searchPanes.options array. When defining a custom searching function there are two properties which need to be defined:

• label - how you want the option displayed in the pane.
• value - your custom function.

The custom searching functions take two parameters

• rowData - the data for the row which is currently being compared in the search function.
• rowIdx - the index of the row which is currently being compared in the search function.

The function should return true if the row is to be included in the result set and false if it is not.

A very basic example is shown below, assuming column 0 is an age column of type number.

$('myTable').DataTable( {
    searchPane: true,
    columnDefs:[
        {
            searchPanes:{
                options:[
                    {
                        label: 'Over 60',
                        value: function(rowData, rowIdx) {
                            return rowData[0] > 60;
                        }
                    }
                ]
            },
            targets: [0]
        }
    ]
})

These custom functions can produce much more complicated search functions as long as they return true if they are to be included and false if they are not. The example below will find all of the ages which are prime numbers and display them in the table.

$('myTable').DataTable( {
    searchPane: true,
    columnDefs:[
        {
            searchPanes:{
                options:[
                    {
                        label: 'Prime Ages',
                        value: function(rowData, rowIdx) {
                            let primeNumber = true;
                            for(let i = 2; i< Math.sqrt(rowData[0]); i++){
                                if(rowData[0] % i == 0){
                                    primeNumber = false;
                                    break;
                                }
                            }
                            return primeNumber && rowData[0] > 1;
                        }
                    }
                ]
            },
            targets[0]
        }
    ]
})

Defining Custom SearchPanes

It is also possible to define a pane that is not tied to a specific column. While technically it would be possible to search across multiple columns in one of the existing columns that is tied to a row, it seems neater to create another pane for them.

In order to do this we define an object within the searchPanes.panes array. This array holds an object for each pane to be created. For each of these objects there is a header property which holds the string which is to be set as the title of the pane. There is also a searchPanes property which in turn has an options property which holds custom searching functions as before. An example is shown below.

$('#myTable').DataTable( {
    searchPanes: {
        panes: [{
            header: 'custom',
            options: [{
                label: 'Accountants in Tokyo',
                value: function(rowData, rowIdx){
                    return rowData[2] === 'Accountant' && rowData[3] === 'Tokyo';
                }
            }]
        }]
    }
} );

The above example searches the table for people whose position in the company is Accountant and are based in Tokyo. As detailed above, adding more objects to the options array will add more options to the new pane.

The functions context is an API instance of the host DataTable. This means that from within the custom search functions it is possible to call this.rows().data() and other API methods.