For tabular display of data in HTML there is nothing quite like the reliable table tag. With a little bit of Javascript magic, tables can be transformed from a static display to a dynamic and interesting information tool. I have been experimenting recently with building a tables plugin for jQuery.

Please note that DataTables now has it's own web-site! Please visit DataTables.net for up-to-date software and information

Introduction

I've been working on a project recently which requires tabular information to be easily accessible, with potentially large amounts of data being presented to the end user at any one particular point. For the project I decided that I would take the opportunity to experiment with the jQuery library, which is simply outstanding. I assumed that there would be several table plugins for jQuery, and indeed there are, but none that quite fits what I require, so I decided to have a go at writing a jQuery plugin. The result is my DataTables plugin.

DataTables provides the following core features:

  • Variable length pagination
  • On-the-fly filtering
  • Sorting with data type detection
  • Smart handling of column widths
  • Themeable by CSS
  • Hidden columns
  • Extremely customisable and flexible
  • Fully internationalisable
    UK, French, German and Spanish translations provided
  • Dynamic creation of tables
  • Multi-column sorting - new in 1.3!
  • Custom DOM positioning - new in 1.3!
  • Single column filtering - new in 1.3!
  • Alternative pagination types - new in 1.3!
  • It's free!

DataTables operates on the principle of progressive enhancement. When you initialise the jQuery.dataTable object, information about the table is read directly from the HTML page. In combination with the default values for the features in DataTables, this makes it very easy to integrate directly into your web-site or web-application.

Example

Let's dive straight into an example to see DataTables in action. The following table is the example browser support table from Conditional-CSS:

Rendering engine Browser Platform(s) Engine version CSS grade
Trident Internet Explorer 4.0 Win 95+ 4 X
Trident Internet Explorer 5.0 Win 95+ 5 C
Trident Internet Explorer 5.5 Win 95+ 5.5 A
Trident Internet Explorer 6 Win 98+ 6 A
Trident Internet Explorer 7 Win XP SP2+ 7 A
Trident AOL desktop Win XP 6 A
Gecko Firefox 1.0 Win 98+ / OSX.2+ 1.7 A
Gecko Firefox 1.5 Win 98+ / OSX.2+ 1.8 A
Gecko Firefox 2.0 Win 98+ / OSX.2+ 1.8 A
Gecko Firefox 3.0 Win 2k+ / OSX.3+ 1.9 A
Gecko Camino 1.0 OSX.2+ 1.8 A
Gecko Camino 1.5 OSX.3+ 1.8 A
Gecko Netscape 7.2 Win 95+ / Mac OS 8.6-9.2 1.7 A
Gecko Netscape Browser 8 Win 98SE+ 1.7 A
Gecko Netscape Navigator 9 Win 98+ / OSX.2+ 1.8 A
Gecko Mozilla 1.0 Win 95+ / OSX.1+ 1 A
Gecko Mozilla 1.1 Win 95+ / OSX.1+ 1.1 A
Gecko Mozilla 1.2 Win 95+ / OSX.1+ 1.2 A
Gecko Mozilla 1.3 Win 95+ / OSX.1+ 1.3 A
Gecko Mozilla 1.4 Win 95+ / OSX.1+ 1.4 A
Gecko Mozilla 1.5 Win 95+ / OSX.1+ 1.5 A
Gecko Mozilla 1.6 Win 95+ / OSX.1+ 1.6 A
Gecko Mozilla 1.7 Win 98+ / OSX.1+ 1.7 A
Gecko Mozilla 1.8 Win 98+ / OSX.1+ 1.8 A
Gecko Seamonkey 1.1 Win 98+ / OSX.2+ 1.8 A
Gecko Epiphany 2.20 Gnome 1.8 A
Webkit Safari 1.2 OSX.3 125.5 A
Webkit Safari 1.3 OSX.3 312.8 A
Webkit Safari 2.0 OSX.4+ 419.3 A
Webkit Safari 3.0 OSX.4+ 522.1 A
Webkit OmniWeb 5.5 OSX.4+ 420 A
Webkit iPod Touch / iPhone iPod 420.1 A
Webkit S60 S60 413 A
Presto Opera 7.0 Win 95+ / OSX.1+ - A
Presto Opera 7.5 Win 95+ / OSX.2+ - A
Presto Opera 8.0 Win 95+ / OSX.2+ - A
Presto Opera 8.5 Win 95+ / OSX.2+ - A
Presto Opera 9.0 Win 95+ / OSX.3+ - A
Presto Opera 9.2 Win 88+ / OSX.3+ - A
Presto Opera 9.5 Win 88+ / OSX.3+ - A
Presto Opera for Wii Wii - A
Presto Nokia N800 N800 - A
Presto Nintendo DS browser Nintendo DS 8.5 C/A1
KHTML Konqureror 3.1 KDE 3.1 3.1 C
KHTML Konqureror 3.3 KDE 3.3 3.3 A
KHTML Konqureror 3.5 KDE 3.5 3.5 A
Tasman Internet Explorer 4.5 Mac OS 8-9 - X
Tasman Internet Explorer 5.1 Mac OS 7.6-9 1 C
Tasman Internet Explorer 5.2 Mac OS 8-X 1 C
Misc NetFront 3.1 Embedded devices - C
Misc NetFront 3.4 Embedded devices - A
Misc Dillo 0.8 Embedded devices - X
Misc Links Text only - X
Misc Lynx Text only - X
Misc IE Mobile Windows Mobile 6 - C
Misc PSP browser PSP - C
Other browsers All others - - U

