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. Now version 1.1!

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 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 (new)
  • Dynamic creation of tables (new)
  • 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:

Defining the 'tfoot' section is optional from the view point of DataTables, and if defined will be used in the same manner that 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.
int : iDefaultSortIndex
If sorting is enabled, then DataTables will perform a first pass sort on initialisation. You can define which column the sort is performed upon with this variable. Note that this index is defined by the data columns on the original table, and starts counting at zero.
Default: 0.
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
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. int : Data row
2. int : Column row
3. array array : Data array for the whole table [row][column].
Return parameter:
string
function : fnSort
Custom sorting function which can be used for sorting data types out with the three standard types DataTables accept by default. This function has all the same requirements as the 'sort( function() )' inner function in Javascript.
Default: void - sort based on the column data type.
string : sType
The type allows you to specify how the data for this column will be sorted. Three types (string, numeric and date) 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' or 'date'
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 : sInfoEmtpy
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: ""

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.
Return parameter:
void
function : fnSort
Sort the table on a particular column.
Input parameters:
1. int : Column to sort on. Note that this is the column index of the original table (this only matters if you are hiding certain columns).
Return parameter:
void
function : fnAddRow
Add a new row 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.
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 : 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

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
Information: Inserted before the table
Change display length *_length
Information: Inserted before the table
Filter *_filter
Information: Inserted before the table
Pagination *_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
Information: Inserted after the table
Sorting sorting_asc
sorting_desc
Information: Applied to the TH in the table header
General *_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

The links below show how you can use some of the features of DataTables with live examples and the code used.

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.

Donate

If you find the software on this site useful, and/or enjoy using it, please consider making a donation so I can keep developing this software.