Class: DataTable

DataTables v1.9.0.beta.1 documentation

Navigation

Hiding private elements (toggle)
Showing extended elements (toggle)
new DataTable(oInit)

DataTables is a plug-in for the jQuery Javascript library. It is a highly flexible tool, based upon the foundations of progressive enhancement, which will add advanced interaction controls to any HTML table. For a full list of features please refer to DataTables.net.

Note that the DataTable object is not a global variable but is aliased to jQuery.fn.DataTable and jQuery.fn.dataTable through which it may be accessed.

Constructor

Parameters:
Name Type Attributes Default Description
1
oInitobjectOptional{}Configuration object for DataTables. Options are defined by DataTable.defaults
Examples:
   // Basic initialisation
   $(document).ready( function {
     $('#example').dataTable();
   } );
 
 
   // Initialisation with configuration options - in this case, disable
   // pagination and sorting.
   $(document).ready( function {
     $('#example').dataTable( {
       "bPaginate": false,
       "bSort": false 
     } );
   } );

Requires

  • module:jQuery

Summary

Namespaces

defaults
Initialisation options that can be given to DataTables at initialisation time.
ext
Extension object for DataTables that is used to provide all extension options. See DataTable.models.ext for full information about the extension object. Note that the DataTable.ext object is aliased to jQuery.fn.dataTableExt through which is may be accessed and manipulated, or jQuery.fn.dataTable.ext.
models
Object models container, for the various models that DataTables has available to it. These models define the objects that are used to hold the active state and configuration of the table.
oApi
Reference to internal functions for use by plug-in developers. Note that these methods are references to internal functions and are considered to be private. If you use these methods, be aware that they are liable to change between versions (check the upgrade notes).

Properties

<static> version :string
Version string for plug-ins to check compatibility. Allowed format is a.b.c.d.e where: a:int, b:int, c:int, d:string(dev|beta), e:int. d and e are optional

Methods

$(sSelector, oOpts) → {object}
Perform a jQuery selector action on the table's TR elements (from the tbody) and return the resulting jQuery object.
fnAddData(mData, bRedraw) → {array}
Add a single new row or multiple rows of data to the table. Please note that this is suitable for client-side processing only - if you are using server-side processing (i.e. "bServerSide": true), then to add data, you must add it to the data source, i.e. the server-side, through an Ajax call.
fnAdjustColumnSizing(bRedraw)
This function will make DataTables recalculate the column sizes, based on the data contained in the table and the sizes applied to the columns (in the DOM, CSS or through the sWidth parameter). This can be useful when the width of the table's parent element changes (for example a window resize).
fnClearTable(bRedraw)
Quickly and simply clear a table
fnClose(nTr) → {int}
The exact opposite of 'opening' a row, this function will close any rows which are currently 'open'.
fnDeleteRow(mTarget, fnCallBack, bRedraw) → {array}
Remove a row for the table
fnDestroy(bRemove)
Restore the table to it's original state in the DOM by removing all of DataTables enhancements, alterations to the DOM structure of the table and event listeners.
fnDraw(bComplete)
Redraw the table
fnFilter(sInput, iColumn, bRegex, bSmart, bShowGlobal, bCaseInsensitive)
Filter the input based on data
fnGetData(mRow, iCol) → {array|string}
Return an array with the data which is used to make up the table or string if both row and column are given
fnGetNodes(iRow) → {array|node}
Get an array of the TR nodes that are used in the table's body. Note that you will typically want to use the '$' API method in preference to this as it is more flexible.
fnGetPosition(nNode) → {int}
Get the array indexes of a particular cell from it's DOM element and column index including hidden columns
fnIsOpen(nTr) → {boolean}
Check to see if a row is 'open' or not.
fnOpen(nTr, mHtml, sClass) → {node}
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.
fnPageChange(mAction, bRedraw)
Change the pagination - provides the internal logic for pagination in a simple API function. With this function you can have a DataTables table go to the next, previous, first or last pages.
fnSetColumnVis(iCol, bShow, bRedraw)
Show a particular column
fnSettings() → {object}
Get the settings for a particular table for external manipulation
fnSort(iCol)
Sort the table by a particular row
fnSortListener(nNode, iColumn, fnCallback)
Attach a sort listener to an element for a given column
fnUpdate(mData, mRow, iColumn, bRedraw, bAction) → {int}
Update a table cell or row - this method will accept either a single value to update the cell with, an array of values with one element for each column or an object in the same format as the original data source. The function is self-referencing in order to make the multi column updates easier.
fnVersionCheck(sVersion) → {boolean}
Provide a common method for plug-ins to check the version of DataTables being used, in order to ensure compatibility.