Prerequisites

In order for DataTables to be able to function correctly, the HTML for the target table must be laid out in a well formed manner with the 'thead' and 'tbody' sections declared. For example:


			...
		
			...
		
		...
	

	
		

			Column 1
			Column 2

	
	
		

			Data 1
			Data 2

Defining the 'tfoot' section is optional from the view point of DataTables, and if defined will be used in a similar manner to how thead is used, with the exception of being able to use them to sort data.

Javascript initialisation

Configuration of DataTables is done by passing an object to the dataTable() function. This is where the majority of code interaction with DataTables will take place. There is a wide range of options available, and are documented below.
Initialisation object properties
bool : bPaginate
Enable or disable pagination.
Default: true.
bool : bLengthChange
Allows the end user to select the size of a formatted page from a select menu (sizes are 10, 25, 50 and 100). Requires pagination (bPaginate).
Default: true.
bool : bFilter
Enable or disable filtering of data. Note that filtering in DataTables is smart in that it allows the end user to input multiple words (space separated) and will match a row containing those words, even if not in the order that was specified (this allow matching across multiple columns).
Default: true.
bool : bSort
Enable or disable sorting of columns. Sorting of individual columns can be disabled by the "bSortable" option for each column.
Default: true.
bool : bInfo
Enable or disable the table information display. This shows information about the data that is currently visible on the page, including information about filtered data if that action is being performed.
Default: true.
bool : bProcessing
Enable or disable the display of a 'processing' indicator when the table is being processed (e.g. a sort). This is particularly useful for tables with large amounts of data where it can take a noticeable amount of time to sort the entries.
Default: true.
bool : bAutoWidth
Enable or disable automatic column width calculation. This can be disabled as an optimisation (it takes some time to calculate the widths) if the tables widths are passed in using aoColumns.
Default: true.
int : iDisplayLength
Number of rows to display on a single page when using pagination. If feature enabled (bLengthChange) then the end user will be able to over-ride this to a custom setting using a pop-up menu.
Default: 10.
array array[int,string] : aaSorting
If sorting is enabled, then DataTables will perform a first pass sort on initialisation. You can define which column(s) the sort is performed upon, and the sorting direction, with this variable. For each column an array must be specified where the first element is an int of the data index, and the second is 'asc' or 'desc' for the sorting direction Example of multiple column sorting: "[[0,'asc'], [1,'asc']]".
Default: [[0,'asc']].
string : sPaginationType
DataTables features two different built-in pagination interaction methods ('two_button' or 'full_numbers') which present different page controls to the end user. Further methods can be added using the API (see below).
Default: 'two_button'.
string : sDom
This initialisation variable allows you to specify exactly where in the DOM you want DataTables to inject the various controls it adds to the page (for example you might want the pagination controls at the top of the table). DIV elements (with or without a custom class) can also be added to aid styling. The follow syntax is used:
  • l - Length changing
  • f - Filtering input
  • t - The table!
  • i - Information
  • p - Pagination
  • r - pRocessing
  • < and > - div elements
  • <"class" and > - div with a class
  • Examples: <"wrapper"flipt>, ip>
