floatThead - table header plugin

Mar 19, 2014 in Tables 8795 views

Download

Overview
Documents

User Rating: 5/5 ( 2 votes)

Your Rating:

jquery.floatThead is a floating/locked/sticky table header plugin that requires no special CSS and supports window and overflow scrolling.

Features:

Floats the table header - so that the user can always see it
Supports tables with inner scroll bars, or window scrolling
Horizontal or vertical scrolling
Doesn't clone the thead - so your events stay bound
Doesn't mess with your styles
Works on any table
Requires no special css
Works with datatables out of the box

Requirements:

jQuery 1.8.x or better (code is 1.9+ compliant) or jQuery 1.7.x + jQuery UI core
Internet Exploder 8 - 11, FireFox 10+ or Chrome15+
Add this meta tag into your header to placate IE: <meta http-equiv="X-UA-Compatible" content="IE=10; IE=9; IE=8; IE=7; IE=EDGE" />

Usage

There are 2 ways you can initialize the table:

Overflow scrolling
The table is inside of a container with overflow:auto
Window scrolling
Header becomes locked at the top of the page as user scrolls down

Window scrolling is the default. Initialize floatThead without any params to use it. $('table').floatThead()

Overflow scrolling takes a bit more work. You must specify a container element inside of which the table will scroll. You must create this element. Usually a div will wrap the table with overflow:auto and a size smaller than the table.

var $table = $('table.demo');
$table.floatThead({
    scrollContainer: function($table){
		return $table.closest('.wrapper');
	}
});

Options

Note: All the options which are functions take a single argument: $table - the table who's header is being floated.
ex: function($table){ ... }


scrollContainer	function	null	Defines a container element inside of which the table scrolls vertically and/or horizontally. usually a wrapping div
scrollingTop	number or function	0	Offset from the top of the window where the floating header will 'stick' when scrolling down
scrollingBottom	number or function	0	Offset from the bottom of the window where the floating header will 'stick' when scrolling down
floatTableClass	string	floatThead-table	This class is added to the table element after you run floatThead on it
floatContainerClass	string	floatThead-container	This class is added to the container div inside of which your thead will spend time floating
useAbsolutePositioning	boolean	true	Position the floated header using absolute positioning or using fixed positioning. Fixed positioning performs better with tables that use window scrolling, but fails miserably on highly dynamic pages where DOM can be suddenly modified causing the location of the floated table to shift. (You should call .floatThead('reflow') in this case, but you cant always instrument your code to make that call.)
debounceResizeMs	number	1	The headers are repositioned on resize. Because this event has the potential to fire a bunch of times, it is debounced. This is the debounce rate.
zIndex	number	1001	z-index of the floating header
cellTag	string	th:visible	Specifies the selector used to find header cells (in the table's thead element)
debug	boolean	false	Point out various possible issues via console.log if it is available
getSizingRow	function	undefined	Used by IE Only If your table's first visible row (tbody tr:visible:first td) contains td elements with colspans, then you need to return another set of tds which have no colspans. In other words the selector should return the same number of TDs as columns in your table. Here is an example
copyTableClass	boolean	true	Should the table's class attribute be copied to the floated table? This make the styles written for the table's class selector apply also to the floated header. However, if you are later selecting this table by class you may be surprised to find 2 tables.

Name	type	default	description

Methods

.floatThead('destroy')

Removes the widget from the table

var $table = $('table.demo1');
//float the headers
$table.floatThead();
//unfloat the headers
$table.floatThead('destroy');

.floatThead('reflow')

Cause header to realign itself to the correct position. Same as the reflow event below.

var $table = $('table.demo1');
//float the headers
$table.floatThead();
$table.floatThead('reflow');

.floatThead('getRowGroups')

Returns the table's thead, tbody and tfoot elements. Useful because you cannot simply select thead if the table's header is currently being floated.
For more info on why you may want this read through this example

Events

$table.trigger('reflow')

Given a table element $table that has been widgetized, a reflow event causes the header to realign itself to the correct position. This event must be triggered if the DOM is modifed in such a way that the widgetized table's location changes.

var $table = $('table.demo1');
$table.floatThead();
//change the location of the table in the dom:
$table.css('marginTop', 100);
//cause the floated header to be properly positioned again:
$table.trigger('reflow');

JS Tutorial