Classes (0) | Namespaces (4) |
Properties (0) | Static properties (1) |
Methods (22) | Static methods (3) |
Events (11) |
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.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | oInit | object | Optional | {} | Configuration object for DataTables. Options are defined by DataTable.defaults |
// 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 } ); } );
Initialisation options that can be given to DataTables at initialisation time.
Extension object for DataTables that is used to provide all extension options. [...]
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.
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).
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
Perform a jQuery selector action on the table's TR elements (from the tbody) and return the resulting jQuery object.
Almost identical to $ in operation, but in this case returns the data for the matched
rows - as such, the jQuery selector used should match TR row nodes or TD/TH cell nodes
rather than any descendants, so the data can be obtained for the row/cell. If matching
rows are found, the data returned is the original data array/object that was used to
create the row (or a generated array if from a DOM source). [...]
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.
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).
Quickly and simply clear a table
The exact opposite of 'opening' a row, this function will close any rows which are currently 'open'.
Remove a row for the table
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.
Redraw the table
Filter the input based on data
Get the data for the whole table, an individual row or an individual cell based on the provided parameters.
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.
Get the array indexes of a particular cell from it's DOM element and column index including hidden columns
Check to see if a row is 'open' or not.
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.
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.
Show a particular column
Get the settings for a particular table for external manipulation
Sort the table by a particular column
Attach a sort listener to an element for a given column
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.
Provide a common method for plug-ins to check the version of DataTables being used, in order to ensure compatibility.
Check if a TABLE node is a DataTable table already or not.
Get all DataTable tables that have been initialised - optionally you can select to get only currently visible tables.
Provide a common method for plug-ins to check the version of DataTables being used, in order to ensure compatibility.
Destroy event, fired when the DataTable is destroyed by calling fnDestroy or passing the bDestroy:true parameter in the initialisation object. This can be used to remove bound events, added DOM nodes, etc.
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 event, fired when the filtering applied to the table (using the build in global global filter, or column filters) is altered.
DataTables initialisation complete event, fired when the table is fully drawn, including Ajax data loaded, if Ajax data is required.
Page change event, fired when the paging of the table is altered.
Processing event, fired when DataTables is doing some kind of processing (be it, sort, filter or anything else). Can be used to indicate to the end user that there is something happening, or that something has finished.
Sort event, fired when the sorting applied to the table is altered.
State loaded event, fired when state has been loaded from stored data and the settings object has been modified by the loaded data.
State load event, fired when the table is loading state from the stored data, but prior to the settings object being modified by the saved state - allowing modification of the saved state is required or loading of state for a plug-in.
State save event, fired when the table has changed state a new state save is required. This method allows modification of the state saving object prior to actually doing the save, including addition or other state properties (for plug-ins) or modification of a DataTables core property.
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).
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
Perform a jQuery selector action on the table's TR elements (from the tbody) and return the resulting jQuery object.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | sSelector | string | node | jQuery | jQuery selector or node collection to act on | ||
2 | oOpts | object | Optional | Optional parameters for modifying the rows to be included | |
oOpts.filter | string | <optional> | none | Select TR elements that meet the current filter criterion ("applied") or all TR elements (i.e. no filter). | |
oOpts.order | string | <optional> | current | Order 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.page | string | <optional> | all | Limit 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. |
jQuery object, filtered by the given selector.
$(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(''); } );
Almost identical to $ in operation, but in this case returns the data for the matched
rows - as such, the jQuery selector used should match TR row nodes or TD/TH cell nodes
rather than any descendants, so the data can be obtained for the row/cell. If matching
rows are found, the data returned is the original data array/object that was used to
create the row (or a generated array if from a DOM source).
This method is often useful in-combination with $ where both functions are given the same parameters and the array indexes will match identically.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | sSelector | string | node | jQuery | jQuery selector or node collection to act on | ||
2 | oOpts | object | Optional | Optional parameters for modifying the rows to be included | |
oOpts.filter | string | <optional> | none | Select elements that meet the current filter criterion ("applied") or all elements (i.e. no filter). | |
oOpts.order | string | <optional> | current | Order of the data 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.page | string | <optional> | all | Limit 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. |
Data for the matched elements. If any elements, as a result of the selector, were not TR, TD or TH elements in the DataTable, they will have a null entry in the array.
$(document).ready(function() { var oTable = $('#example').dataTable(); // Get the data from the first row in the table var data = oTable._('tr:first'); // Do something useful with the data alert( "First cell is: "+data[0] ); } );
$(document).ready(function() { var oTable = $('#example').dataTable(); // Filter to 'Webkit' and get all data for oTable.fnFilter('Webkit'); var data = oTable._('tr', {"filter": "applied"}); // Do something with the data alert( data.length+" rows matched the filter" ); } );
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.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | mData | array | object | The data to be added to the table. This can be:
| ||
2 | bRedraw | bool | Optional | true | redraw the table or not |
An array of integers, representing the list of indexes in aoData (DataTable.models.oSettings) that have been added to the table.
// 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++; }
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).
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | bRedraw | boolean | Optional | true | Redraw the table or not, you will typically want to |
$(document).ready(function() { var oTable = $('#example').dataTable( { "sScrollY": "200px", "bPaginate": false } ); $(window).bind('resize', function () { oTable.fnAdjustColumnSizing(); } ); } );
Quickly and simply clear a table
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | bRedraw | bool | Optional | true | redraw the table or not |
$(document).ready(function() { var oTable = $('#example').dataTable(); // Immediately 'nuke' the current rows (perhaps waiting for an Ajax callback...) oTable.fnClearTable(); } );
The exact opposite of 'opening' a row, this function will close any rows which are currently 'open'.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | nTr | node | the table row to 'close' |
0 on success, or 1 if failed (can't find the row)
$(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(); } );
Remove a row for the table
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | mTarget | mixed | The index of the row from aoData to be deleted, or the TR element you want to delete | ||
2 | fnCallBack | function | null | Optional | Callback function | |
3 | bRedraw | bool | Optional | true | Redraw the table or not |
The row that was deleted
$(document).ready(function() { var oTable = $('#example').dataTable(); // Immediately remove the first row oTable.fnDeleteRow( 0 ); } );
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.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | bRemove | boolean | Optional | false | Completely remove the table from the DOM |
$(document).ready(function() { // This example is fairly pointless in reality, but shows how fnDestroy can be used var oTable = $('#example').dataTable(); oTable.fnDestroy(); } );
Redraw the table
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | bComplete | bool | Optional | true | Re-filter and resort (if enabled) the table before the draw. |
$(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(); } );
Filter the input based on data
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | sInput | string | String to filter the table on | ||
2 | iColumn | int | null | Optional | Column to limit filtering to | |
3 | bRegex | bool | Optional | false | Treat as regular expression or not |
4 | bSmart | bool | Optional | true | Perform smart filtering or not |
5 | bShowGlobal | bool | Optional | true | Show the input global filter in it's input box(es) |
6 | bCaseInsensitive | bool | Optional | true | Do case-insensitive matching (true) or not (false) |
$(document).ready(function() { var oTable = $('#example').dataTable(); // Sometime later - filter... oTable.fnFilter( 'test string' ); } );
Get the data for the whole table, an individual row or an individual cell based on the provided parameters.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | mRow | int | node | Optional | A TR row node, TD/TH cell node or an integer. If given as a TR node then the data source for the whole row will be returned. If given as a TD/TH cell node then iCol will be automatically calculated and the data for the cell returned. If given as an integer, then this is treated as the aoData internal data index for the row (see fnGetPosition) and the data for that row used. | |
2 | iCol | int | Optional | Optional column index that you want the data of. |
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.
// Row data $(document).ready(function() { oTable = $('#example').dataTable(); oTable.$('tr').click( function () { var data = oTable.fnGetData( this ); // ... do something with the array / object of data for the row } ); } );
// Individual cell data $(document).ready(function() { oTable = $('#example').dataTable(); oTable.$('td').click( function () { var sData = oTable.fnGetData( this ); alert( 'The cell clicked on had the value of '+sData ); } ); } );
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.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | iRow | int | Optional | Optional row index for the TR element you want |
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.
$(document).ready(function() { var oTable = $('#example').dataTable(); // Get the nodes from the table var nNodes = oTable.fnGetNodes( ); } );
Get the array indexes of a particular cell from it's DOM element and column index including hidden columns
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | nNode | node | this can either be a TR, TD or TH in the table's body |
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), column index (all)] is given.
$(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(); } );
Check to see if a row is 'open' or not.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | nTr | node | the table row to check |
true if the row is currently open, false otherwise
$(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(); } );
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.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | nTr | node | The table row to 'open' | ||
2 | mHtml | string | node | jQuery | The HTML to put into the row | ||
3 | sClass | string | Class to give the new TD cell |
The row opened. Note that if the table row passed in as the first parameter, is not found in the table, this method will silently return.
$(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(); } );
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.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | mAction | string | int | Paging action to take: "first", "previous", "next" or "last" or page number to jump to (integer), note that page 0 is the first page. | ||
2 | bRedraw | bool | Optional | true | Redraw the table or not |
$(document).ready(function() { var oTable = $('#example').dataTable(); oTable.fnPageChange( 'next' ); } );
Show a particular column
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | iCol | int | The column whose display should be changed | ||
2 | bShow | bool | Show (true) or hide (false) the column | ||
3 | bRedraw | bool | Optional | true | Redraw the table or not |
$(document).ready(function() { var oTable = $('#example').dataTable(); // Hide the second column after initialisation oTable.fnSetColumnVis( 1, false ); } );
Get the settings for a particular table for external manipulation
DataTables settings object. See DataTable.models.oSettings
$(document).ready(function() { var oTable = $('#example').dataTable(); var oSettings = oTable.fnSettings(); // Show an example parameter from the settings alert( oSettings._iDisplayStart ); } );
Sort the table by a particular column
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | iCol | int | the data index to sort on. Note that this will not match the 'display index' if you have hidden data entries |
$(document).ready(function() { var oTable = $('#example').dataTable(); // Sort immediately with columns 0 and 1 oTable.fnSort( [ [0,'asc'], [1,'asc'] ] ); } );
Attach a sort listener to an element for a given column
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | nNode | node | the element to attach the sort listener to | ||
2 | iColumn | int | the column that a click on this node will sort on | ||
3 | fnCallback | function | Optional | callback function when sort is run |
$(document).ready(function() { var oTable = $('#example').dataTable(); // Sort on column 1, when 'sorter' is clicked on oTable.fnSortListener( document.getElementById('sorter'), 1 ); } );
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.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | mData | object | array | string | Data to update the cell/row with | ||
2 | mRow | node | int | TR element you want to update or the aoData index | ||
3 | iColumn | int | Optional | The column to update (not used of mData is an array or object) | |
4 | bRedraw | bool | Optional | true | Redraw the table or not |
5 | bAction | bool | Optional | true | Perform pre-draw actions or not |
0 on success, 1 on error
$(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 } );
Provide a common method for plug-ins to check the version of DataTables being used, in order to ensure compatibility.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | sVersion | string | Version string to check for, in the format "X.Y.Z". Note that the formats "X" and "X.Y" are also acceptable. |
true if this version of DataTables is greater or equal to the required version, or false if this version of DataTales is not suitable
$(document).ready(function() { var oTable = $('#example').dataTable(); alert( oTable.fnVersionCheck( '1.9.0' ) ); } );
Check if a TABLE node is a DataTable table already or not.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | nTable | node | The TABLE node to check if it is a DataTable or not (note that other node types can be passed in, but will always return false). |
true the table given is a DataTable, or false otherwise
var ex = document.getElementById('example'); if ( ! $.fn.DataTable.fnIsDataTable( ex ) ) { $(ex).dataTable(); }
Get all DataTable tables that have been initialised - optionally you can select to get only currently visible tables.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | bVisible | boolean | Optional | false | Flag to indicate if you want all (default) or visible tables only. |
Array of TABLE nodes (not DataTable instances) which are DataTables
var table = $.fn.dataTable.fnTables(true); if ( table.length > 0 ) { $(table).dataTable().fnAdjustColumnSizing(); }
Provide a common method for plug-ins to check the version of DataTables being used, in order to ensure compatibility.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | sVersion | string | Version string to check for, in the format "X.Y.Z". Note that the formats "X" and "X.Y" are also acceptable. |
true if this version of DataTables is greater or equal to the required version, or false if this version of DataTales is not suitable
alert( $.fn.dataTable.fnVersionCheck( '1.9.0' ) );
Destroy event, fired when the DataTable is destroyed by calling fnDestroy or passing the bDestroy:true parameter in the initialisation object. This can be used to remove bound events, added DOM nodes, etc.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | e | event | jQuery event object | ||
2 | o | object | DataTables settings object DataTable.models.oSettings |
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.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | e | event | jQuery event object | ||
2 | o | object | DataTables settings object DataTable.models.oSettings |
Filter event, fired when the filtering applied to the table (using the build in global global filter, or column filters) is altered.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | e | event | jQuery event object | ||
2 | o | object | DataTables settings object DataTable.models.oSettings |
DataTables initialisation complete event, fired when the table is fully drawn, including Ajax data loaded, if Ajax data is required.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | e | event | jQuery event object | ||
2 | oSettings | object | DataTables settings object | ||
3 | json | object | The JSON object request from the server - only present if client-side Ajax sourced data is used |
Page change event, fired when the paging of the table is altered.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | e | event | jQuery event object | ||
2 | o | object | DataTables settings object DataTable.models.oSettings |
Processing event, fired when DataTables is doing some kind of processing (be it, sort, filter or anything else). Can be used to indicate to the end user that there is something happening, or that something has finished.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | e | event | jQuery event object | ||
2 | oSettings | object | DataTables settings object | ||
3 | bShow | boolean | Flag for if DataTables is doing processing or not |
Sort event, fired when the sorting applied to the table is altered.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | e | event | jQuery event object | ||
2 | o | object | DataTables settings object DataTable.models.oSettings |
State loaded event, fired when state has been loaded from stored data and the settings object has been modified by the loaded data.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | e | event | jQuery event object | ||
2 | oSettings | object | DataTables settings object | ||
3 | json | object | The saved state information |
State load event, fired when the table is loading state from the stored data, but prior to the settings object being modified by the saved state - allowing modification of the saved state is required or loading of state for a plug-in.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | e | event | jQuery event object | ||
2 | oSettings | object | DataTables settings object | ||
3 | json | object | The saved state information |
State save event, fired when the table has changed state a new state save is required. This method allows modification of the state saving object prior to actually doing the save, including addition or other state properties (for plug-ins) or modification of a DataTables core property.
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | e | event | jQuery event object | ||
2 | oSettings | object | DataTables settings object | ||
3 | json | object | The state information to be saved |
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).
Name | Type | Attributes | Default | Description | |
---|---|---|---|---|---|
1 | e | event | jQuery event object | ||
2 | o | object | DataTables settings object DataTable.models.oSettings | ||
3 | json | object | JSON returned from the server |