Default: 'lfrtip'.
array stings : asStripClasses
An array of CSS classes that should be applied to displayed rows. This array may be of any length, and DataTables will apply each class sequentially, looping when required.
Default: [ 'odd', 'even' ]
function : fnRowCallback
This function allows you to 'post process' each row after it have been generated for each table draw, but before it is rendered on screen. This function might be used for setting the row class name etc.
Default: void.
Input parameters:
1. node : "TR" element for the current row
2. array strings : Raw data array for this row (as derived from the original HTML)
3. int : The display index for the current table draw
Return parameter:
node : "TR" element for the current row
function : fnDrawCallback
This function is called on every 'draw' event, and allows you to dynamically modify any aspect you want about the created DOM. This is useful for adding event handlers etc after a draw.
Default: void.
Input parameters:
void
Return parameter:
void
function : fnHeaderCallback
This function is called on every 'draw' event, and allows you to dynamically modify the header row. This can be used to calculate and display useful information about the table.
Default: void.
Input parameters:
1. node : "TR" element for the header
2. array array strings : Full table data (as derived from the original HTML)
3. int : Index for the current display starting point in the data array
4. int : Index for the current display ending point in the data array
Return parameter:
void
function : fnFooterCallback
Identical to fnHeaderCallback() but for the table footer this function allows you to modify the table footer on every 'draw' even.
Default: void.
Input parameters:
1. node : "TR" element for the header
2. array array strings : Full table data (as derived from the original HTML)
3. int : Index for the current display starting point in the data array
4. int : Index for the current display ending point in the data array
Return parameter:
void
array objects : aoColumns
Although DataTables can obtain information about the table directly from the DOM, you may wish to given DataTables specific instructions for each individual column. This can be done with the parameters given in the object for each column. If specified, then the length of this array must be equal to the number of columns in the original HTML table. Use 'null' where you wish to use only the default values. Parameters: Each object in the array can have the parameters shown below or may be 'null'.
Default: Null - Obtain data directly from what is available in the DOM. Automatic detection of the data type will be performed. The defaults shown for the parameters in the aoColumns objects array will be used as the default for each specific option.
aoColumns objects
bool : bVisible
Enable or disable the display of this column.
Default: true
bool : bSearchable
Enable or disable filtering on the data in this column.
Default: true
bool : bSortable
Enable or disable sorting on this column.
Default: true
string : sTitle
The title of this column.
Default: Derived from the 'TH' value for this column in the original HTML table.
string : sWidth
Defining the width of the column, this parameter may take any CSS value (3em, 20px etc). DataTables applys 'smart' widths to columns which have not been given a specific width through this interface ensuring that the table remains readable.
Default: Automatic
string : sClass
Class to give to each cell in this column
Default: ''
function : fnRender
Custom display function that will be called for the display of each cell in this column.
Default: void - use the raw data
Input parameters:
1. Object with the following parameters:
   1.1. int : iDataRow - Data row
   1.2. int : iDataColumn - Column row
   1.3. array array : aData - Data array for the whole table [row][column].
