TableFilter/README.md

TableFilter

Filter HTML tables data easily

TableFilter is a modernised version of the HTML Table Filter generator plugin. 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. By default, the script automatically adds a filter grid bar at the top of the desired table.

##Features

• Convert a regular HTML table into an advanced grid component providing:
  • Advanced columns filtering model
  • Sorting and pagination facilities
  • Complete selection model (addon)
  • Extended keyboard navigation (addon)
  • Inline cell or row editing (addon)
  • Row insertion or deleting (addon)
  • And even more behaviors...
• Attach to an existing HTML table
• Integration with any server-side technology as this is a pure client-side solution
• Callbacks for all events, and delegates for most actions
• Exhaustive documentation and API
• Valuable support provided under a Premium request

##Setup Copy the tablefilter directory under dist and place it at desired location in your project. Then include the bundle js file in your page:

<script src="path/to/my/scripts/tablefilter/tablefilter.js"></script>

Place the following snippet just under the HTML table and always define a base_path property in the configuration object to reflect the path to the script

<script>
var tf = new TableFilter('my-table-id', {
    base_path: 'path/to/my/scripts/tablefilter/'
});
tf.init();
</script>

##Development If you are not familiar with Grunt visit this page: gruntjs.com/getting-started. Once Grunt is sorted out you can follow the instructions below. Start by installing any dependencies.

npm install

Use the Grunt dev task to launch a build / watch cycle and start the local sever on port 8080:

grunt dev

Use the build task to generate a production build:

grunt build

The default Grunt task will create a production build and also run the tests:

grunt

To run all the tests:

grunt test

and to run specific test(s):

grunt test-only:test.html
grunt test-only:test.html,test-sort.html

Support

• GitHub for reporting bugs and feature requests.

License

MIT

Documentation

Configuration

Filters appearance

Property	Type	Description	Remarks	Example
base_path	string	defines the path to the script's directory (default: 'TableFilter/')		var tfConfig = { base_path: 'myDir/' }
stylesheet	string	defines the global stylesheet (default: 'filtergrid.css')		var tfConfig = { stylesheet: 'myDir/myStylesheet.css' }
filters_cell_tag	string	specifies the tag of the cell containing a filter ('td' / 'th')		var tfConfig = { filters_cell_tag: 'th' }
col_widths	array	this property defines column widths. It accepts an array containing width values (['150px','10%'])		var tfConfig = { col_widths: ["150px","15%",null,null] }
inf_div_css_class	string	defines the css class of div containing paging elements, rows counter etc.	This div contains the paging elements, subdivided in 3 divs (left, middle and right).	var tfConfig = { inf_div_css_class: "myclass" }
left_div_css_class	string	defines the css class of left div	This div contains the rows counter	var tfConfig = { left_div_css_class: "myclass" }
right_div_css_class	string	defines the css class of right div	This div contains the Clear button and the results per page drop-down list if paging is enabled	var tfConfig = { right_div_css_class: "myclass" }
middle_div_css_class	string	defines the css class of middle div	This div contains the pages drop-down list and paging navigation buttons	var tfConfig = { middle_div_css_class: "myclass" }
flts_row_css_class	string	defines the css class of filters row		var tfConfig = { flts_row_css_class: "myclass" }
flt_css_class	string	defines the css class of filters (inputs and selects)		var tfConfig = { flt_css_class: "myclass" }
flt_small_css_class	string	defines the css class of smaller filters (if validation button is generated in the same column of a filter)		var tfConfig = { flt_small_css_class: "myclass" }
flt_multi_css_class	string	defines css class of multiple select filters		var tfConfig = { flt_multi_css_class: "myclass" }
single_flt_css_class	string	defines the css class of the single filter when the single_search_filter property is on		var tfConfig = { single_flt_css_class: "myclass" }
highlight_css_class	string	defines the css class of highlighted keywords		var tfConfig = { highlight_css_class: "myclass" }
even_row_css_class	string	defines the css class for even rows		var tfConfig = { even_row_css_class: "myclass" }
odd_row_css_class	string	defines the css class for odd rows		var tfConfig = { odd_row_css_class: "myclass" }
input_watermark_css_class	string	defines the css class of the watermark in input filters (default - fltWatermark)		var tfConfig = { input_watermark_css_class: "myclass" }
active_columns_css_class	string	defines the css class of the active column headers (default - activeHeader)		var tfConfig = { active_columns_css_class: "myclass" }

####Features and behaviours

