Extension for JQuery plug-in DataTables adding drop down filter elements for selected columns
Adds a dropDown element for selected columns to a datatable allowing the user to filter the table to only show rows containing a certain value. e.g. in a list of employees to only show the ones that have an office in a certain city. The filter element extracts all unique values from a column and adds them sorted and stripped as options.
- Uses column header as default title, can be overridden with custom title
- CSS styles and/or CSS classes can be applied to each filter element
- Supports Bootstrap 3 and Boostrap 5 styling
- Supports server-side processing
Here is a screenshot showing how it looks like in action:
- Download
filterDropDown.min.jsto your website. You find the latest version in thejsfolder. - Include
filterDropDown.min.jsinto your html file. It must be after the inclusion of dataTables JS - Add a filterDropDown section in the DataTables initialization object
<!-- This is your HTML file -->
<head>
<!-- all your includes for Jquery, Bootstrap (optionally), Datatables above -->
<!-- Now we include the actual plugin -->
<script src="filterDropDown.min.js"></script>
<!-- Finally you define your DataTables table and include a filterDropDown section in the initialization array -->
<script>
$(document).ready(function() {
$('#example').DataTable({
filterDropDown: {
columns: [
idx: 3
]
}
} );
} );
</script>
</head>Also see folder examples for complete examples including both vanilla html and Bootstrap.
The extension will generate classes for each filter that you can use to apply CSS styling. There are two classes for each table:
[tableId]_filterWrapper: this class is assigned to the div that encapsulated the whole filter element and the label. Use this to apply styles to the label.[tableId]_filterSelect: this class is assigned to each select element
The class names are generated based on the table ID. So e.g. if the table has the ID example, then the wrapper class will be called example_filterWrapper.
DataTables can use to server-side processing, and filterDropDown also supports it.
To use server-side processing your app will needs two things:
- An endpoint for filterDropDown that provides the necessary data, similar to the endpoint needed to power DataTables server-side processing feature.
- The endpoint for DataTables must support the feature of searching columns with regex (
columns[{num}][search][regex])
To enable server-side processing just provide an URL to that endpoint in the ajax property of the filterDropDown init array.
The endpoint for filterDropDown needs to implement the following protocol:
The endpoint will receive a GET request with the following query parameter:
columns: list of requested columns, either by name or index (depends oncolumnsdefinition)
Example2:
http://www.example.com/endpoint?columns=2,3,0
http://www.example.com/endpoint?columns=office,position,name
Column names will match with the names defined in the DataTables init array under data for each column.
The endpoint will need to respond with an JSON object that has the requested columns as property key and the sorted list of options as it's respective values.
Note that all data processing like selecting unique values and sorting is expected to happen by the server.
Examples:
{
"office":
[
"Edinburgh", "London", "New Yok", "San Francisco", "Sidney", "Tokyo"
],
"position":
[
"Accountant", "Customer Support", "Data Coordinator", "Developer"
]
}{
"2":
[
"Edinburgh", "London", "New Yok", "San Francisco", "Sidney", "Tokyo"
],
"3":
[
"Accountant", "Customer Support", "Data Coordinator", "Developer"
]
}In case columns are missing in the response, those will be reported with a warning in the browser console.
All configuration options must be set in the filterDropDown section of the initialization array for your respective DataTable.
| Option | Type | Mandatory | Default | Description |
|---|---|---|---|---|
| bootstrap | boolean | no | false |
Defines whether Bootstrap styling should be applied |
| autoSize | boolean | no | true |
Turns off auto sizing for all select elements to the width of its title. Useful if table is rendered on hidden tab. |
| label | string | no | "Filter " |
Text displayed at the beginning of the filter row. This option can be useful if label should be shown in other languages |
| ajax | string | no | null |
URL to server endpoint for server-side processing. Enabled by providing a value. |
| columns | array | yes | N/A | Array of definition, one for each column that gets a filter element |
| columns[].idx | number | yes | N/A | Index of selected column, starting at 0 for the first column. Same as indices used in DataTables config array |
| columns[].autoSize | boolean | no | true |
Turns off auto sizing for this select elements to the width of its title. Useful if table is rendered on hidden tab. |
| columns[].maxWidth | string | no | automatic width, so that title will fit. Turned off for screens < 768 pixels | css value to assigned to max-width. use "null" to turn off automatic max-width or specify a custom width, e.g. "5em" |
| columns[].title | string | no | header text of respective column or just "column x" if column has no header label | This is useful if you want to filter by the contents of an invisible column that usually would not have any header label |
- JQuery: 1.12.4+
- DataTables: 1.10.15+
- Bootstrap: 3.3.7+
It might work with earlier versions, but that has not been tested.
You find test instrumentation in the tests folder. There are two parts:
- Web server
- Unit tests for the web server
The tests are running a web server build with with Flask. Here is how to setup your test environment:
python3 -m venv venv
source venv/bin/activate
cd tests
pip install -r requirements.txtThe web server will render a web site with several example data tables, which will allow you to manually test the filterDropDown library with various scenarios, e.g.:
- Vanilla style
- Bootstrap style
- Server side processing
Here is how to start the web server (we recommend doing this in a Python virtual environment):
cd tests
flask runThe unit tests are in Python and only test the web server, not the filterDropDown library. These tests only need to run when the web server code was changed.
Here is how you can run these tests:
cd tests
python app_test.pyI have a column with html styled data and the option list of its dropDown does still contain parts of the html. How do I filter by the plain value only?
Add an invisible column containing only the plan values and filter by that column instead. Use titleOverride to set the correct title for the dropDown element.
The select elements are too small when rendered. How can I change the width of each column?
The width of the select element for each column is automatically set to width of its title to safe space. This can be turned off for each column or globally for the whole table with the autoSize property.