| Classes (0) | Namespaces (3) |
| Properties (0) | Static properties (58) |
| Methods (0) | Static methods (0) |
| Events (0) |
| Properties (0) | Static properties (58) |
| Methods (0) | Static methods (0) |
| Events (0) |
Initialisation options that can be given to DataTables at initialisation +time.
Column options that can be given to DataTables at initialisation time.
All strings that DataTables uses in the user interface that it creates +are defined in this object, allowing you to modified them individually or +completely replace them all as required.
This parameter allows you to have define the global filtering state at +initialisation time. As an object the "sSearch" parameter must be +defined, but all other parameters are optional. When "bRegex" is true, +the search string will be treated as a regular expression, when false +(default) it will be treated as a straight string. When "bSmart" +DataTables will use it's smart filtering methods (to word match at +any point in the data), when false this will not be done.
An array of data to use for the table, passed in at initialisation which +will be used in preference to any data which is already in the DOM. This is +particularly useful for constructing tables purely in Javascript, for +example with a custom Ajax call.
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. The aaSorting array should +contain an array for each column to be sorted initially containing the +column's index and a direction string ('asc' or 'desc').
This parameter is basically identical to the aaSorting parameter, but +cannot be overridden by user interaction with the table. What this means +is that you could have a column (visible or hidden) which the sorting will +always be forced on first - any sorting after that (from the user) will +then be performed as required. This can be useful for grouping rows +together.
This parameter allows you to readily specify the entries in the length drop +down menu that DataTables shows when pagination is enabled. It can be +either a 1D array of options which will be used for both the displayed +option and the value, or a 2D array which will use the array in the first +position as the value, and the array in the second position as the +displayed options (useful for language strings such as 'All').
Very similar to aoColumns, aoColumnDefs allows you to target a specific +column, multiple columns, or all columns, using the aTargets property of +each object in the array. This allows great flexibility when creating +tables, as the aoColumnDefs arrays can be of any length, targeting the +columns you specifically want. aoColumnDefs may use any of the column +options available: DataTable.defaults.columns, but it must +have aTargets defined in each object in the array. Values in the aTargets +array may be: +
The aoColumns 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 +DataTable.defaults.columns. Note that if you use aoColumns 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).
Basically the same as oSearch, this parameter defines the individual column +filtering state at initialisation time. The array must be of the same size +as the number of columns, and each element be an object with the parameters +"sSearch" and "bEscapeRegex" (the latter is optional). 'null' is also +accepted and the default will be used.
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.
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.
Deferred rendering can provide DataTables with a huge speed boost when you +are using an Ajax or JS data source for the table. This option, when set to +true, will cause DataTables to defer the creation of the table elements for +each row until they are needed for a draw - saving a significant amount of +time.
Replace a DataTable which matches the given selector and replace it with +one which has the properties of the new initialisation object passed. If no +table matches the selector, then the new DataTable will be constructed as +per normal.
Enable or disable filtering of data. 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). Note that if you +wish to use filtering in DataTables this must remain 'true' - to remove the +default filtering input box and retain filtering abilities, please use +DataTable.defaults.sDom.
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.
Enable jQuery UI ThemeRoller support (required as ThemeRoller requires some +slightly different and additional mark-up from what DataTables has +traditionally used).
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).
Enable or disable pagination.
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.
Retrieve the DataTables object for the given selector. Note that if the +table has already been initialised, this parameter will cause DataTables +to simply return the object that has already been set up - it will not take +account of any changes you might have made to the initialisation object +passed to DataTables (setting this parameter to true is an acknowledgement +that you understand this). bDestroy can be used to reinitialise a table if +you need.
Indicate if DataTables should be allowed to set the padding / margin +etc for the scrolling header elements or not. Typically you will want +this.
When vertical (y) scrolling is enabled, DataTables will force the height of +the table's viewport to the given height at all times (useful for layout). +However, this can look odd when filtering data down to a small data set, +and the footer is left "floating" further down. This parameter (when +enabled) will cause DataTables to collapse the table's viewport down when +the result set will fit within the given Y height.
Enable infinite scrolling for DataTables (to be used in combination with +sScrollY). Infinite scrolling means that DataTables will continually load +data as a user scrolls through a table, which is very useful for large +dataset. This cannot be used with pagination, which is automatically +disabled. Note - the Scroller extra for DataTables is recommended in +in preference to this option.
Configure DataTables to use server-side processing. Note that the +sAjaxSource parameter must also be given in order to give DataTables a +source to obtain the required data for each draw.
Enable or disable sorting of columns. Sorting of individual columns can be +disabled by the "bSortable" option for each column.
Allows control over whether DataTables should use the top (true) unique +cell that is found for a single column, or the bottom (false - default). +This is useful when using complex headers.
Enable or disable the addition of the classes 'sorting_1', 'sorting_2' and +'sorting_3' to the columns which are currently being sorted on. This is +presented as a feature switch as it can increase processing time (while +classes are removed and added) so for large data sets you might want to +turn this off.
Enable or disable state saving. When enabled a cookie will be used to save +table display information such as pagination information, display length, +filtering and sorting. As such when the end user reloads the page the +display display will match what thy had previously set up.
Customise the cookie and / or the parameters being stored when using +DataTables with state saving enabled. This function is called whenever +the cookie is modified, and it expects a fully formed cookie string to be +returned. Note that the data object passed in is a Javascript object which +must be converted to a string (JSON.stringify for example).
This function is called when a TR element is created (and all TD child +elements have been inserted), or registered if using a DOM source, allowing +manipulation of the TR element (adding classes etc).
This function is called on every 'draw' event, and allows you to +dynamically modify any aspect you want about the created DOM.
Identical to fnHeaderCallback() but for the table footer this function +allows you to modify the table footer on every 'draw' even.
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.
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.
The information element can be used to convey information about the current +state of the table. Although the internationalisation options presented by +DataTables are quite capable of dealing with most customisations, there may +be times where you wish to customise the string further. This callback +allows you to do exactly that.
Called when the table has been initialised. Normally DataTables will +initialise sequentially and there will be no need for this function, +however, this does not hold true when using external language information +since that is obtained using an async XHR call.
Called at the very start of each table draw and can be used to cancel the +draw by returning false, any other return (including undefined) results in +the full draw occurring).
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.
This parameter allows you to override the default function which obtains +the data from the server ($.getJSON) so something more suitable for your +application. For example you could use POST data, or pull information from +a Gears or AIR database.
It is often useful to send extra data to the server when making an Ajax +request - for example custom filtering information, and this callback +function makes it trivial to send extra information to the server. The +passed in parameter is the data set that has been constructed by +DataTables, and you can add to this or modify it as you require.
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 its state saving +cookie, but you might wish to use local storage (HTML5) or a server-side database.
Callback that is called when the state has been loaded from the state saving method +and the DataTables settings object has been modified as a result of the loaded state.
Callback which allows modification of the saved state prior to loading that state. +This callback is called when the table is loading state from the stored data, but +prior to the settings object being modified by the saved state. Note that for +plug-in authors, you should use the 'stateLoadParams' event to load parameters for +a plug-in.
Save the table state. This function allows you to define where and how the state +information for the table is stored - by default it will use a cookie, but you +might want to use local storage (HTML5) or a server-side database.
Callback which allows modification of the state to be saved. Called 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 or modification. Note that for plug-in authors, you should +use the 'stateSaveParams' event to save parameters for a plug-in.
Duration of the cookie which is used for storing session information. This +value is given in seconds.
When enabled DataTables will not make a request to the server for the first +page draw - rather it will use the data already on the page (no sorting etc +will be applied to it), thus saving on an XHR at load time. iDeferLoading +is used to indicate that deferred loading is required, but it is also used +to tell DataTables how many records there are in the full table (allowing +the information element and pagination to be displayed correctly). In the case +where a filtering is applied to the table on initial load, this can be +indicated by giving the parameter as an array, where the first element is +the number of records available after filtering and the second element is the +number of records without filtering (allowing the table information element +to be shown correctly).
Number of rows to display on a single page when using pagination. If +feature enabled (bLengthChange) then the end user will be able to override +this to a custom setting using a pop-up menu.
Define the starting point for data display when using DataTables with +pagination. Note that this parameter is the number of records, rather than +the page number, so if you have 10 records per page and want to start on +the third page, it should be "20".
The scroll gap is the amount of scrolling that is left to go before +DataTables will load the next 'page' of data automatically. You typically +want a gap which is big enough that the scrolling will be smooth for the +user, while not so large that it will load more data than need.
By default DataTables allows keyboard navigation of the table (sorting, paging, +and filtering) by adding a tabindex attribute to the required elements. This +allows you to tab through the controls and press the enter key to activate them. +The tabindex is default 0, meaning that the tab follows the flow of the document. +You can overrule this using this parameter if you wish. Use a value of -1 to +disable built-in keyboard navigation.
By default DataTables will look for the property 'aaData' when obtaining +data from an Ajax source or for server-side processing - this parameter +allows that property to be changed. You can use Javascript dotted object +notation to get a data source for multiple levels of nesting.
You can instruct DataTables to load data from an external source using this +parameter (use aData if you want to pass data in you already have). Simply +provide a url a JSON object can be obtained from. This object must include +the parameter 'aaData' which is the data source for the table.
This parameter can be used to override the default prefix that DataTables +assigns to a cookie when state saving is enabled.
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: +
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).
Enable horizontal scrolling. When a table is too wide to fit into a certain +layout, or you have a large number of columns in the table, you can enable +x-scrolling to show the table in a viewport, which can be scrolled. This +property can be any CSS unit, or a number (in which case it will be treated +as a pixel measurement).
This property can be used to force a DataTable to use more width than it +might otherwise do when x-scrolling is enabled. For example if you have a +table which requires to be well spaced, this parameter is useful for +"over-sizing" the table, and thus forcing scrolling. This property can by +any CSS unit, or a number (in which case it will be treated as a pixel +measurement).
Enable vertical scrolling. Vertical scrolling will constrain the DataTable +to the given height, and enable scrolling for any data which overflows the +current viewport. This can be used as an alternative to paging to display +a lot of data in a small area (although paging and scrolling can both be +enabled at the same time). This property can be any CSS unit, or a number +(in which case it will be treated as a pixel measurement).
Set the HTTP method that is used to make the Ajax call for server-side +processing or Ajax sourced data.
An array of data to use for the table, passed in at initialisation which +will be used in preference to any data which is already in the DOM. This is +particularly useful for constructing tables purely in Javascript, for +example with a custom Ajax call.
// Using a 2D array data source
+ $(document).ready( function () {
+ $('#example').dataTable( {
+ "aaData": [
+ ['Trident', 'Internet Explorer 4.0', 'Win 95+', 4, 'X'],
+ ['Trident', 'Internet Explorer 5.0', 'Win 95+', 5, 'C'],
+ ],
+ "aoColumns": [
+ { "sTitle": "Engine" },
+ { "sTitle": "Browser" },
+ { "sTitle": "Platform" },
+ { "sTitle": "Version" },
+ { "sTitle": "Grade" }
+ ]
+ } );
+ } );
+
+
+ // Using an array of objects as a data source (mData)
+ $(document).ready( function () {
+ $('#example').dataTable( {
+ "aaData": [
+ {
+ "engine": "Trident",
+ "browser": "Internet Explorer 4.0",
+ "platform": "Win 95+",
+ "version": 4,
+ "grade": "X"
+ },
+ {
+ "engine": "Trident",
+ "browser": "Internet Explorer 5.0",
+ "platform": "Win 95+",
+ "version": 5,
+ "grade": "C"
+ }
+ ],
+ "aoColumns": [
+ { "sTitle": "Engine", "mData": "engine" },
+ { "sTitle": "Browser", "mData": "browser" },
+ { "sTitle": "Platform", "mData": "platform" },
+ { "sTitle": "Version", "mData": "version" },
+ { "sTitle": "Grade", "mData": "grade" }
+ ]
+ } );
+ } );
+ 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. The aaSorting array should +contain an array for each column to be sorted initially containing the +column's index and a direction string ('asc' or 'desc').
// Sort by 3rd column first, and then 4th column
+ $(document).ready( function() {
+ $('#example').dataTable( {
+ "aaSorting": [[2,'asc'], [3,'desc']]
+ } );
+ } );
+
+ // No initial sorting
+ $(document).ready( function() {
+ $('#example').dataTable( {
+ "aaSorting": []
+ } );
+ } );
+ This parameter is basically identical to the aaSorting parameter, but +cannot be overridden by user interaction with the table. What this means +is that you could have a column (visible or hidden) which the sorting will +always be forced on first - any sorting after that (from the user) will +then be performed as required. This can be useful for grouping rows +together.
$(document).ready( function() {
+ $('#example').dataTable( {
+ "aaSortingFixed": [[0,'asc']]
+ } );
+ } )
+ This parameter allows you to readily specify the entries in the length drop +down menu that DataTables shows when pagination is enabled. It can be +either a 1D array of options which will be used for both the displayed +option and the value, or a 2D array which will use the array in the first +position as the value, and the array in the second position as the +displayed options (useful for language strings such as 'All').
$(document).ready( function() {
+ $('#example').dataTable( {
+ "aLengthMenu": [[10, 25, 50, -1], [10, 25, 50, "All"]]
+ } );
+ } );
+
+
+ // Setting the default display length as well as length menu
+ // This is likely to be wanted if you remove the '10' option which
+ // is the iDisplayLength default.
+ $(document).ready( function() {
+ $('#example').dataTable( {
+ "iDisplayLength": 25,
+ "aLengthMenu": [[25, 50, 100, -1], [25, 50, 100, "All"]]
+ } );
+ } );
+ Very similar to aoColumns, aoColumnDefs allows you to target a specific +column, multiple columns, or all columns, using the aTargets property of +each object in the array. This allows great flexibility when creating +tables, as the aoColumnDefs arrays can be of any length, targeting the +columns you specifically want. aoColumnDefs may use any of the column +options available: DataTable.defaults.columns, but it must +have aTargets defined in each object in the array. Values in the aTargets +array may be: +
The aoColumns 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 +DataTable.defaults.columns. Note that if you use aoColumns 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).
Basically the same as oSearch, this parameter defines the individual column +filtering state at initialisation time. The array must be of the same size +as the number of columns, and each element be an object with the parameters +"sSearch" and "bEscapeRegex" (the latter is optional). 'null' is also +accepted and the default will be used.
$(document).ready( function() {
+ $('#example').dataTable( {
+ "aoSearchCols": [
+ null,
+ { "sSearch": "My filter" },
+ null,
+ { "sSearch": "^[0-9]", "bEscapeRegex": false }
+ ]
+ } );
+ } )
+ 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.
$(document).ready( function() {
+ $('#example').dataTable( {
+ "asStripeClasses": [ 'strip1', 'strip2', 'strip3' ]
+ } );
+ } )
+ 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.
$(document).ready( function () {
+ $('#example').dataTable( {
+ "bAutoWidth": false
+ } );
+ } );
+ Deferred rendering can provide DataTables with a huge speed boost when you +are using an Ajax or JS data source for the table. This option, when set to +true, will cause DataTables to defer the creation of the table elements for +each row until they are needed for a draw - saving a significant amount of +time.
$(document).ready( function() {
+ var oTable = $('#example').dataTable( {
+ "sAjaxSource": "sources/arrays.txt",
+ "bDeferRender": true
+ } );
+ } );
+ Replace a DataTable which matches the given selector and replace it with +one which has the properties of the new initialisation object passed. If no +table matches the selector, then the new DataTable will be constructed as +per normal.
$(document).ready( function() {
+ $('#example').dataTable( {
+ "sScrollY": "200px",
+ "bPaginate": false
+ } );
+
+ // Some time later....
+ $('#example').dataTable( {
+ "bFilter": false,
+ "bDestroy": true
+ } );
+ } );
+ Enable or disable filtering of data. 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). Note that if you +wish to use filtering in DataTables this must remain 'true' - to remove the +default filtering input box and retain filtering abilities, please use +DataTable.defaults.sDom.
$(document).ready( function () {
+ $('#example').dataTable( {
+ "bFilter": false
+ } );
+ } );
+ 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.
$(document).ready( function () {
+ $('#example').dataTable( {
+ "bInfo": false
+ } );
+ } );
+ Enable jQuery UI ThemeRoller support (required as ThemeRoller requires some +slightly different and additional mark-up from what DataTables has +traditionally used).
$(document).ready( function() {
+ $('#example').dataTable( {
+ "bJQueryUI": true
+ } );
+ } );
+ 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).
$(document).ready( function () {
+ $('#example').dataTable( {
+ "bLengthChange": false
+ } );
+ } );
+ Enable or disable pagination.
$(document).ready( function () {
+ $('#example').dataTable( {
+ "bPaginate": false
+ } );
+ } );
+ 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.
$(document).ready( function () {
+ $('#example').dataTable( {
+ "bProcessing": true
+ } );
+ } );
+ Retrieve the DataTables object for the given selector. Note that if the +table has already been initialised, this parameter will cause DataTables +to simply return the object that has already been set up - it will not take +account of any changes you might have made to the initialisation object +passed to DataTables (setting this parameter to true is an acknowledgement +that you understand this). bDestroy can be used to reinitialise a table if +you need.
$(document).ready( function() {
+ initTable();
+ tableActions();
+ } );
+
+ function initTable ()
+ {
+ return $('#example').dataTable( {
+ "sScrollY": "200px",
+ "bPaginate": false,
+ "bRetrieve": true
+ } );
+ }
+
+ function tableActions ()
+ {
+ var oTable = initTable();
+ // perform API operations with oTable
+ }
+ Indicate if DataTables should be allowed to set the padding / margin +etc for the scrolling header elements or not. Typically you will want +this.
$(document).ready( function() {
+ $('#example').dataTable( {
+ "bScrollAutoCss": false,
+ "sScrollY": "200px"
+ } );
+ } );
+ When vertical (y) scrolling is enabled, DataTables will force the height of +the table's viewport to the given height at all times (useful for layout). +However, this can look odd when filtering data down to a small data set, +and the footer is left "floating" further down. This parameter (when +enabled) will cause DataTables to collapse the table's viewport down when +the result set will fit within the given Y height.
$(document).ready( function() {
+ $('#example').dataTable( {
+ "sScrollY": "200",
+ "bScrollCollapse": true
+ } );
+ } );
+ Enable infinite scrolling for DataTables (to be used in combination with +sScrollY). Infinite scrolling means that DataTables will continually load +data as a user scrolls through a table, which is very useful for large +dataset. This cannot be used with pagination, which is automatically +disabled. Note - the Scroller extra for DataTables is recommended in +in preference to this option.
$(document).ready( function() {
+ $('#example').dataTable( {
+ "bScrollInfinite": true,
+ "bScrollCollapse": true,
+ "sScrollY": "200px"
+ } );
+ } );
+ Configure DataTables to use server-side processing. Note that the +sAjaxSource parameter must also be given in order to give DataTables a +source to obtain the required data for each draw.
$(document).ready( function () {
+ $('#example').dataTable( {
+ "bServerSide": true,
+ "sAjaxSource": "xhr.php"
+ } );
+ } );
+ Enable or disable sorting of columns. Sorting of individual columns can be +disabled by the "bSortable" option for each column.
$(document).ready( function () {
+ $('#example').dataTable( {
+ "bSort": false
+ } );
+ } );
+ Allows control over whether DataTables should use the top (true) unique +cell that is found for a single column, or the bottom (false - default). +This is useful when using complex headers.
$(document).ready( function() {
+ $('#example').dataTable( {
+ "bSortCellsTop": true
+ } );
+ } );
+ Enable or disable the addition of the classes 'sorting_1', 'sorting_2' and +'sorting_3' to the columns which are currently being sorted on. This is +presented as a feature switch as it can increase processing time (while +classes are removed and added) so for large data sets you might want to +turn this off.
$(document).ready( function () {
+ $('#example').dataTable( {
+ "bSortClasses": false
+ } );
+ } );
+ Enable or disable state saving. When enabled a cookie will be used to save +table display information such as pagination information, display length, +filtering and sorting. As such when the end user reloads the page the +display display will match what thy had previously set up.
$(document).ready( function () {
+ $('#example').dataTable( {
+ "bStateSave": true
+ } );
+ } );
+ Customise the cookie and / or the parameters being stored when using +DataTables with state saving enabled. This function is called whenever +the cookie is modified, and it expects a fully formed cookie string to be +returned. Note that the data object passed in is a Javascript object which +must be converted to a string (JSON.stringify for example).
| + | Name | +Type | +Attributes | +Default | +Description | +
|---|---|---|---|---|---|
1 | sName | string | Name of the cookie defined by DataTables | ||
2 | oData | object | Data to be stored in the cookie | ||
3 | sExpires | string | Cookie expires string | ||
4 | sPath | string | Path of the cookie to set |
Cookie formatted string (which should be encoded by + using encodeURIComponent())
$(document).ready( function () {
+ $('#example').dataTable( {
+ "fnCookieCallback": function (sName, oData, sExpires, sPath) {
+ // Customise oData or sName or whatever else here
+ return sName + "="+JSON.stringify(oData)+"; expires=" + sExpires +"; path=" + sPath;
+ }
+ } );
+ } );
+ This function is called when a TR element is created (and all TD child +elements have been inserted), or registered if using a DOM source, allowing +manipulation of the TR element (adding classes etc).
| + | Name | +Type | +Attributes | +Default | +Description | +
|---|---|---|---|---|---|
1 | nRow | node | "TR" element for the current row | ||
2 | aData | array | Raw data array for this row | ||
3 | iDataIndex | int | The index of this row in aoData |
$(document).ready( function() {
+ $('#example').dataTable( {
+ "fnCreatedRow": function( nRow, aData, iDataIndex ) {
+ // Bold the grade for all 'A' grade browsers
+ if ( aData[4] == "A" )
+ {
+ $('td:eq(4)', nRow).html( 'A' );
+ }
+ }
+ } );
+ } );
+ This function is called on every 'draw' event, and allows you to +dynamically modify any aspect you want about the created DOM.
| + | Name | +Type | +Attributes | +Default | +Description | +
|---|---|---|---|---|---|
1 | oSettings | object | DataTables settings object |
$(document).ready( function() {
+ $('#example').dataTable( {
+ "fnDrawCallback": function( oSettings ) {
+ alert( 'DataTables has redrawn the table' );
+ }
+ } );
+ } );
+ Identical to fnHeaderCallback() but for the table footer this function +allows you to modify the table footer on every 'draw' even.
| + | Name | +Type | +Attributes | +Default | +Description | +
|---|---|---|---|---|---|
1 | nFoot | node | "TR" element for the footer | ||
2 | aData | array | Full table data (as derived from the original HTML) | ||
3 | iStart | int | Index for the current display starting point in the + display array | ||
4 | iEnd | int | Index for the current display ending point in the + display array | ||
5 | aiDisplay | array int | Index array to translate the visual position + to the full data array |
$(document).ready( function() {
+ $('#example').dataTable( {
+ "fnFooterCallback": function( nFoot, aData, iStart, iEnd, aiDisplay ) {
+ nFoot.getElementsByTagName('th')[0].innerHTML = "Starting index is "+iStart;
+ }
+ } );
+ } )
+ 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.
| + | Name | +Type | +Attributes | +Default | +Description | +
|---|---|---|---|---|---|
1 | iIn | int | number to be formatted |
formatted string for DataTables to show the number
$(document).ready( function() {
+ $('#example').dataTable( {
+ "fnFormatNumber": function ( iIn ) {
+ if ( iIn < 1000 ) {
+ return iIn;
+ } else {
+ var
+ s=(iIn+""),
+ a=s.split(""), out="",
+ iLen=s.length;
+
+ for ( var i=0 ; i<iLen ; i++ ) {
+ if ( i%3 === 0 && i !== 0 ) {
+ out = "'"+out;
+ }
+ out = a[iLen-i-1]+out;
+ }
+ }
+ return out;
+ };
+ } );
+ } );
+ 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.
| + | Name | +Type | +Attributes | +Default | +Description | +
|---|---|---|---|---|---|
1 | nHead | node | "TR" element for the header | ||
2 | aData | array | Full table data (as derived from the original HTML) | ||
3 | iStart | int | Index for the current display starting point in the + display array | ||
4 | iEnd | int | Index for the current display ending point in the + display array | ||
5 | aiDisplay | array int | Index array to translate the visual position + to the full data array |
$(document).ready( function() {
+ $('#example').dataTable( {
+ "fnHeaderCallback": function( nHead, aData, iStart, iEnd, aiDisplay ) {
+ nHead.getElementsByTagName('th')[0].innerHTML = "Displaying "+(iEnd-iStart)+" records";
+ }
+ } );
+ } )
+ The information element can be used to convey information about the current +state of the table. Although the internationalisation options presented by +DataTables are quite capable of dealing with most customisations, there may +be times where you wish to customise the string further. This callback +allows you to do exactly that.
| + | Name | +Type | +Attributes | +Default | +Description | +
|---|---|---|---|---|---|
1 | oSettings | object | DataTables settings object | ||
2 | iStart | int | Starting position in data for the draw | ||
3 | iEnd | int | End position in data for the draw | ||
4 | iMax | int | Total number of rows in the table (regardless of + filtering) | ||
5 | iTotal | int | Total number of rows in the data set, after filtering | ||
6 | sPre | string | The string that DataTables has formatted using it's + own rules |
The string to be displayed in the information element.
$('#example').dataTable( {
+ "fnInfoCallback": function( oSettings, iStart, iEnd, iMax, iTotal, sPre ) {
+ return iStart +" to "+ iEnd;
+ }
+ } );
+ Called when the table has been initialised. Normally DataTables will +initialise sequentially and there will be no need for this function, +however, this does not hold true when using external language information +since that is obtained using an async XHR call.
| + | Name | +Type | +Attributes | +Default | +Description | +
|---|---|---|---|---|---|
1 | oSettings | object | DataTables settings object | ||
2 | json | object | The JSON object request from the server - only + present if client-side Ajax sourced data is used |
$(document).ready( function() {
+ $('#example').dataTable( {
+ "fnInitComplete": function(oSettings, json) {
+ alert( 'DataTables has finished its initialisation.' );
+ }
+ } );
+ } )
+ Called at the very start of each table draw and can be used to cancel the +draw by returning false, any other return (including undefined) results in +the full draw occurring).
| + | Name | +Type | +Attributes | +Default | +Description | +
|---|---|---|---|---|---|
1 | oSettings | object | DataTables settings object |
False will cancel the draw, anything else (including no + return) will allow it to complete.
$(document).ready( function() {
+ $('#example').dataTable( {
+ "fnPreDrawCallback": function( oSettings ) {
+ if ( $('#test').val() == 1 ) {
+ return false;
+ }
+ }
+ } );
+ } );
+ 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.
| + | Name | +Type | +Attributes | +Default | +Description | +
|---|---|---|---|---|---|
1 | nRow | node | "TR" element for the current row | ||
2 | aData | array | Raw data array for this row | ||
3 | iDisplayIndex | int | The display index for the current table draw | ||
4 | iDisplayIndexFull | int | The index of the data in the full list of + rows (after filtering) |
$(document).ready( function() {
+ $('#example').dataTable( {
+ "fnRowCallback": function( nRow, aData, iDisplayIndex, iDisplayIndexFull ) {
+ // Bold the grade for all 'A' grade browsers
+ if ( aData[4] == "A" )
+ {
+ $('td:eq(4)', nRow).html( 'A' );
+ }
+ }
+ } );
+ } );
+ This parameter allows you to override the default function which obtains +the data from the server ($.getJSON) so something more suitable for your +application. For example you could use POST data, or pull information from +a Gears or AIR database.
| + | Name | +Type | +Attributes | +Default | +Description | +
|---|---|---|---|---|---|
1 | sSource | string | HTTP source to obtain the data from (sAjaxSource) | ||
2 | aoData | array | A key/value pair object containing the data to send + to the server | ||
3 | fnCallback | function | to be called on completion of the data get + process that will draw the data on the page. | ||
4 | oSettings | object | DataTables settings object |
// POST data to server
+ $(document).ready( function() {
+ $('#example').dataTable( {
+ "bProcessing": true,
+ "bServerSide": true,
+ "sAjaxSource": "xhr.php",
+ "fnServerData": function ( sSource, aoData, fnCallback, oSettings ) {
+ oSettings.jqXHR = $.ajax( {
+ "dataType": 'json',
+ "type": "POST",
+ "url": sSource,
+ "data": aoData,
+ "success": fnCallback
+ } );
+ }
+ } );
+ } );
+ It is often useful to send extra data to the server when making an Ajax +request - for example custom filtering information, and this callback +function makes it trivial to send extra information to the server. The +passed in parameter is the data set that has been constructed by +DataTables, and you can add to this or modify it as you require.
| + | Name | +Type | +Attributes | +Default | +Description | +
|---|---|---|---|---|---|
1 | aoData | array | Data array (array of objects which are name/value + pairs) that has been constructed by DataTables and will be sent to the + server. In the case of Ajax sourced data with server-side processing + this will be an empty array, for server-side processing there will be a + significant number of parameters! |
Ensure that you modify the aoData array passed in, + as this is passed by reference.
$(document).ready( function() {
+ $('#example').dataTable( {
+ "bProcessing": true,
+ "bServerSide": true,
+ "sAjaxSource": "scripts/server_processing.php",
+ "fnServerParams": function ( aoData ) {
+ aoData.push( { "name": "more_data", "value": "my_value" } );
+ }
+ } );
+ } );
+ 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 its state saving +cookie, but you might wish to use local storage (HTML5) or a server-side database.
| + | Name | +Type | +Attributes | +Default | +Description | +
|---|---|---|---|---|---|
1 | oSettings | object | DataTables settings object |
The DataTables state object to be loaded
$(document).ready( function() {
+ $('#example').dataTable( {
+ "bStateSave": true,
+ "fnStateLoad": function (oSettings) {
+ var o;
+
+ // Send an Ajax request to the server to get the data. Note that
+ // this is a synchronous request.
+ $.ajax( {
+ "url": "/state_load",
+ "async": false,
+ "dataType": "json",
+ "success": function (json) {
+ o = json;
+ }
+ } );
+
+ return o;
+ }
+ } );
+ } );
+ Callback that is called when the state has been loaded from the state saving method +and the DataTables settings object has been modified as a result of the loaded state.
| + | Name | +Type | +Attributes | +Default | +Description | +
|---|---|---|---|---|---|
1 | oSettings | object | DataTables settings object | ||
2 | oData | object | The state object that was loaded |
// Show an alert with the filtering value that was saved
+ $(document).ready( function() {
+ $('#example').dataTable( {
+ "bStateSave": true,
+ "fnStateLoaded": function (oSettings, oData) {
+ alert( 'Saved filter was: '+oData.oSearch.sSearch );
+ }
+ } );
+ } );
+ Callback which allows modification of the saved state prior to loading that state. +This callback is called when the table is loading state from the stored data, but +prior to the settings object being modified by the saved state. Note that for +plug-in authors, you should use the 'stateLoadParams' event to load parameters for +a plug-in.
| + | Name | +Type | +Attributes | +Default | +Description | +
|---|---|---|---|---|---|
1 | oSettings | object | DataTables settings object | ||
2 | oData | object | The state object that is to be loaded |
// Remove a saved filter, so filtering is never loaded
+ $(document).ready( function() {
+ $('#example').dataTable( {
+ "bStateSave": true,
+ "fnStateLoadParams": function (oSettings, oData) {
+ oData.oSearch.sSearch = "";
+ }
+ } );
+ } );
+
+
+ // Disallow state loading by returning false
+ $(document).ready( function() {
+ $('#example').dataTable( {
+ "bStateSave": true,
+ "fnStateLoadParams": function (oSettings, oData) {
+ return false;
+ }
+ } );
+ } );
+ Save the table state. This function allows you to define where and how the state +information for the table is stored - by default it will use a cookie, but you +might want to use local storage (HTML5) or a server-side database.
| + | Name | +Type | +Attributes | +Default | +Description | +
|---|---|---|---|---|---|
1 | oSettings | object | DataTables settings object | ||
2 | oData | object | The state object to be saved |
$(document).ready( function() {
+ $('#example').dataTable( {
+ "bStateSave": true,
+ "fnStateSave": function (oSettings, oData) {
+ // Send an Ajax request to the server with the state object
+ $.ajax( {
+ "url": "/state_save",
+ "data": oData,
+ "dataType": "json",
+ "method": "POST"
+ "success": function () {}
+ } );
+ }
+ } );
+ } );
+ Callback which allows modification of the state to be saved. Called 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 or modification. Note that for plug-in authors, you should +use the 'stateSaveParams' event to save parameters for a plug-in.
| + | Name | +Type | +Attributes | +Default | +Description | +
|---|---|---|---|---|---|
1 | oSettings | object | DataTables settings object | ||
2 | oData | object | The state object to be saved |
// Remove a saved filter, so filtering is never saved
+ $(document).ready( function() {
+ $('#example').dataTable( {
+ "bStateSave": true,
+ "fnStateSaveParams": function (oSettings, oData) {
+ oData.oSearch.sSearch = "";
+ }
+ } );
+ } );
+ Duration of the cookie which is used for storing session information. This +value is given in seconds.
$(document).ready( function() {
+ $('#example').dataTable( {
+ "iCookieDuration": 60*60*24; // 1 day
+ } );
+ } )
+ When enabled DataTables will not make a request to the server for the first +page draw - rather it will use the data already on the page (no sorting etc +will be applied to it), thus saving on an XHR at load time. iDeferLoading +is used to indicate that deferred loading is required, but it is also used +to tell DataTables how many records there are in the full table (allowing +the information element and pagination to be displayed correctly). In the case +where a filtering is applied to the table on initial load, this can be +indicated by giving the parameter as an array, where the first element is +the number of records available after filtering and the second element is the +number of records without filtering (allowing the table information element +to be shown correctly).
// 57 records available in the table, no filtering applied
+ $(document).ready( function() {
+ $('#example').dataTable( {
+ "bServerSide": true,
+ "sAjaxSource": "scripts/server_processing.php",
+ "iDeferLoading": 57
+ } );
+ } );
+
+
+ // 57 records after filtering, 100 without filtering (an initial filter applied)
+ $(document).ready( function() {
+ $('#example').dataTable( {
+ "bServerSide": true,
+ "sAjaxSource": "scripts/server_processing.php",
+ "iDeferLoading": [ 57, 100 ],
+ "oSearch": {
+ "sSearch": "my_filter"
+ }
+ } );
+ } );
+ Number of rows to display on a single page when using pagination. If +feature enabled (bLengthChange) then the end user will be able to override +this to a custom setting using a pop-up menu.
$(document).ready( function() {
+ $('#example').dataTable( {
+ "iDisplayLength": 50
+ } );
+ } )
+ Define the starting point for data display when using DataTables with +pagination. Note that this parameter is the number of records, rather than +the page number, so if you have 10 records per page and want to start on +the third page, it should be "20".
$(document).ready( function() {
+ $('#example').dataTable( {
+ "iDisplayStart": 20
+ } );
+ } )
+ The scroll gap is the amount of scrolling that is left to go before +DataTables will load the next 'page' of data automatically. You typically +want a gap which is big enough that the scrolling will be smooth for the +user, while not so large that it will load more data than need.
$(document).ready( function() {
+ $('#example').dataTable( {
+ "bScrollInfinite": true,
+ "bScrollCollapse": true,
+ "sScrollY": "200px",
+ "iScrollLoadGap": 50
+ } );
+ } );
+ By default DataTables allows keyboard navigation of the table (sorting, paging, +and filtering) by adding a tabindex attribute to the required elements. This +allows you to tab through the controls and press the enter key to activate them. +The tabindex is default 0, meaning that the tab follows the flow of the document. +You can overrule this using this parameter if you wish. Use a value of -1 to +disable built-in keyboard navigation.
$(document).ready( function() {
+ $('#example').dataTable( {
+ "iTabIndex": 1
+ } );
+ } );
+ By default DataTables will look for the property 'aaData' when obtaining +data from an Ajax source or for server-side processing - this parameter +allows that property to be changed. You can use Javascript dotted object +notation to get a data source for multiple levels of nesting.
// Get data from { "data": [...] }
+ $(document).ready( function() {
+ var oTable = $('#example').dataTable( {
+ "sAjaxSource": "sources/data.txt",
+ "sAjaxDataProp": "data"
+ } );
+ } );
+
+
+ // Get data from { "data": { "inner": [...] } }
+ $(document).ready( function() {
+ var oTable = $('#example').dataTable( {
+ "sAjaxSource": "sources/data.txt",
+ "sAjaxDataProp": "data.inner"
+ } );
+ } );
+ You can instruct DataTables to load data from an external source using this +parameter (use aData if you want to pass data in you already have). Simply +provide a url a JSON object can be obtained from. This object must include +the parameter 'aaData' which is the data source for the table.
$(document).ready( function() {
+ $('#example').dataTable( {
+ "sAjaxSource": "http://www.sprymedia.co.uk/dataTables/json.php"
+ } );
+ } )
+ This parameter can be used to override the default prefix that DataTables +assigns to a cookie when state saving is enabled.
$(document).ready( function() {
+ $('#example').dataTable( {
+ "sCookiePrefix": "my_datatable_",
+ } );
+ } );
+ 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: +
$(document).ready( function() {
+ $('#example').dataTable( {
+ "sDom": '<"top"i>rt<"bottom"flp><"clear">'
+ } );
+ } );
+ 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).
$(document).ready( function() {
+ $('#example').dataTable( {
+ "sPaginationType": "full_numbers"
+ } );
+ } )
+ Enable horizontal scrolling. When a table is too wide to fit into a certain +layout, or you have a large number of columns in the table, you can enable +x-scrolling to show the table in a viewport, which can be scrolled. This +property can be any CSS unit, or a number (in which case it will be treated +as a pixel measurement).
$(document).ready( function() {
+ $('#example').dataTable( {
+ "sScrollX": "100%",
+ "bScrollCollapse": true
+ } );
+ } );
+ This property can be used to force a DataTable to use more width than it +might otherwise do when x-scrolling is enabled. For example if you have a +table which requires to be well spaced, this parameter is useful for +"over-sizing" the table, and thus forcing scrolling. This property can by +any CSS unit, or a number (in which case it will be treated as a pixel +measurement).
$(document).ready( function() {
+ $('#example').dataTable( {
+ "sScrollX": "100%",
+ "sScrollXInner": "110%"
+ } );
+ } );
+ Enable vertical scrolling. Vertical scrolling will constrain the DataTable +to the given height, and enable scrolling for any data which overflows the +current viewport. This can be used as an alternative to paging to display +a lot of data in a small area (although paging and scrolling can both be +enabled at the same time). This property can be any CSS unit, or a number +(in which case it will be treated as a pixel measurement).
$(document).ready( function() {
+ $('#example').dataTable( {
+ "sScrollY": "200px",
+ "bPaginate": false
+ } );
+ } );
+ Set the HTTP method that is used to make the Ajax call for server-side +processing or Ajax sourced data.
$(document).ready( function() {
+ $('#example').dataTable( {
+ "bServerSide": true,
+ "sAjaxSource": "scripts/post.php",
+ "sServerMethod": "POST"
+ } );
+ } );
+