Events

draw
Draw event, fired whenever the table is redrawn on the page, at the same point as fnDrawCallback. This may be useful for binding events or performing calculations when the table is altered at all.
filter
Filter event, fired when the filtering applied to the table (using the build in global global filter, or column filters) is altered.
page
Page change event, fired when the paging of the table is altered.
sort
Sort event, fired when the sorting applied to the table is altered.
xhr
Ajax (XHR) event, fired whenever an Ajax request is completed from a request to made to the server for new data (note that this trigger is called in fnServerData, if you override fnServerData and which to use this event, you need to trigger it in you success function).

Details

Properties

<static> version :string

Version string for plug-ins to check compatibility. Allowed format is a.b.c.d.e where: a:int, b:int, c:int, d:string(dev|beta), e:int. d and e are optional

Methods

$(sSelector, oOpts) → {object}

Perform a jQuery selector action on the table's TR elements (from the tbody) and return the resulting jQuery object.

Parameters:
Name Type Attributes Default Description
1
sSelectorstringjQuery selector
2
oOptsobjectOptionalOptional parameters for modifying the rows to be included
oOpts.filterstring<optional>
noneSelect TR elements that meet the current filter criterion ("applied") or all TR elements (i.e. no filter).
oOpts.orderstring<optional>
currentOrder of the TR elements in the processed array. Can be either 'current', whereby the current sorting of the table is used, or 'original' whereby the original order the data was read into the table is used.
oOpts.pagestring<optional>
allLimit the selection to the currently displayed page ("current") or not ("all"). If 'current' is given, then order is assumed to be 'current' and filter is 'applied', regardless of what they might be given as.
Returns:

jQuery object, filtered by the given selector.

Examples:
   $(document).ready(function() {
     var oTable = $('#example').dataTable();

     // Highlight every second row
     oTable.$('tr:odd').css('backgroundColor', 'blue');
   } );

 
   $(document).ready(function() {
     var oTable = $('#example').dataTable();

     // Filter to rows with 'Webkit' in them, add a background colour and then
     // remove the filter, thus highlighting the 'Webkit' rows only.
     oTable.fnFilter('Webkit');
     oTable.$('tr', {"filter": "applied"}).css('backgroundColor', 'blue');
     oTable.fnFilter('');
   } );
fnAddData(mData, bRedraw) → {array}

Add a single new row or multiple rows of data to the table. Please note that this is suitable for client-side processing only - if you are using server-side processing (i.e. "bServerSide": true), then to add data, you must add it to the data source, i.e. the server-side, through an Ajax call.

Parameters:
Name Type Attributes Default Description
1
mDataarray | objectThe data to be added to the table. This can be:
  • 1D array of data - add a single row with the data provided
  • 2D array of arrays - add multiple rows in a single call
  • object - data object when using mDataProp
  • array of objects - multiple data objects when using mDataProp
2
bRedrawboolOptionaltrueredraw the table or not
Returns:

An array of integers, representing the list of indexes in aoData (DataTable.models.oSettings) that have been added to the table.

Example:
   // Global var for counter
   var giCount = 2;
   
   $(document).ready(function() {
     $('#example').dataTable();
   } );
   
   function fnClickAddRow() {
     $('#example').dataTable().fnAddData( [
       giCount+".1",
       giCount+".2",
       giCount+".3",
       giCount+".4" ]
     );
       
     giCount++;
   }
fnAdjustColumnSizing(bRedraw)

This function will make DataTables recalculate the column sizes, based on the data contained in the table and the sizes applied to the columns (in the DOM, CSS or through the sWidth parameter). This can be useful when the width of the table's parent element changes (for example a window resize).