Property	Type	Description	Remarks	Example
grid	boolean	enables / disables filters generation (default - true)		var tfConfig = { grid: false }
col_{n}	string	generates a filter type in specified column (replace "{n}" by column index). Possible values: "input", "select", "multiple", "checklist", "none" (default: "input")		var tfConfig = { col_2: "none", col_3: "select", col_4: "multiple", col_5: "checklist"}
filters_row_index	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 }
enter_key	boolean	enables / disables "enter" key for validation (default * true)		var tfConfig = { enter_key: false }
on_before_filter	function	Callback fired before filtering starts		var tfConfig = { on_before_filter: function(o){ alert('Calls function before filtering starts!!!'); }
on_after_filter	function	Callback fired after filtering is completed		var tfConfig = { on_after_filter: function(o){ alert('Calls function after filtering process!!!'); }
on_filters_loaded	function	Callback fired after filters instantiation		var tfConfig = { on_filters_loaded: function(o){ alert('Calls function after filters generation!!!'); }
on_before_operation	function	Callback fired before column operations are performed (default * null)		var tfConfig = { on_before_operation: function(o){ alert('Calls function before column operations are performed!!!'); }
on_after_operation	function	Callback fired after column operations are performed (default * null)		var tfConfig = { on_after_operation: function(o){ alert('Calls function after column operations are performed!!!'); }
on_row_validated	function	Callback fired after a row is validated (default - null)	note that 2 parameters are sent to the callback: o is the current TF object k is the current row index	var tfConfig = { on_row_validated: function(o, k){ alert('Calls function after a row is validated!!! Validated row nb = '+k ); }
custom_cell_data_cols	array	specifies the columns that will use the custom_cell_data delegate (default - [])		var tfConfig = { custom_cell_data_cols: [0,2,3] };
custom_cell_data	function	Custom delegate function retrieving cell data (default - null)	3 parameters are sent to the function: o is the current TF object cell is the current cell from which data is retrieved index is the current column index	var tfConfig = { custom_cell_data: function(o,cell,index){ alert('Calls function when cell data is retrieved!!!'); }
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 }
case_sensitive	boolean	if set true terms matching become case sensitive (default - false)		var tfConfig = { case_sensitive: true }
alternate_rows	boolean	if set true, it enables alternating rows background color (default * false)		var tfConfig = { alternate_rows: true }
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..])	since rows are always visible, cells value will not appear in corresponding drop-down filters. Note that this property works only if paging is disabled	var tfConfig = { rows_always_visible: [9,10] }
refresh_filters	boolean	if set true this property modifies the filtering behaviour: drop-down menus are refreshed and display only the visible options (default * false).		var tfConfig = { refresh_filters: true }
disable_excluded_options	boolean	When refresh_filters is enabled, if set true this property disables the excluded options (default * false).	This feature was suggested by zehnplus.	var tfConfig = { refresh_filters: true, disable_excluded_options: true }
auto_filter	boolean	if set true this property enables the 'filter as you type' behaviour (default - false)	table is filtered when user stops typing	var tfConfig = { auto_filter: true }
auto_filter_delay	number	defines the filtering delay in milliseconds (default - 900)	when user stops typing, table is filtered after defined delay	var tfConfig = { auto_filter: true, auto_filter_delay: 1500 }
highlight_keywords	boolean	if set true this property enables keywords highlighting (default * false)		var tfConfig = { highlight_keywords: true }
remember_grid_values	boolean	if set true this property will re-set filters' values at page reload (default - false)		var tfConfig = { remember_grid_values: true }
remember_page_number	boolean	if set true this property will re-set the last accessed page at page reload (default - false)		var tfConfig = { remember_page_number: true }
remember_page_length	boolean	if set true this property will re-set the number of results per page at page re-load (default - false)		var tfConfig = { remember_page_length: true }
single_search_filter	boolean	if set true this property enables a single criteria search. Only 1 text-box filter will be displayed (single criteria search vs. multi-criteria search) searching in all table columns (default - false)		var tfConfig = { single_search_filter: true }
external_flt_grid	boolean	if set true this property enables filters generation in desired container elements (default - false)	Check this example.	var tfConfig = { external_flt_grid: true }
external_flt_grid_ids	array	this array contains the id of the elements that will contain the generated filters. The indexes of the array items match the indexes ot the columns of the table ( ['id0','id1','id02'] corresponds to col0, col1, col2) (default - null)		var tfConfig = { external_flt_grid_ids: ['id0','id1','id2'] }
toolbar_target_id	string	defines the id of the element that will contain the toolbar container, located above the table headers by default (default * null)		var tfConfig = { toolbar_target_id: 'myContainerId' };
status	boolean	if set true this property displays status messages in the browser's status bar		var tfConfig = { status: true }
or_operator	string	defines the or operator that enables multiple keywords searches on a column (default - '||')		var tfConfig = { or_operator: ',' }
exec_delay	number	sets the delay in msecs of filtering process if loader set true (default - 100)		var tfConfig = { exec_delay: 250 }
set_cookie_duration	number	sets the cookie duration in mms (default - 100000)		var tfConfig = { set_cookie_duration: 250000 }
enable_icons	boolean	it makes the toolbar icons visible by default, paging and clear filters button (default - true)	Makes the configuration object a little bit less verbose	var tfConfig = { enable_icons: false }
input_watermark	string	defines the watermark text for input type filters (default - '')	Same text is set in all input filters	var tfConfig = { input_watermark: 'Search...' }
watermark	array or string	if used as an array, a different text can be defined for each input filter (default - '')		var tfConfig = { watermark: ['Search...', null, 'Dates here...'] }
mark_active_columns	boolean	column headers are highlighted upon filtering(default * false)		var tfConfig = { mark_active_columns: true }
on_before_active_column	function	Callback fired before column header is marked as active (default - null)	note that 2 parameters are sent to the function: o is the current TF object the current index of filtered column	var tfConfig = { on_before_active_column: function(o, colIndex){ alert(colIndex); } }
on_after_active_column	function	Callback fired after column header is marked as active (default - null)	note that 2 parameters are sent to the function: o is the current TF object the current index of filtered column	var tfConfig = { on_after_active_column: function(o, colIndex){ alert(colIndex); } }