Return parameter:
string
string : sType
The type allows you to specify how the data for this column will be sorted. Four types (string, numeric, date and html (will strip HTML tags before sorting)) are currently available. Note that only date formats understood by Javascript's Date() object will be accepted as type date. For example: "Mar 26, 2008 5:03 PM".
Default: Auto-detect from raw data.
Values: 'string', 'numeric', 'date' or 'html'
string : iDataSort
The column index (starting from 0!) that you wish a sort to be performed upon when this column is selected for sorting. This can be used for sorting on hidden columns for example.
Default: Auto-detect from current column.
Value: integer
object : oLanguage
The language information presented by DataTables can be completely altered for internationalisation (or localisation) using the properties of this object. Note that all strings in the following may contain HTML tags (i.e. you can include images etc if you so wish in them).
oLanguage parameters
string : sProcessing
Text which is displayed when the table is processing a user action (usually a sort command or similar).
Default: "Processing..."
string : sLengthMenu
Detail the action that will be taken when the drop down menu for the pagination length option is changed. The '_MENU_' variable is replaced with a default select list of 10, 25, 50 and 100, and can be replaced with a custom select box if required.
Default: "Show _MENU_ entries"
string : sZeroRecords
Text shown inside the table records when the is no information to be displayed. This includes when the table is filtered to zero records.
Default: "No matching records found"
string : sInfo
This string gives information to the end user about the information that is current on display on the page. The _START_, _END_ and _TOTAL_ variables are all dynamically replaced as the table display updates, and can be freely moved or removed as the language requirements change.
Default: "Showing _START_ to _END_ of _TOTAL_ entries"
string : sInfoEmpty
Display information string for when the table is empty. Typically the format of this string should match sInfo.
Default: "Showing 0 to 0 of 0 entries"
string : sInfoFiltered
When a user filters the information in a table, this string is appended to the information (sInfo) to give an idea of how strong the filtering is. The variable _MAX_ is dynamically updated.
Default: "(filtered from _MAX_ total entries)"
string : sInfoPostFix
If can be useful to append extra information to the info string at times, and this variable does exactly that. This information will be appended to the sInfo (sInfoEmpty and sInfoFiltered in whatever combination they are being used) at all times.
Default: ""
string : sSearch
Details the actions that will be taken when the user types into the filtering input text box.
Default: "Search:"
string : sUrl
All of the language information can be stored in a file on the server-side, which DataTables will look up if this parameter is passed. It must store the URL of the language file, which is in a JSON format, and the object has the same properties as the oLanguage object in the initialiser object (i.e. the above parameters). Please refer to one of the example language files to see how this works in action.
Default: ""
string : oPaginate.sFirst
Text to use when using the 'full_buttons' type of pagination for the button to take the user to the first page.
Default: "First"
string : oPaginate.sPrevious
Text to use when using the 'full_buttons' type of pagination for the button to take the user to the previous page.
Default: "Previous"
string : oPaginate.sNext
Text to use when using the 'full_buttons' type of pagination for the button to take the user to the next page
Default: "Next"
string : oPaginate.sLast
Text to use when using the 'full_buttons' type of pagination for the button to take the user to the last page
Default: "Last"

Javascript API

Although most of the time your Javascript interaction with DataTables will be done using the initialisation object as described above, there are times at which you might find it useful to have some external control of the table. The following functions are available from the jQuery.dataTable object:

jQuery.dataTable object
function : fnDraw
Redraw the table.
Input parameters:
void
Return parameter:
void
function : fnFilter
Filter the table based on the string input. This will automatically redraw the table.
Input parameters:
1. string : String to filter on.
2. int (optional): Column to limit filtering to.
Return parameter:
void
function : fnSort
Sort the table.
Input parameters:
1. array array [int, string] : Multi-column sorting array.
Return parameter:
void
function : fnAddData
Add a new row or multiple rows to the table. Redraw is not automatic on this function.
Input parameters:
1. array strings : The data to be added to the table. This array must be of the same length as the number of columns on the original HTML table.
or
1. array array strings : 2D array of data to be added to the table. The inner array must be of the same length as the number of columns on the original HTML table.
Return parameter:
int : 0 okay, 1 error
function : fnDeleteRow
Remove a row from the table. Redraw is not automatic on this function.
Input parameters:
1. int : Index of the row to delete.
Return parameter:
void
function : fnClearTable
Empty the entire table of current row information.
Input parameters:
void
Return parameter:
void
function : fnOpen
This function will place a new row directly after a row which is currently on display on the page, with the HTMl contents that is passed into the function. This can be used, for example, to ask for confirmation that a particular record should be deleted.
Input parameters:
1. node - the table row to 'open'
2. string - the HTML to put into the row
3. string - class to give the new row
Return parameter:
void
function : fnClose
The exact opposite of 'opening' a row, this function will close any rows which are currently 'open'.
Input parameters:
void
Return parameter:
void
function : fnDecrement
If you are using fnOpen/fnClose to delete records from a table and are displaying an index of the records on display, fnDecrement can be utilised to keep the index up-to-date based on the deleted row. All indexes greater that the deleted row are decremented by one.
Input parameters:
1. int - Index at which to start decrementing
2. int - The column the data is stored in which should be decremented.
Return parameter:
void
function : fnClearTable
Delete all of the data contained inside a table.
Input parameters:
void
Return parameter:
void
function : fnSettings
Access the internal DataTables parameters for a table.
Input parameters:
void
Return parameter:
void

Plugins

As flexible as DataTables is, there may be times when you wish to customise certain aspects of the display. Currently DataTables provides plugin support for additional sorting function and new pagination controls.

To add a new sort function to DataTables you need to attach your function to the object $.fn.dataTableExt.oSort. For example, the following adds a case sensitive sorting function of type 'string-case':

jQuery.fn.dataTableExt.oSort['string-case-asc']  = function(x,y) {
	return ((x < y) ? -1 : ((x > y) ?  1 : 0));
};

jQuery.fn.dataTableExt.oSort['string-case-desc'] = function(x,y) {
	return ((x < y) ?  1 : ((x > y) ? -1 : 0));
};

For each sort method you want to add, you need to add both an ascending method and a descending method. Each function should take two inputs, as you would expect from a Javascript sort function.

You can also add a new pagination control mechanism to DataTables by extending the object $.fn.dataTableExt.oPagination. Each new parameter to the object should include two methods (fnInit and fnDraw). I strongly suggest that you look at the DataTables source code to see how I've implement the two built-in types.

If you have created any plugins for DataTables please get in touch with me and I'll include a link to the plugin here.

CSS Styles

Providing the range of features that DataTables does is great, but you will also wish to style the table and the HTML that DataTables adds to the document. The key to this is the 'id' attribute that you give the table in question. Any HTML added to the page will have this id with a postfix (e.g. _info). The following ID's and classes will be applied:

Feature ID Class
Processing indicator *_processing dataTables_processing
Information: Inserted before the table
Change display length *_length dataTables_length
Information: Inserted before the table
Filter *_filter dataTables_filter
Information: Inserted before the table
Pagination *_paginate dataTables_paginate
Information: Inserted after the table
Pagination *_previous paginate_disabled_previous
paginate_enabled_previous
Pagination *_next paginate_disabled_next
paginate_enabled_next
Display information *_info dataTables_info
Information: Inserted after the table
Sorting sorting_asc
sorting_desc
Information: Applied to the TH in the table header
General *_wrapper dataTables_wrapper
Information: General wrapper div element around the table

Download and license

DataTables is dual licensed under the GPL v2 and a BSD style license. You can download DataTables below:

Article image

Demos

Basic initialisation

Advanced initialisation

API

Support / information

The following browsers are supported with DataTables:

  • Internet Explorer 6+
  • Firefox 2+
  • Safari 3+
  • Opera 9.2+

Like all software there might be the odd bug or inconsistency in DataTables which you stumble across. If you do find any, please report them to me. Likewise, please get in touch if you have any ideas for enhancements which could be made and improve DataTables or if you want more information.