Demo Pages Moved!!!

If you are reading this, it means that my magical meta-refresh tag did effect you! This is the old version of the plugin/docs. The new version is here:

http://mkoryak.github.io/floatThead/

Intro

I was fed up the current state of floating header plugins. They either lose your styles or lose your events, or dont support the edge cases.
This is why i wrote jQuery.floatThead.

Features:

Floats the table header - so that the user can always see it
Supports tables with inner scroll bars, or whole page scrolling
Horizonal or vertical scrolling
Doesnt clone the thead - so your events stay bound
Doesnt 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 or jQuery 1.7.x + jQuery UI core
Underscore.js 1.3 or better
IE8, IE9, FF10+ or Chrome15+

Demo

Header 1	Header 2	Header...3
Cell Content 1	Cell Content 2	Cell Content 3
More Cell Content 1	More Cell Content 2	More Cell Content 3
Even More Cell Content 1	Even More Cell Content 2	Even More Cell Content 3
And Repeat 1	And Repeat 2	And Repeat 3
Cell Content 1	Cell Content 2	Cell Content 3
More Cell Content 1	More Cell Content 2	More Cell Content 3
Even More Cell Content 1	Even More Cell Content 2	Even More Cell Content 3
And Repeat 1	And Repeat 2	And Repeat 3
Cell Content 1	Cell Content 2	Cell Content 3
More Cell Content 1	More Cell Content 2	More Cell Content 3
Even More Cell Content 1	Even More Cell Content 2	Even More Cell Content 3
And Repeat 1	And Repeat 2	And Repeat 3
Cell Content 1	Cell Content 2	Cell Content 3
More Cell Content 1	More Cell Content 2	More Cell Content 3
Even More Cell Content 1	Even More Cell Content 2	Even More Cell Content 3
And Repeat 1	And Repeat 2	And Repeat 3
Cell Content 1	Cell Content 2	Cell Content 3
More Cell Content 1	More Cell Content 2	More Cell Content 3
Even More Cell Content 1	Even More Cell Content 2	Even More Cell Content 3

Usage

There are 2 ways you can initialize the table:

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

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

Internal 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){ ... }

Name	type	default	description
scrollContainer	function	null	Defines a contaier 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
getSizingRow	function	null	The plugin uses the first row in the table body to calculate floated header's column sizes. It expects this row to contain `<td>`s with colspan of at most 1. If the first row does not meet that requirement, you must implement this function. Returns: jquery object containing tds. Length of this element much match the number of columns in the table. example use
useAbsolutePositioning	boolean	true	Position the floated header using absolute positioning or using fixed positioning. Fixed positioning peforms 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	Specifies which tag is used in the header to specify cells example use

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');

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');

Examples

Internal Scrolling

Internal scrolling is used when the table is inside of a container smaller than itself.
This also demonstrates the reflow method. When a DOM modification causes the table's location to change, you must call this method on the table.

Code

var $demo1 = $('table.demo1');
$demo1.floatThead({
	scrollingTop: 41,
	scrollContainer: function($table){
		return $table.closest('.wrapper');
	}
});
$('a#change-dom').click(function(){ //click to remove
	$(this).parent().hide();
	//DOM has changed. must reflow floatThead
	$demo1.floatThead('reflow');
});

There might be some table controls here or something.. Click to remove

Page Scrolling

Page scrolling isused when you have a large table that takes up the whole screen.
Code

$('table.demo2').floatThead({
	scrollingTop: 41,
	// I need this offset because i dont 
	// want the table header to overlap 
	//my site navigation
	useAbsolutePositioning: false 
	// absolutePositioning is better for 
	//highly dynamic sites 
	//(which this is not)
});

Known Issues

Issues list is pulled from github

There are no issues! Yey!

Download

This plugin is in beta.
You can grab the latest non-minified version at github
and a minified version here (4.6K Minified version can lag behind latest version!!)
To report issues, visit the project's github repository page.

NOTE: The code included on this page is used for developing new features and fixing bugs. Use the code in github.

TODO:

fix spellign!
stablize code
cleanup code