This script adds to any html table a "filter by column" feature that enables users to filter and limit the data displayed within a long table. It even works on tables with uneven rows. The script automatically adds a filter grid bar at the top of the desired table. Users can use the following operators to filter columns containing numeric data: <, <=, >, >=.
- Description page at:
mguglielmi.free.fr/scripts/TableFilter
- Additional demo pages at:
mguglielmi.free.fr/scripts/TableFilter/datademo.htm
mguglielmi.free.fr/scripts/TableFilter/datademo2.htm
mguglielmi.free.fr/scripts/TableFilter/filter-sort.htm
You just need to define the id attribute of a table and insert a piece of javascript code in the head of the html document or in an external ".js" file.
Here you have an example of a regular html table:
| From | Destination | Road Distance (km) | By Air (hrs) | By Car/Coach (hrs) | By Rail (hrs) |
| Sydney | Adelaide | 1412 | 1.4 | 24 | 25.3 |
| Sydney | Brisbane | 982 | 1.5 | 17 | 16 |
| Sydney | Canberra | 286 | .6 | 4.2 | 4.3 |
| Sydney | Melbourne | 872 | 1.1 | 14.3 | 10.5 |
| Adelaide | Perth | 2781 | 3.1 | 35 | 38 |
| Adelaide | Alice Springs | 1533 | 2 | 20 | 20.25 |
| Adelaide | Brisbane | 2045 | 2.15 | 33.3 | 40 |
Below the same table with a filtering grid generated automatically:
| From | Destination | Road Distance (km) | By Air (hrs) | By Car/Coach (hrs) | By Rail (hrs) |
|---|---|---|---|---|---|
| Sydney | Adelaide | 1412 | 1.4 | 24 | 25.3 |
| Sydney | Brisbane | 982 | 1.5 | 17 | 16 |
| Sydney | Canberra | 286 | .6 | 4.2 | 4.3 |
| Sydney | Melbourne | 872 | 1.1 | 14.3 | 10.5 |
| Adelaide | Perth | 2781 | 3.1 | 35 | 38 |
| Adelaide | Alice Springs | 1533 | 2 | 20 | 20.25 |
| Adelaide | Brisbane | 2045 | 2.15 | 33.3 | 40 |
By adding an id (id="table1") to the table
and inserting the script block in the <body> section below
the table itself:
<script language="javascript" type="text/javascript">
setFilterGrid("table1");
</script>
the grid will be generated automatically. The number of filters (<input>) is equal to the number of columns (<td>).
If your document contains several tables (like this page), it is important to define unique ids, otherwise the script will not work properly.
The setFilterGrid() function accepts 2 additional parameters that
will be explained in the next tables. In the example below, by specifing a row
number as a "reference" row, we tell the function which row to use
in order to generate the right number of filters:
| This is the table caption | |||||
| From | Destination | Road Distance (km) | By Air (hrs) | By Car/Coach (hrs) | By Rail (hrs) |
|---|---|---|---|---|---|
| Sydney | Adelaide (AUS) | 1412 | 1.4 | 24 | 25.3 |
| Sydney | Brisbane | 982 | 1.5 | 17 | 16 |
| Sydney | Canberra | 286 | .6 | 4.2 | 4.3 |
| Sydney | Melbourne | 872 | 1.1 | 14.3 | 10.5 |
| Adelaide | Perth | 2781 | 3.1 | 35 | 38 |
| Adelaide | Alice Springs | 1533 | 2 | 20 | 20.25 |
| Adelaide | Brisbane2045 | 2.15 | 33.3 | 40ttt | |
setFilterGrid("table2",1);
Here we have specified row number 1, that is the second row
from the top. The 1st row is number 0. Since the 1st row doesn't
contain the right number of columns, we need to pass the mentioned parameter
in order to calculate the right number of columns and also define from which
row should start the filtering process. Note that merged cells (<td
colspan="2">) are simply skipped.
By default, the script adds text boxes (<input>). As you
will see in the next example, you may also decide to use a drop-down
lists (<select>) instead of text boxes:
| This is the table caption | ||||||
| From | Destination | Road Distance (km) | By Air (hrs) | By Car/Coach (hrs) | By Rail (hrs) | |
|---|---|---|---|---|---|---|
| 1. | Sydney | Adelaide | 1412 | 1.4 | 24 | 25.3 |
| 2. | Sydney | Brisbane | 982 | 1.5 | 17 | 16 |
| 3. | Sydney | Canberra | 286 | .6 | 4.2 | 4.3 |
| 4. | Sydney | Melbourne | 872 | 1.1 | 14.3 | 10.5 |
| 5. | Adelaide | Perth | 2781 | 3.1 | 35 | 38 |
| 6. | Adelaide | Alice Springs | 1533 | 2 | 20 | 20.25 |
| 7. | Adelaide | Brisbane | 2045 | 2.15 | 33.3 | 40 |
To do that you just need to declare an Array in which you specify which filters should not be displayed or displayed as drop-down lists:
<script language="javascript" type="text/javascript">
var table3Filters = {
btn: true,
col_0: "none",
col_2: "select",
btn_text: " > "
}
setFilterGrid("table3",1,table3Filters);
</script>
You can name the Array as you want, but don't forget to add it
to the parameters of the setFilterGrid() function. It is important
to respect the syntax and naming convention as shown above. There are only 2
values: "none" hides the text box for
the designated column and "select" creates
a drop-down list with only 1 occurrence of each cell data. Similarly to row
designation, here the first column is column number 0: col_0.
The button "go" in the grid can also be changed. By adding the btn_text property with
a desired value, you can modify the text of the button. Below you will find an exhaustive list of properties you can define.
In the following table you will find all the properties you can use to configure the grid:
| Property Name | Type | Description | Example |
|---|---|---|---|
| col_n | string | hides text box (input) for a desired column (replace "n" by column index) | var tfConfig = { col_0: "none" } |
| col_n | string | generates a drop-down list for a desired column (replace "n" by column index) | var tfConfig = { col_3: "select" } |
| btn | boolean | if set true shows "Go" button in the grid (default - false) | var tfConfig = { btn: true } |
| btn_text | string | changes the text of the button | var tfConfig = { btn_text: "Filter"
} |
| enter_key | boolean | disables "enter" key (default - true) | var tfConfig = { enter_key: false } |
| mod_filter_fn | function | calls another function instead of the default function ( tf_Filter('mytable') ) at submission | var tfConfig = { mod_filter_fn: function(){ alert('Calls
another function!!!'); tf_Filter('table_3'); }} |
| display_all_text | string | sets "display all" text in drop-down list; (default - empty) | var tfConfig = { display_all_text: "Display
all" } |
| on_change | boolean | filters the table as you change the value of a drop-down list (default - true) | var tfConfig = { on_change: false } |
| rows_counter | boolean | if set true, it will display the total # of rows displayed at the top of the table in left corner (default - false) | var tfConfig = { rows_counter: true } |
| rows_counter_text | string | sets text for rows counter label (default - "Data rows: ") | var tfConfig = { rows_counter_text: "Total
items: " } |
| btn_reset | boolean | if set true, it will show a "Reset" button at the top-right corner of the table allowing users to re-initialise the table (default - false) | var tfConfig = { btn_reset: true } |
| btn_reset_text | string | sets text for the "Reset" button (default - "Reset") | var tfConfig = { btn_reset_text: "Clear"
} |
| btn_reset_html new | string | defines 'reset' button HTML if btn_reset property set true (default - null). Note that onclick event is added automatically to html element and overwrites any eventual onclick attribute | var tfConfig = { btn_reset:true, |
| sort_select | boolean | if set true, it will sort options in the drop-down list(s) (default - false) | var tfConfig = { sort_select: true } |
| sort_num_asc new | array | this property sets the numeric values of a specified column drop-down filter in ascending order. Columns should only contain numeric values. It accepts an array containing column indexes ([0,2]) | var tfConfig = { sort_num_asc: [1,2] }; |
| sort_num_desc new | array | this property sets the numeric values of a specified column drop-down filter in descending order. Columns should only contain numeric values. It accepts an array containing column indexes ([0,2]) | var tfConfig = { sort_num_desc: [1,2] }; |
| paging | boolean | if set true, it will generate a paging feature | var tfConfig = { paging: true } |
| paging_length | number | sets # of rows displayed in a page (default - 10) | var tfConfig = { paging_length: 50 } |
| results_per_page new | array | this property enables users to change the number of results per page.
Paging property needs to be set true. It accepts an array with the following
values:
|
var tfConfig = { results_per_page: ['Results per page',[25,50,100]]
}; |
| pagingBtns new | boolean | enables / disables paging buttons if paging property set true (default - true) | var tfConfig = { paging: true, pagingBtns: false }; |
| btn_next_page_text new | string | sets 'next page' button's label if paging property set true (default - ">") | var tfConfig = { paging: true, btn_next_page_text: 'Next >' }; |
| btn_prev_page_text new | string | sets 'previous page' button's label if paging property set true (default - "<") | var tfConfig = { paging: true, btn_prev_page_text: '< Prev' }; |
| btn_last_page_text new | string | sets 'last page' button's label if paging property set true (default - ">|") | var tfConfig = { paging: true, btn_last_page_text: 'Last >>' }; |
| btn_first_page_text new | string | sets 'first page' button's label if paging property set true (default - "|<") | var tfConfig = { paging: true, btn_first_page_text: '<| First' }; |
| btn_next_page_html new | string | defines 'next page' button's HTML if paging property set true. Note that onclick event is added automatically to html element and overwrites any eventual onclick attribute (default - null) | var tfConfig = { paging: true, btn_next_page_html: ' <a href="javascript:;">Next
></a> ' }; |
| btn_prev_page_html new | string | defines 'next page' button's HTML if paging property set true. Note that onclick event is added automatically to html element and overwrites any eventual onclick attribute (default - null) | var tfConfig = { paging: true, btn_prev_page_html: ' <a href="javascript:;"><
Previous</a> ' }; |
| btn_last_page_html new | string | defines 'next page' button's HTML if paging property set true. Note that onclick event is added automatically to html element and overwrites any eventual onclick attribute (default - null) | var tfConfig = { paging: true, btn_last_page_html: ' <a href="javascript:;"><
Last >|</a> ' }; |
| btn_first_page_html new | string | defines 'next page' button's HTML if paging property set true. Note that onclick event is added automatically to html element and overwrites any eventual onclick attribute (default - null) | var tfConfig = { paging: true, btn_first_page_html: ' <a href="javascript:;"><|
First</a> ' }; |
| loader | boolean | if set true, it will display a "loading" message (default - false) | var tfConfig = { loader: true } |
| loader_text | string | sets text for "loading" message (default - "Loading...") | var tfConfig = { loader_text: "Filtering
data..." } |
| loader_html new | string | defines loader's HTML if loader property set true (default - null) | var tfConfig = { loader:true, |
| exact_match | boolean | if set true, only exact matches will be displayed (default - false). Note that this is case insensitive | var tfConfig = { exact_match: true } |
| match_case new | boolean | If set true filters become case sensitive (default - false) | var tfConfig = { match_case: true }; |
| grid | boolean | enables / disables filter grid generation (default - true) | var tfConfig = { grid: false } |
| filters_row_index new | number | this property defines in which row the filters grid will be generated: 0 (before table headers) or 1 (after table headers) | var tfConfig = { filters_row_index: 1 }; |
| alternate_rows | boolean | if set true, it enables alternating rows background color (default - false) | var tfConfig = { alternate_rows: true } |
| col_operation updated | object | this object calculates the values of a column (sum,mean,min,max). It works
with the following properties:
|
var tfConfig = { |
| rows_always_visible | array | this property makes desired rows always visible. It accepts an array definining the row indexes to be displayed ([1,2,3..]) | var tfConfig = { rows_always_visible: [9,10] } |
| col_width | array | this property defines column widths. It accepts an array containing width values (['150px','10%']) | var tfConfig = { col_width: ["150px","15%",null,null]
} |
| bind_script | object | this property designs a function to call after grid generation. This function
will interact with another script in order to merge the filter generator
with other script(s). Note that the invoked function needs to developed.
It accepts an object with the following properties:
|
var tfConfig = { |
| refresh_filters new | boolean | If set true this property modifies the filtering behavior: drop-down menus are refreshed and display only the visible options (default - false). | var tfConfig = { refresh_filters: true }; |
| remember_grid_values new | boolean | If set true this property will re-set filters' values on page reload (default - false) | var tfConfig = { remember_grid_values: true }; |
These are the functions developers should use in order to interact with the filter grid:
| Fn name | Description | Example |
|---|---|---|
| TF_GetFilterIds() | Returns an array containing filter grid ids of the page | var gridIds = TF_GetFilterIds(); |
| TF_HasGrid(id) | Checks if the table designated by the argument has a filter grid. It returns a boolean | var hasTFGrid = TF_HasGrid("myTableId"); |
| TF_GetFilters(id) | Returns an array containing filter ids of a specified grid | var filterIds = TF_GetFilters("myTableId"); |
| TF_GetStartRow(id) | Returns the index of the row from which will start the filtering process | var startRow = TF_GetStartRow("myTableId"); |
| TF_GetColValues(id,colindex,num) | Returns an array containing cell values of a column. It needs following
args:
|
var myColValues = TF_GetColValues("myTableId",0);
|
| TF_Filter(id) | Filters a table | TF_Filter("myTableId"); |
| TF_RemoveFilterGrid(id) | Removes the grid. Note that all the properties attached to the filter table will not be removed. This will make it easier to reset the filter (if needed) since all the properties are still available | TF_RemoveFilterGrid("myTableId"); |
| TF_ClearFilters(id) | Clears the grid filters only. Note that the table will not be filtered | TF_ClearFilters(id); |
| TF_SetFilterValue(id,index,searcharg) | Inserts a value in a specified filter. It accepts the following arguments:
|
TF_SetFilterValue("myTableId",2,'Search string here');
|
| TF_GetFilterValue(id,index) new | Retrieves the value of a specified filter. It needs the following arguments:
|
TF_GetFilterValue("myTableId",2); |
| TF_SetPage(id,action) new | If paging set true shows page according to action param value. It needs the following arguments:
|
TF_SetPage("myTableId","next"); |
| TF_GetTableData(id) new | Returns an array containing the data of a specified table. The array is formated in the following manner:
|
TF_GetTableData("myTableId"); |
I hope you will find this script useful. Feel free to use and change this script, however I will be grateful if you could inform me about any usage or modification.