DataTable.Api Class
DataTables API class - used to control and interface with one or more DataTables enhanced tables.
The API class is heavily based on jQuery, presenting a chainable interface that you can use to interact with tables. Each instance of the API class has a "context" - i.e. the tables that it will operate on. This could be a single table, all tables on a page or a sub-set thereof.
Additionally the API is designed to allow you to easily work with the data in
the tables, retrieving and manipulating it as required. This is done by
presenting the API class as an array like interface. The contents of the
array depend upon the actions requested by each method (for example
rows().nodes() will return an array of nodes, while rows().data() will
return an array of objects or arrays depending upon your table's
configuration). The API object has a number of array like methods (push,
pop, reverse etc) as well as additional helper methods (each, pluck,
unique etc) to assist your working with the data held in a table.
Most methods (those which return an Api instance) are chainable, which means the return from a method call also has all of the methods available that the top level object had. For example, these two calls are equivalent:
// Not chained
api.row.add( {...} );
api.draw();
// Chained
api.row.add( {...} ).draw();Item Index
Methods
Methods
-
sVersion
Provide a common method for plug-ins to check the version of DataTables being used, in order to ensure compatibility.
Parameters:
-
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' ) ); } );
Version string for plug-ins to check compatibility. Allowed format is
a.b.c-d where: a:int, b:int, c:int, d:string(dev|beta|alpha). d is used
only for non-release builds. See http://semver.org/ for more information.
Private data store, containing all of the settings objects that are created for the tables on a given page.
Note that the DataTable.settings object is aliased to
jQuery.fn.dataTableExt through which it may be accessed and
manipulated, or jQuery.fn.dataTable.settings.
DataTable.defaults.column
()
The columns option in the initialisation parameter allows you to define
details about the way individual columns behave. For a full list of
column options that can be set, please see
{@link DataTable.defaults.column}. Note that if you use columns to
define your columns, you must have an entry in the array for every single
column that you have in your table (these can be null if you don't which
to specify any options).
DataTable.defaults.columnDefs
()
Very similar to columns, columnDefs allows you to target a specific
column, multiple columns, or all columns, using the targets property of
each object in the array. This allows great flexibility when creating
tables, as the columnDefs arrays can be of any length, targeting the
columns you specifically want. columnDefs may use any of the column
options available: {@link DataTable.defaults.column}, but it must
have targets defined in each object in the array. Values in the targets
array may be:
- a string - class name will be matched on the TH for the column
- 0 or a positive integer - column index counting from the left
- a negative integer - column index counting from the right
- the string "_all" - all columns (i.e. assign a default)
DataTable.defaults.formatNumber
-
toFormat
When rendering large numbers in the information element for the table (i.e. "Showing 1 to 10 of 57 entries") DataTables will render large numbers to have a comma separator for the 'thousands' units (e.g. 1 million is rendered as "1,000,000") to help readability for the end user. This function will override the default method DataTables uses.
Parameters:
-
toFormatIntnumber to be formatted
Returns:
formatted string for DataTables to show the number
Example:
// Format a number using a single quote for the separator (note that // this can also be done with the language.thousands option) $(document).ready( function() { $('#example').dataTable( { "formatNumber": function ( toFormat ) { return toFormat.toString().replace( /\B(?=(\d{3})+(?!\d))/g, "'" ); }; } ); } );
DataTable.defaults.serverData
-
source -
data -
callback -
settings
Deprecated The functionality provided by this parameter has now been
superseded by that provided through ajax, which should be used instead.
This parameter allows you to override the default function which obtains the data from the server so something more suitable for your application. For example you could use POST data, or pull information from a Gears or AIR database.
Parameters:
-
sourceStringHTTP source to obtain the data from (
ajax) -
dataArrayA key/value pair object containing the data to send to the server
-
callbackFunctionto be called on completion of the data get process that will draw the data on the page.
-
settingsObjectDataTables settings object
DataTable.defaults.stateLoadCallback
-
settings -
callback
Load the table state. With this function you can define from where, and how, the
state of a table is loaded. By default DataTables will load from localStorage
but you might wish to use a server-side database or cookies.
Parameters:
-
settingsObjectDataTables settings object
-
callbackObjectCallback that can be executed when done. It should be passed the loaded state object.
Returns:
The DataTables state object to be loaded
Example:
$(document).ready( function() { $('#example').dataTable( { "stateSave": true, "stateLoadCallback": function (settings, callback) { $.ajax( { "url": "/state_load", "dataType": "json", "success": function (json) { callback( json ); } } ); } } ); } );
DataTable.defaults.stateSaveCallback
-
settings -
data
Save the table state. This function allows you to define where and how the state
information for the table is stored By default DataTables will use localStorage
but you might wish to use a server-side database or cookies.
Parameters:
-
settingsObjectDataTables settings object
-
dataObjectThe state object to be saved
Example:
$(document).ready( function() { $('#example').dataTable( { "stateSave": true, "stateSaveCallback": function (settings, data) { // Send an Ajax request to the server with the state object $.ajax( { "url": "/state_save", "data": data, "dataType": "json", "method": "POST" "success": function () {} } ); } } ); } );
Events
State loaded event, fired when state has been loaded from stored data and the settings object has been modified by the loaded data.
Event Payload:
-
eEventjQuery event object
-
oSettingsObjectDataTables settings object
-
jsonObjectThe saved state information
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.
Event Payload:
-
eEventjQuery event object
-
oObjectDataTables settings object {@link DataTable.models.oSettings}
Page change event, fired when the paging of the table is altered.
Event Payload:
-
eEventjQuery event object
-
oObjectDataTables settings object {@link DataTable.models.oSettings}
Order event, fired when the ordering applied to the table is altered.
Event Payload:
-
eEventjQuery event object
-
oObjectDataTables settings object {@link DataTable.models.oSettings}
DataTables initialisation complete event, fired when the table is fully drawn, including Ajax data loaded, if Ajax data is required.
Event Payload:
-
eEventjQuery event object
-
oSettingsObjectDataTables settings object
-
jsonObjectThe JSON object request from the server - only present if client-side Ajax sourced data is used
State save event, fired when the table has changed state a new state save is required. This event 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.
Event Payload:
-
eEventjQuery event object
-
oSettingsObjectDataTables settings object
-
jsonObjectThe state information to be saved
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.
Event Payload:
-
eEventjQuery event object
-
oSettingsObjectDataTables settings object
-
jsonObjectThe saved state information
Search event, fired when the searching applied to the table (using the built-in global search, or column filters) is altered.
Event Payload:
-
eEventjQuery event object
-
oObjectDataTables settings object {@link DataTable.models.oSettings}
Processing event, fired when DataTables is doing some kind of processing (be it, order, searcg or anything else). It can be used to indicate to the end user that there is something happening, or that something has finished.
Event Payload:
-
eEventjQuery event object
-
oSettingsObjectDataTables settings object
-
bShowBooleanFlag for if DataTables is doing processing or not
Ajax (XHR) event, fired whenever an Ajax request is completed from a request to made to the server for new data. This event is called before DataTables processed the returned data, so it can also be used to pre- process the data returned from the server, if needed.
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.
Event Payload:
-
eEventjQuery event object
-
oObjectDataTables settings object {@link DataTable.models.oSettings}
-
jsonObjectJSON returned from the server
Example:
// Use a custom property returned from the server in another DOM element
$('#table').dataTable().on('xhr.dt', function (e, settings, json) {
$('#status').html( json.status );
} );// Pre-process the data returned from the server
$('#table').dataTable().on('xhr.dt', function (e, settings, json) {
for ( var i=0, ien=json.aaData.length ; i<ien ; i++ ) {
json.aaData[i].sum = json.aaData[i].one + json.aaData[i].two;
}
// Note no return - manipulate the data directly in the JSON object.
} );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.
Event Payload:
-
eEventjQuery event object
-
oObjectDataTables settings object {@link DataTable.models.oSettings}
Page length change event, fired when number of records to show on each page (the length) is changed.
Event Payload:
-
eEventjQuery event object
-
oObjectDataTables settings object {@link DataTable.models.oSettings}
-
lenIntegerNew length