|
|
Cut & Paste HTML Table filter script (v 1.6)
Note: Updated to v 1.6 on Feb 15th, 2007
Description:
This awesome 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. Very nice!
How does it work?
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 (press
enter after entering in some filter text):
|
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 below in the <body> section:
<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 |
|
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 (AUS) |
Perth |
2781 |
3.1 |
35 |
38 |
|
6. |
DeAdelaide |
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 for col_n: "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.
Properties table
In the following table you will find all the elements you can define in the
grid:
|
Property Name |
Type |
Description |
Example |
|
col_0 |
string |
hides text box (input) for a desired column |
var MyTableFilter = { col_0: "none" } |
|
col_3 |
string |
generates a drop-down list for a desired column |
var MyTableFilter = { col_3: "select" } |
|
btn |
boolean |
if set true shows "Go" button in the grid (default - false) |
var MyTableFilter = { btn: true } |
|
btn_text |
string |
changes the text of the button |
var MyTableFilter = { btn_text: "Filter" } |
|
enter_key |
boolean |
disables "enter" key (default - true) |
var MyTableFilter = { enter_key: false } |
|
mod_filter_fn |
function |
calls another function instead of the default function ( Filter('mytable') )
at submission |
var MyTableFilter = { mod_filter_fn: function(){ alert('Calls another
function!!!'); Filter('table_3'); }} |
|
display_all_text |
string |
sets message for "display all" in drop-down list; (default - empty) |
var MyTableFilter = { display_all_text: "Display all towns" } |
|
on_change |
boolean |
filters the table as you change the value of a drop-down list (default -
true) |
var MyTableFilter = { 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 MyTableFilter = { rows_counter: true } |
|
rows_counter_text |
string |
sets text of the label for total # of rows displayed (default - "Data rows:
") |
var MyTableFilter = { rows_counter_text: "Total items: " } |
|
btn_reset |
boolean |
if set true, it will show a "Reset" button at the top of the table in right
corner (default - false) allowing users to re-initialise the table |
var MyTableFilter = { btn_reset: true } |
|
btn_reset_text |
string |
sets text for the "Reset" button (default - "Reset")
|
var MyTableFilter = { btn_reset_text: "Clear" } |
|
sort_select |
boolean |
if set true, it will sort options in the drop-down list(s) (default - false) |
var MyTableFilter = { sort_select: true } |
|
paging |
boolean |
if set true, it will generate a paging feature |
var MyTableFilter = { paging: true } |
|
paging_length |
number |
sets # of rows displayed in a page (default - 10) |
var MyTableFilter = { paging_length: 50 } |
|
loader |
boolean |
if set true, it will display a "loading" message (default - false) |
var MyTableFilter = { loader: true } |
|
loader_text |
string |
sets text for "loading" message (default - "Loading...")
|
var MyTableFilter = { loader_text: "Filtering data..." } |
|
exact_match |
boolean |
if set true, only exact matches will be displayed (default - false) |
var MyTableFilter = { exact_match: true } |
|
grid |
boolean |
enables / disables filter grid generation (default - true) |
var MyTableFilter = { grid: false } |
|
alternate_rows |
boolean |
if set true, it enables alternating rows background color (default - false)
|
var MyTableFilter = { alternate_rows: true } |
|
col_operation |
object |
this object calculates the values of a column (sum,mean). It works with the
following properties:
- colOperation["id"] contains the ids of elements
showing result (array)
- colOperation["col"] contains index of
columns (array)
- colOperation["operation"] contains operation
type (array, values: 'sum', 'mean')
- colOperation["write_method"] array defines
which method to use for displaying the
result ('innerHTML', 'setValue', 'createTextNode').
Note that innerHTML is the default value.
|
var MyTableFilter = {
col_operation: {
id: ["table8Tot1","table8Tot2"],
col: [2,5],
operation: ["sum","mean"],
write_method:
["innerHTML","setValue"]
}
} |
|
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 MyTableFilter = { rows_always_visible: [9,10] } |
|
col_width |
array |
this property defines column widths. It accepts an array containing width
values (['150px','10%']) |
var MyTableFilter = { col_width: ["150px","15%",null,null] } |
|
bind_script |
object |
this property designs a function that will be called 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:
- bind_script["name"] contains an identifier for the script
(string)
- bind_script["target_fn"] designs the function to invoke
(function)
|
var table10_Props = {
bind_script:{ name:"autocomplete", target_fn:
setAutoComplete }
}; |
Public functions
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:
- a table id (string)
- a column index (number)
- a boolean set to true if we want only numbers to be returned
(optional)
|
var myColValues = TF_GetColValues("myTableId",0);
|
|
TF_Filter(id) |
Filters a table |
TF_Filter("myTableId"); |
|
TF_RemoveFilterGrid(id) |
Removes a filter 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:
- a table id (string)
- a filter column index (numeric value)
- a search string
|
TF_SetFilterValue("myTableId",2,'Search string here');
|
Directions: Simply download "HTML
Table Filter (v1.6)", and refer to the html page inside.
|