Parameters:
Name Type Attributes Default Description
1
bRedrawbooleanOptionaltrueRedraw the table or not, you will typically want to
Example:
   $(document).ready(function() {
     var oTable = $('#example').dataTable( {
       "sScrollY": "200px",
       "bPaginate": false
     } );
     
     $(window).bind('resize', function () {
       oTable.fnAdjustColumnSizing();
     } );
   } );
fnClearTable(bRedraw)

Quickly and simply clear a table

Parameters:
Name Type Attributes Default Description
1
bRedrawboolOptionaltrueredraw the table or not
Example:
   $(document).ready(function() {
     var oTable = $('#example').dataTable();
     
     // Immediately 'nuke' the current rows (perhaps waiting for an Ajax callback...)
     oTable.fnClearTable();
   } );
fnClose(nTr) → {int}

The exact opposite of 'opening' a row, this function will close any rows which are currently 'open'.

Parameters:
Name Type Attributes Default Description
1
nTrnodethe table row to 'close'
Returns:

0 on success, or 1 if failed (can't find the row)

Example:
   $(document).ready(function() {
     var oTable;
     
     // 'open' an information row when a row is clicked on
     $('#example tbody tr').click( function () {
       if ( oTable.fnIsOpen(this) ) {
         oTable.fnClose( this );
       } else {
         oTable.fnOpen( this, "Temporary row opened", "info_row" );
       }
     } );
     
     oTable = $('#example').dataTable();
   } );
fnDeleteRow(mTarget, fnCallBack, bRedraw) → {array}

Remove a row for the table

Parameters:
Name Type Attributes Default Description
1
mTargetmixedThe index of the row from aoData to be deleted, or the TR element you want to delete
2
fnCallBackfunction | nullOptionalCallback function
3
bRedrawboolOptionaltrueRedraw the table or not
Returns:

The row that was deleted

Example:
   $(document).ready(function() {
     var oTable = $('#example').dataTable();
     
     // Immediately remove the first row
     oTable.fnDeleteRow( 0 );
   } );
fnDestroy(bRemove)

Restore the table to it's original state in the DOM by removing all of DataTables enhancements, alterations to the DOM structure of the table and event listeners.

Parameters:
Name Type Attributes Default Description
1
bRemovebooleanOptionalfalseCompletely remove the table from the DOM
Example:
   $(document).ready(function() {
     // This example is fairly pointless in reality, but shows how fnDestroy can be used
     var oTable = $('#example').dataTable();
     oTable.fnDestroy();
   } );
fnDraw(bComplete)

Redraw the table

Parameters:
Name Type Attributes Default Description
1
bCompleteboolOptionaltrueRe-filter and resort (if enabled) the table before the draw.
Example:
   $(document).ready(function() {
     var oTable = $('#example').dataTable();
     
     // Re-draw the table - you wouldn't want to do it here, but it's an example :-)
     oTable.fnDraw();
   } );
fnFilter(sInput, iColumn, bRegex, bSmart, bShowGlobal, bCaseInsensitive)

Filter the input based on data

Parameters:
Name Type Attributes Default Description
1
sInputstringString to filter the table on
2
iColumnint | nullOptionalColumn to limit filtering to
3
bRegexboolOptionalfalseTreat as regular expression or not
4
bSmartboolOptionaltruePerform smart filtering or not
5
bShowGlobalboolOptionaltrueShow the input global filter in it's input box(es)
6
bCaseInsensitiveboolOptionaltrueDo case-insensitive matching (true) or not (false)
Example:
   $(document).ready(function() {
     var oTable = $('#example').dataTable();
     
     // Sometime later - filter...
     oTable.fnFilter( 'test string' );
   } );
fnGetData(mRow, iCol) → {array|string}

Return an array with the data which is used to make up the table or string if both row and column are given

Parameters:
Name Type Attributes Default Description
1
mRowmixedOptionalThe TR row element to get the data for, or the aoData internal index (mapped to the TR element)
2
iColintOptionalOptional column index that you want the data of
Returns:

If mRow is undefined, then the data for all rows is returned. If mRow is defined, just data for that row, and is iCol is defined, only data for the designated cell is returned.

Example:
   $(document).ready(function() {
     $('#example tbody td').click( function () {
       // Get the position of the current data from the node
       var aPos = oTable.fnGetPosition( this );
       
       // Get the data array for this row
       var aData = oTable.fnGetData( this.parentNode );
       
       // Update the data array and return the value
       aData[ aPos[1] ] = 'clicked';
       this.innerHTML = 'clicked';
     } );
     
     // Init DataTables
     oTable = $('#example').dataTable();
   } );
fnGetNodes(iRow) → {array|node}

Get an array of the TR nodes that are used in the table's body. Note that you will typically want to use the '$' API method in preference to this as it is more flexible.

Parameters:
Name Type Attributes Default Description
1
iRowintOptionalOptional row index for the TR element you want
Returns:

If iRow is undefined, returns an array of all TR elements in the table's body, or iRow is defined, just the TR element requested.

Example:
   $(document).ready(function() {
     var oTable = $('#example').dataTable();
     
     // Get the nodes from the table
     var nNodes = oTable.fnGetNodes( );
   } );
fnGetPosition(nNode) → {int}

Get the array indexes of a particular cell from it's DOM element and column index including hidden columns

Parameters:
Name Type Attributes Default Description
1
nNodenodethis can either be a TR, TD or TH in the table's body
Returns:

If nNode is given as a TR, then a single index is returned, or if given as a cell, an array of [row index, column index (visible)] is given.

Example:
   $(document).ready(function() {
     $('#example tbody td').click( function () {
       // Get the position of the current data from the node
       var aPos = oTable.fnGetPosition( this );
       
       // Get the data array for this row
       var aData = oTable.fnGetData( aPos[0] );
       
       // Update the data array and return the value
       aData[ aPos[1] ] = 'clicked';
       this.innerHTML = 'clicked';
     } );
     
     // Init DataTables
     oTable = $('#example').dataTable();
   } );
fnIsOpen(nTr) → {boolean}

Check to see if a row is 'open' or not.

Parameters:
Name Type Attributes Default Description
1
nTrnodethe table row to check
Returns:

true if the row is currently open, false otherwise

Example:
   $(document).ready(function() {
     var oTable;
     
     // 'open' an information row when a row is clicked on
     $('#example tbody tr').click( function () {
       if ( oTable.fnIsOpen(this) ) {
         oTable.fnClose( this );
       } else {
         oTable.fnOpen( this, "Temporary row opened", "info_row" );
       }
     } );
     
     oTable = $('#example').dataTable();
   } );
fnOpen(nTr, mHtml, sClass) → {node}

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.

Parameters:
Name Type Attributes Default Description
1
nTrnodeThe table row to 'open'
2
mHtmlstring | node | jQueryThe HTML to put into the row
3
sClassstringClass to give the new TD cell
Returns:

The row opened

Example:
   $(document).ready(function() {
     var oTable;
     
     // 'open' an information row when a row is clicked on
     $('#example tbody tr').click( function () {
       if ( oTable.fnIsOpen(this) ) {
         oTable.fnClose( this );
       } else {
         oTable.fnOpen( this, "Temporary row opened", "info_row" );
       }
     } );
     
     oTable = $('#example').dataTable();
   } );
fnPageChange(mAction, bRedraw)

Change the pagination - provides the internal logic for pagination in a simple API function. With this function you can have a DataTables table go to the next, previous, first or last pages.

Parameters:
Name Type Attributes Default Description
1
mActionstring | intPaging action to take: "first", "previous", "next" or "last" or page number to jump to (integer), note that page 0 is the first page.
2
bRedrawboolOptionaltrueRedraw the table or not
Example:
   $(document).ready(function() {
     var oTable = $('#example').dataTable();
     oTable.fnPageChange( 'next' );
   } );
fnSetColumnVis(iCol, bShow, bRedraw)

Show a particular column

Parameters:
Name Type Attributes Default Description
1
iColintThe column whose display should be changed
2
bShowboolShow (true) or hide (false) the column
3
bRedrawboolOptionaltrueRedraw the table or not
Example:
   $(document).ready(function() {
     var oTable = $('#example').dataTable();
     
     // Hide the second column after initialisation
     oTable.fnSetColumnVis( 1, false );
   } );
fnSettings() → {object}

Get the settings for a particular table for external manipulation

Returns:

DataTables settings object. See DataTable.models.oSettings

Example:
   $(document).ready(function() {
     var oTable = $('#example').dataTable();
     var oSettings = oTable.fnSettings();
     
     // Show an example parameter from the settings
     alert( oSettings._iDisplayStart );
   } );
fnSort(iCol)

Sort the table by a particular row

Parameters:
Name Type Attributes Default Description
1
iColintthe data index to sort on. Note that this will not match the 'display index' if you have hidden data entries
Example:
   $(document).ready(function() {
     var oTable = $('#example').dataTable();
     
     // Sort immediately with columns 0 and 1
     oTable.fnSort( [ [0,'asc'], [1,'asc'] ] );
   } );
fnSortListener(nNode, iColumn, fnCallback)

Attach a sort listener to an element for a given column

Parameters:
Name Type Attributes Default Description
1
nNodenodethe element to attach the sort listener to
2
iColumnintthe column that a click on this node will sort on
3
fnCallbackfunctionOptionalcallback function when sort is run
Example:
   $(document).ready(function() {
     var oTable = $('#example').dataTable();
     
     // Sort on column 1, when 'sorter' is clicked on
     oTable.fnSortListener( document.getElementById('sorter'), 1 );
   } );
fnUpdate(mData, mRow, iColumn, bRedraw, bAction) → {int}

Update a table cell or row - this method will accept either a single value to update the cell with, an array of values with one element for each column or an object in the same format as the original data source. The function is self-referencing in order to make the multi column updates easier.

Parameters:
Name Type Attributes Default Description
1
mDataobject | array | stringData to update the cell/row with
2
mRownode | intTR element you want to update or the aoData index
3
iColumnintOptionalThe column to update (not used of mData is an array or object)
4
bRedrawboolOptionaltrueRedraw the table or not
5
bActionboolOptionaltruePerform predraw actions or not
Returns:

0 on success, 1 on error

Example:
   $(document).ready(function() {
     var oTable = $('#example').dataTable();
     oTable.fnUpdate( 'Example update', 0, 0 ); // Single cell
     oTable.fnUpdate( ['a', 'b', 'c', 'd', 'e'], 1, 0 ); // Row
   } );
fnVersionCheck(sVersion) → {boolean}

Provide a common method for plug-ins to check the version of DataTables being used, in order to ensure compatibility.

Parameters:
Name Type Attributes Default Description
1
sVersionstringVersion string to check for, in the format "X.Y.Z". Note that the formats "X" and "X.Y" are also acceptable.
Returns:

true if this version of DataTables is greater or equal to the required version, or false if this version of DataTales is not suitable

Example:
   $(document).ready(function() {
     var oTable = $('#example').dataTable();
     alert( oTable.fnVersionCheck( '1.9.0' ) );
   } );

Events

draw

Draw event, fired whenever the table is redrawn on the page, at the same point as fnDrawCallback. This may be useful for binding events or performing calculations when the table is altered at all.

Parameters:
Name Type Attributes Default Description
1
eeventjQuery event object
2
oobjectDataTables settings object DataTable.models.oSettings
filter

Filter event, fired when the filtering applied to the table (using the build in global global filter, or column filters) is altered.

Parameters:
Name Type Attributes Default Description
1
eeventjQuery event object
2
oobjectDataTables settings object DataTable.models.oSettings
page

Page change event, fired when the paging of the table is altered.

Parameters:
Name Type Attributes Default Description
1
eeventjQuery event object
2
oobjectDataTables settings object DataTable.models.oSettings
sort

Sort event, fired when the sorting applied to the table is altered.

Parameters:
Name Type Attributes Default Description
1
eeventjQuery event object
2
oobjectDataTables settings object DataTable.models.oSettings
xhr

Ajax (XHR) event, fired whenever an Ajax request is completed from a request to made to the server for new data (note that this trigger is called in fnServerData, if you override fnServerData and which to use this event, you need to trigger it in you success function).

Parameters:
Name Type Attributes Default Description
1
eeventjQuery event object
2
oobjectDataTables settings object DataTable.models.oSettings