diff --git a/src/main/resources/web/scripts/DataTables-1.9.1/DT_bootstrap.css b/src/main/resources/web/scripts/DataTables-1.9.1/DT_bootstrap.css new file mode 100644 index 0000000..8d51761 --- /dev/null +++ b/src/main/resources/web/scripts/DataTables-1.9.1/DT_bootstrap.css @@ -0,0 +1,47 @@ + +div.dataTables_length label { + float: left; + text-align: left; +} + +div.dataTables_length select { + width: 75px; +} + +div.dataTables_filter label { + float: right; +} + +div.dataTables_info { + padding-top: 8px; +} + +div.dataTables_paginate { + float: right; + margin: 0; +} + +table.table { + clear: both; + margin-bottom: 6px !important; +} + +table.table thead .sorting, +table.table thead .sorting_asc, +table.table thead .sorting_desc, +table.table thead .sorting_asc_disabled, +table.table thead .sorting_desc_disabled { + cursor: pointer; + *cursor: hand; +} + +table.table thead .sorting { background: url('media/images/sort_both.png') no-repeat center right; } +table.table thead .sorting_asc { background: url('media/images/sort_asc.png') no-repeat center right; } +table.table thead .sorting_desc { background: url('media/images/sort_desc.png') no-repeat center right; } + +table.table thead .sorting_asc_disabled { background: url('media/images/sort_asc_disabled.png') no-repeat center right; } +table.table thead .sorting_desc_disabled { background: url('media/images/sort_desc_disabled.png') no-repeat center right; } + +table.dataTable th:active { + outline: none; +} diff --git a/src/main/resources/web/scripts/DataTables-1.9.1/DT_bootstrap.js b/src/main/resources/web/scripts/DataTables-1.9.1/DT_bootstrap.js new file mode 100644 index 0000000..9f50504 --- /dev/null +++ b/src/main/resources/web/scripts/DataTables-1.9.1/DT_bootstrap.js @@ -0,0 +1,106 @@ +/* Default class modification */ +$.extend( $.fn.dataTableExt.oStdClasses, { + "sWrapper": "dataTables_wrapper form-inline" +} ); + +/* API method to get paging information */ +$.fn.dataTableExt.oApi.fnPagingInfo = function ( oSettings ) +{ + return { + "iStart": oSettings._iDisplayStart, + "iEnd": oSettings.fnDisplayEnd(), + "iLength": oSettings._iDisplayLength, + "iTotal": oSettings.fnRecordsTotal(), + "iFilteredTotal": oSettings.fnRecordsDisplay(), + "iPage": Math.ceil( oSettings._iDisplayStart / oSettings._iDisplayLength ), + "iTotalPages": Math.ceil( oSettings.fnRecordsDisplay() / oSettings._iDisplayLength ) + }; +} + +/* Bootstrap style pagination control */ +$.extend( $.fn.dataTableExt.oPagination, { + "bootstrap": { + "fnInit": function( oSettings, nPaging, fnDraw ) { + var oLang = oSettings.oLanguage.oPaginate; + var fnClickHandler = function ( e ) { + e.preventDefault(); + if ( oSettings.oApi._fnPageChange(oSettings, e.data.action) ) { + fnDraw( oSettings ); + } + }; + + $(nPaging).addClass('pagination').append( + '
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).
JSON stringify. If JSON.stringify it provided by the browser, json2.js or any other +library, then we use that as it is fast, safe and accurate. If the function isn't +available then we need to built it ourselves - the insperation for this function comes +from Craig Buckler ( http://www.sitepoint.com/javascript-json-serialization/ ). It is +not perfect and absolutely should not be used as a replacement to json2.js - but it does +do what we need, without requiring a dependency for DataTables.
Add a column to the list used for the table with default values
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | nTh | node | The th element for this column |
Add a data array to the table, creating DOM node etc. This is the parallel to +_fnGatherData, but for adding rows from a Javascript source, rather than a +DOM source.
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | aData | array | data array to be added |
>=0 if successful (index of new aoData entry), -1 if failed
Add the options to the page HTML for the table
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
Adjust the table column widths for new data. Note: you would probably want to +do a redraw after calling this function!
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
Build up the parameters in an object needed for a server-side processing request
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
block the table drawing or not
Update the table using an Ajax call
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
Block the table drawing or not
Data the data from the server (nuking the old) and redraw the table
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | json | object | json data return from the server. | ||
json.sEcho | string | Tracking flag for DataTables to match requests | |||
json.iTotalRecords | int | Number of records in the data set, not accounting for filtering | |||
json.iTotalDisplayRecords | int | Number of records in the data set, accounting for filtering | |||
json.aaData | array | The data to display on this page | |||
json.sColumns | string | <optional> | Column ordering (sName, comma separated) |
Take the column definitions and static columns arrays and calculate how +they relate to column indexes. The callback function will then apply the +definition found for a column to a suitable configuration object.
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | aoColDefs | array | The aoColumnDefs array that is to be applied | ||
3 | aoCols | array | The aoColumns array that defines columns individually | ||
4 | fn | function | Callback function - takes two parameters, the calculated + column index and the definition for that column. |
Apply a given function to the display child nodes of an element array (typically +TD children of TR rows
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | fn | function | Method to apply to the objects | ||
2 | array | {nodes} an1 List of elements to look through for display children | |||
3 | array | {nodes} an2 Another list (identical structure to the first) - optional |
Bind an event handers to allow a click or return key to activate the callback. +This is good for accessability since a return on the keyboard will have the +same effect as a click, if the element has focus.
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | n | element | Element to bind the action to | ||
2 | oData | object | Data object to pass to the triggered function | ||
3 | {function) | fn Callback function for when the event is triggered |
Create the HTML header for the table
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
Create an array which can be quickly search through
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | iMaster | int | use the master data array - optional |
Create a searchable string from a single data row
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | aData | array | Row data array to use for the data to search |
Calculate the width of columns for the table
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
Rcalculate the end point based on the start point
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
Fire callback functions and trigger events. Note that the loop over the callback +array store is done backwards! Further note that you do not want to fire off triggers +in time sensitive applications (for example cell creation) as its slow.
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | sStore | string | Name of the array storeage for the callbacks in oSettings | ||
3 | sTrigger | string | Name of the jQuery custom event to trigger. If null no trigger + is fired | ||
4 | {array) | aArgs Array of arguments to pass to the callback function / trigger |
Register a callback function. Easily allows a callback function to be added to +an array store of callback functions that can then all be called together.
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | sStore | string | Name of the array storeage for the callbacks in oSettings | ||
3 | fn | function | Function to be called back | ||
4 | {string) | sName Identifying name for the callback (i.e. a label) |
Nuke the table
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
Covert the index of an index in the data array and convert it to the visible + column index (take account of hidden columns)
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | iMatch | int | Column index to lookup | ||
2 | oSettings | object | dataTables settings object |
i the data index
Apply options for a column
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | iCol | int | column index to consider | ||
3 | oOptions | object | object with sType, bVisible and bSearchable |
Get the column ordering that DataTables expects
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
comma separated list of names
Convert a CSS unit width to pixels (e.g. 2em)
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | sWidth | string | width to be converted | ||
2 | nParent | node | parent to get the with for (required for relative widths) - optional |
iWidth width in pixels
Create a new cookie with a value to store the state of a table
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | sName | string | name of the cookie to create | ||
2 | sValue | string | the value the cookie should take | ||
3 | iSecs | int | duration of the cookie | ||
4 | sBaseName | string | sName is made up of the base + file name - this is the base | ||
5 | fnCallback | function | User definable function to modify the cookie |
Create a new TR element (and it's TD children) for a row
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | iRow | int | Row to consider |
Convert raw data into something that the user can search on
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | sData | string | data to be modified | ||
2 | sType | string | data type |
search string
Take an array of integers (index array) and remove a target integer (value - not +the key!)
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | a | array | Index array to target | ||
2 | iTarget | int | value to find |
Use the DOM source to create up an array of header cells. The idea here is to +create a layout grid (array) of rows x columns, which contains a reference +to the cell that that point in the grid (regardless of col/rowspan), such that +any column / row could be removed and the new grid constructed
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | array | {object} aLayout Array to store the calculated layout in | |||
2 | nThead | node | The header/footer element for the table |
Get the sort type based on an input string
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | sData | string | data we wish to know the type of |
type (defaults to 'string' if no type can be detected)
Insert the required TR nodes into the table for display
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
Draw the header (or footer) element based on the column visibility states. The +methodology here is to use the layout array from _fnDetectHeader, modified for +the instantaneous column visibility, to construct the new layout. The grid is +traversed over cell at a time in a rows x columns grid fashion, although each +cell insert can cover multiple elements in the grid - which is tracks using the +aApplied array. Cell inserts in the grid will only occur where there isn't +already a cell in that position.
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | array | {objects} aoSource Layout array from _fnDetectHeader | |||
3 | bIncludeHidden | boolean | Optional | false | If true then include the hidden columns in the calc, |
scape a string stuch that it can be used in a regular expression
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | sVal | string | string to escape |
escaped string
Extend objects - very similar to jQuery.extend, but deep copy objects, and shallow +copy arrays. The reason we need to do this, is that we don't want to deep copy array +init values (such as aaSorting) since the dev wouldn't be able to override them, but +we do want to deep copy arrays.
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oOut | object | Object to extend | ||
2 | oExtender | object | Object from which the properties will be applied to oOut |
oOut Reference, just for convenience - oOut === the return.
Create a wrapper function for exporting an internal functions to an external API.
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | sFunc | string | API function name |
wrapped function
Generate the node required for filtering text
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
Filter control element
Generate the node required for the info display
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
Information element
Generate the node required for user display length changing
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
Display length feature node
Generate the node required for default pagination
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
Pagination feature node
Generate the node required for the processing node
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
Processing element
Add any control elements for the table - specifically scrolling
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
Node to add to the DOM
Filter the data table based on user input and draw the table
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | sInput | string | string to filter on | ||
3 | iForce | int | optional - force a research of the master array (1) or not (undefined or 0) | ||
4 | bRegex | bool | treat as a regular expression or not | ||
5 | bSmart | bool | perform smart filtering or not | ||
6 | bCaseInsensitive | bool | Do case insenstive matching or not |
Filter the table on a per-column basis
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | sInput | string | string to filter on | ||
3 | iColumn | int | column to filter | ||
4 | bRegex | bool | treat search string as a regular expression or not | ||
5 | bSmart | bool | use smart filtering or not | ||
6 | bCaseInsensitive | bool | Do case insenstive matching or not |
Filter the table using both the global filter and column based filtering
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | oSearch | object | search information | ||
3 | iForce | int | Optional | force a research of the master array (1) or not (undefined or 0) |
Build a regular expression object suitable for searching a table
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | sSearch | string | string to search for | ||
2 | bRegex | bool | treat as a regular expression or not | ||
3 | bSmart | bool | perform smart filtering or not | ||
4 | bCaseInsensitive | bool | Do case insenstive matching or not |
constructed object
Apply custom filtering functions
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
Read in the data from the target table from the DOM
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
Get the data for a given cell from the internal cache, taking into account data mapping
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | iRow | int | aoData row id | ||
3 | iCol | int | Column index | ||
4 | sSpecific | string | data get type ('display', 'type' 'filter' 'sort') |
Cell data
Return an array with the full table data
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
array {array} aData Master data array
Get the maximum strlen for each data column
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | iCol | int | column of interest |
max strlens for each column
Return a function that can be used to get data from a source object, taking +into account the ability to use nested objects as a source
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | mSource | string | int | function | The data source for the object |
Data get function
Get an array of data for a given row from the internal data cache
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | iRow | int | aoData row id | ||
3 | sSpecific | string | data get type ('type' 'filter' 'sort') |
Data array
Return an flat array with all TD nodes for the table, or row
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | iIndividualRow | int | Optional | aoData index to get the nodes for - optional + if not given then the return array will contain all nodes for the table |
TD array
Return an array with the TR nodes for the table
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
TR array
Get an array of unique th elements, one for each column
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | nHeader | node | automatically detect the layout from this node - optional | ||
3 | aLayout | array | thead/tfoot layout from _fnDetectHeader - optional |
array {node} aReturn list of unique ths
Get the widest node
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | iCol | int | column of interest |
max strlens for each column
Draw the table for the first time, adding all required features
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | json | object | Optional | JSON from the server that completed the table, if using Ajax source + with client-side processing (optional) |
Draw the table for the first time, adding all required features
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
Language compatibility - when certain options are given, and others aren't, we +need to duplicate the values over, in order to provide backwards compatibility +with older language files.
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
Attempt to load a saved table state from a cookie
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | oInit | object | DataTables init object so we can override settings |
Log an error message
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | iLevel | int | log error messages, or display them to the user | ||
3 | sMesg | string | error message |
See if a property is defined on one object, if so assign it to the other object
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oRet | object | target object | ||
2 | oSrc | object | source object | ||
3 | sName | string | property | ||
4 | sMappedName | string | Optional | name to map too - optional, sName used if not given |
Take a TD element and convert it into a column data index (not the visible index)
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | iRow | int | The row number the TD/TH can be found in | ||
3 | n | node | The TD/TH element to find |
index if the node is found, -1 if not
Take a TR element and convert it to an index in aoData
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | n | node | the TR element to find |
index if the node is found, null if not
Alter the display settings to change the page
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | mAction | string | int | Paging action to take: "first", "previous", "next" or "last" + or page number to jump to (integer) |
true page has changed, false - no change (no effect) eg 'first' on page 1
Display or hide the processing indicator
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | bShow | bool | Show the processing indicator (true) or not (false) |
Read an old cookie to get a cookie with an old table state
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | sName | string | name of the cookie to read |
contents of the cookie - or null if no cookie with that name found
Redraw the table - taking account of the various features which are enabled
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
Call the developer defined fnRender function for a given cell (row/column) with +the required parameters and return the result.
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | iRow | int | aoData index for the row | ||
3 | iCol | int | aoColumns index for the column |
Return of the developer's fnRender function
Figure out how to reorder a display list
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
array {int} aiReturn index list for reordering
Save the state of a table in a cookie such that the page can be reloaded
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
Get the width of a scroll bar in this browser being used
width in pixels
Update the various tables for resizing. It's a bit of a pig this function, but +basically the idea to: + 1. Re-create the table inside the scrolling div + 2. Take live measurements from the DOM + 3. Apply the measurements + 4. Clean up
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | o | object | dataTables settings object |
Node to add to the DOM
Adjust a table's width to take account of scrolling
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | n | node | table node |
Add Ajax parameters from plugins
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | array | {objects} aoData name/value pairs to send to the server |
Set the value for a specific cell, into the internal data cache
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | iRow | int | aoData row id | ||
3 | iCol | int | Column index | ||
4 | val | * | Value to set |
Return a function that can be used to set data from a source object, taking +into account the ability to use nested objects as a source
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | mSource | string | int | function | The data source for the object |
Data set function
Return the settings object for a particular table
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | nTable | node | table we are using as a dataTable |
Settings object - or null if not found
Change the order of the table
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | bApplyClasses | bool | optional - should we apply classes or not |
Attach a sort handler (click) to a node
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | nNode | node | node to attach the handler to | ||
3 | iDataIndex | int | column sorting index | ||
4 | fnCallback | function | Optional | callback function |
Set the sorting classes on the header, Note: it is safe to call this function +when bSort and bSortClasses are false
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
Append a CSS unit (only if required) to a string
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | aArray1 | array | first array | ||
2 | aArray2 | array | second array |
0 if match, 1 if length is different, 2 if no match
Update the information elements in the display
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object |
Get the number of visible columns
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oS | object | dataTables settings object |
i the number of visible columns
Covert the index of a visible column to the index in the data array (take account +of hidden columns)
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oSettings | object | dataTables settings object | ||
2 | iMatch | int | Visible column index to lookup |
i the data index
Column options that can be given to DataTables at initialisation time.
Allows a column's sorting to take multiple columns into account when +doing a sort. For example first name / last name columns make sense to +do a multi-column sort over the two columns.
// Using aoColumnDefs + $(document).ready(function() { + $('#example').dataTable( { + "aoColumnDefs": [ + { "aDataSort": [ 0, 1 ], "aTargets": [ 0 ] }, + { "aDataSort": [ 1, 0 ], "aTargets": [ 1 ] }, + { "aDataSort": [ 2, 3, 4 ], "aTargets": [ 2 ] } + ] + } ); + } ); + ++
// Using aoColumns + $(document).ready(function() { + $('#example').dataTable( { + "aoColumns": [ + { "aDataSort": [ 0, 1 ] }, + { "aDataSort": [ 1, 0 ] }, + { "aDataSort": [ 2, 3, 4 ] }, + null, + null + ] + } ); + } );+
You can control the default sorting direction, and even alter the behaviour +of the sort handler (i.e. only allow ascending sorting etc) using this +parameter.
// Using aoColumnDefs + $(document).ready(function() { + $('#example').dataTable( { + "aoColumnDefs": [ + { "asSorting": [ "asc" ], "aTargets": [ 1 ] }, + { "asSorting": [ "desc", "asc", "asc" ], "aTargets": [ 2 ] }, + { "asSorting": [ "desc" ], "aTargets": [ 3 ] } + ] + } ); + } ); + ++
// Using aoColumns + $(document).ready(function() { + $('#example').dataTable( { + "aoColumns": [ + null, + { "asSorting": [ "asc" ] }, + { "asSorting": [ "desc", "asc", "asc" ] }, + { "asSorting": [ "desc" ] }, + null + ] + } ); + } );+
Enable or disable filtering on the data in this column.
// Using aoColumnDefs + $(document).ready(function() { + $('#example').dataTable( { + "aoColumnDefs": [ + { "bSearchable": false, "aTargets": [ 0 ] } + ] } ); + } ); + ++
// Using aoColumns + $(document).ready(function() { + $('#example').dataTable( { + "aoColumns": [ + { "bSearchable": false }, + null, + null, + null, + null + ] } ); + } );+
Enable or disable sorting on this column.
// Using aoColumnDefs + $(document).ready(function() { + $('#example').dataTable( { + "aoColumnDefs": [ + { "bSortable": false, "aTargets": [ 0 ] } + ] } ); + } ); + ++
// Using aoColumns + $(document).ready(function() { + $('#example').dataTable( { + "aoColumns": [ + { "bSortable": false }, + null, + null, + null, + null + ] } ); + } );+
When using fnRender() for a column, you may wish to use the original data +(before rendering) for sorting and filtering (the default is to used the +rendered data that the user can see). This may be useful for dates etc. +NOTE* It is it is advisable now to use mDataProp as a function and make +use of the 'type' that it gives, allowing (potentially) different data to +be used for sorting, filtering, display and type detection.
// Using aoColumnDefs + $(document).ready(function() { + $('#example').dataTable( { + "aoColumnDefs": [ + { + "fnRender": function ( oObj ) { + return oObj.aData[0] +' '+ oObj.aData[3]; + }, + "bUseRendered": false, + "aTargets": [ 0 ] + } + ] + } ); + } ); + ++
// Using aoColumns + $(document).ready(function() { + $('#example').dataTable( { + "aoColumns": [ + { + "fnRender": function ( oObj ) { + return oObj.aData[0] +' '+ oObj.aData[3]; + }, + "bUseRendered": false + }, + null, + null, + null, + null + ] + } ); + } );+
Enable or disable the display of this column.
// Using aoColumnDefs + $(document).ready(function() { + $('#example').dataTable( { + "aoColumnDefs": [ + { "bVisible": false, "aTargets": [ 0 ] } + ] } ); + } ); + ++
// Using aoColumns + $(document).ready(function() { + $('#example').dataTable( { + "aoColumns": [ + { "bVisible": false }, + null, + null, + null, + null + ] } ); + } );+
Developer definable function that is called whenever a cell is created (Ajax source, +etc) or processed for input (DOM source). This can be used as a compliment to fnRender +allowing you to modify the DOM element (add background colour for example) when the +element is available (since it is not when fnRender is called).
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | nTd | element | The TD node that has been created | ||
2 | sData | * | The Data for the cell | ||
3 | oData | array | object | The data for the whole row | ||
4 | iRow | int | The row index for the aoData data store | ||
5 | iCol | int | The column index for aoColumns |
$(document).ready(function() { + $('#example').dataTable( { + "aoColumnDefs": [ { + "aTargets": [3], + "fnCreatedCell": function (nTd, sData, oData, iRow, iCol) { + if ( sData == "1.7" ) { + $(nTd).css('color', 'blue') + } + } + } ] + }); + } );+
Custom display function that will be called for the display of each cell in +this column.
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | o | object | Object with the following parameters: | ||
o.iDataRow | int | The row in aoData | |||
o.iDataColumn | int | The column in question | |||
o.aData | array | The data for the row in question | |||
o.oSettings | object | The settings object for this DataTables instance | |||
o.mDataProp | object | The data property used for this column | |||
7 | val | * | The current cell value |
The string you which to use in the display
// Using aoColumnDefs + $(document).ready(function() { + $('#example').dataTable( { + "aoColumnDefs": [ + { + "fnRender": function ( o, val ) { + return o.aData[0] +' '+ o.aData[3]; + }, + "aTargets": [ 0 ] + } + ] + } ); + } ); + ++
// Using aoColumns + $(document).ready(function() { + $('#example').dataTable( { + "aoColumns": [ + { "fnRender": function ( o, val ) { + return o.aData[0] +' '+ o.aData[3]; + } }, + null, + null, + null, + null + ] + } ); + } );+
The column index (starting from 0!) that you wish a sort to be performed +upon when this column is selected for sorting. This can be used for sorting +on hidden columns for example.
// Using aoColumnDefs + $(document).ready(function() { + $('#example').dataTable( { + "aoColumnDefs": [ + { "iDataSort": 1, "aTargets": [ 0 ] } + ] + } ); + } ); + ++
// Using aoColumns + $(document).ready(function() { + $('#example').dataTable( { + "aoColumns": [ + { "iDataSort": 1 }, + null, + null, + null, + null + ] + } ); + } );+
This property can be used to read data from any JSON data source property, +including deeply nested objects / properties. mDataProp can be given in a +number of different ways which effect its behaviour: +
// Read table data from objects + $(document).ready(function() { + var oTable = $('#example').dataTable( { + "sAjaxSource": "sources/deep.txt", + "aoColumns": [ + { "mDataProp": "engine" }, + { "mDataProp": "browser" }, + { "mDataProp": "platform.inner" }, + { "mDataProp": "platform.details.0" }, + { "mDataProp": "platform.details.1" } + ] + } ); + } ); + ++
// Using mDataProp as a function to provide different information for + // sorting, filtering and display. In this case, currency (price) + $(document).ready(function() { + var oTable = $('#example').dataTable( { + "aoColumnDefs": [ + { + "aTargets": [ 0 ], + "mDataProp": function ( source, type, val ) { + if (type === 'set') { + source.price = val; + // Store the computed dislay and filter values for efficiency + source.price_display = val=="" ? "" : "$"+numberFormat(val); + source.price_filter = val=="" ? "" : "$"+numberFormat(val)+" "+val; + return; + } + else if (type === 'display') { + return source.price_display; + } + else if (type === 'filter') { + return source.price_filter; + } + // 'sort', 'type' and undefined all just use the integer + return source.price; + } + ] + } ); + } );+
Change the cell type created for the column - either TD cells or TH cells. This +can be useful as TH cells have semantic meaning in the table body, allowing them +to act as a header for a row (you may wish to add scope='row' to the TH elements).
// Make the first column use TH cells + $(document).ready(function() { + var oTable = $('#example').dataTable( { + "aoColumnDefs": [ + { + "aTargets": [ 0 ], + "sCellType": "th" + ] + } ); + } );+
Class to give to each cell in this column.
// Using aoColumnDefs + $(document).ready(function() { + $('#example').dataTable( { + "aoColumnDefs": [ + { "sClass": "my_class", "aTargets": [ 0 ] } + ] + } ); + } ); + ++
// Using aoColumns + $(document).ready(function() { + $('#example').dataTable( { + "aoColumns": [ + { "sClass": "my_class" }, + null, + null, + null, + null + ] + } ); + } );+
When DataTables calculates the column widths to assign to each column, +it finds the longest string in each column and then constructs a +temporary table and reads the widths from that. The problem with this +is that "mmm" is much wider then "iiii", but the latter is a longer +string - thus the calculation can go wrong (doing it properly and putting +it into an DOM object and measuring that is horribly(!) slow). Thus as +a "work around" we provide this option. It will append its value to the +text that is found to be the longest string for the column - i.e. padding. +Generally you shouldn't need this, and it is not documented on the +general DataTables.net documentation
// Using aoColumns + $(document).ready(function() { + $('#example').dataTable( { + "aoColumns": [ + null, + null, + null, + { + "sContentPadding": "mmm" + } + ] + } ); + } );+
Allows a default value to be given for a column's data, and will be used +whenever a null data source is encountered (this can be because mDataProp +is set to null, or because the data source itself is null).
// Using aoColumnDefs + $(document).ready(function() { + $('#example').dataTable( { + "aoColumnDefs": [ + { + "mDataProp": null, + "sDefaultContent": "Edit", + "aTargets": [ -1 ] + } + ] + } ); + } ); + ++
// Using aoColumns + $(document).ready(function() { + $('#example').dataTable( { + "aoColumns": [ + null, + null, + null, + { + "mDataProp": null, + "sDefaultContent": "Edit" + } + ] + } ); + } );+
This parameter is only used in DataTables' server-side processing. It can +be exceptionally useful to know what columns are being displayed on the +client side, and to map these to database fields. When defined, the names +also allow DataTables to reorder information from the server if it comes +back in an unexpected order (i.e. if you switch your columns around on the +client-side, your server-side code does not also need updating).
// Using aoColumnDefs + $(document).ready(function() { + $('#example').dataTable( { + "aoColumnDefs": [ + { "sName": "engine", "aTargets": [ 0 ] }, + { "sName": "browser", "aTargets": [ 1 ] }, + { "sName": "platform", "aTargets": [ 2 ] }, + { "sName": "version", "aTargets": [ 3 ] }, + { "sName": "grade", "aTargets": [ 4 ] } + ] + } ); + } ); + ++
// Using aoColumns + $(document).ready(function() { + $('#example').dataTable( { + "aoColumns": [ + { "sName": "engine" }, + { "sName": "browser" }, + { "sName": "platform" }, + { "sName": "version" }, + { "sName": "grade" } + ] + } ); + } );+
Defines a data source type for the sorting which can be used to read +realtime information from the table (updating the internally cached +version) prior to sorting. This allows sorting to occur on user editable +elements such as form inputs.
// Using aoColumnDefs + $(document).ready(function() { + $('#example').dataTable( { + "aoColumnDefs": [ + { "sSortDataType": "dom-text", "aTargets": [ 2, 3 ] }, + { "sType": "numeric", "aTargets": [ 3 ] }, + { "sSortDataType": "dom-select", "aTargets": [ 4 ] }, + { "sSortDataType": "dom-checkbox", "aTargets": [ 5 ] } + ] + } ); + } ); + ++
// Using aoColumns + $(document).ready(function() { + $('#example').dataTable( { + "aoColumns": [ + null, + null, + { "sSortDataType": "dom-text" }, + { "sSortDataType": "dom-text", "sType": "numeric" }, + { "sSortDataType": "dom-select" }, + { "sSortDataType": "dom-checkbox" } + ] + } ); + } );+
The title of this column.
// Using aoColumnDefs + $(document).ready(function() { + $('#example').dataTable( { + "aoColumnDefs": [ + { "sTitle": "My column title", "aTargets": [ 0 ] } + ] + } ); + } ); + ++
// Using aoColumns + $(document).ready(function() { + $('#example').dataTable( { + "aoColumns": [ + { "sTitle": "My column title" }, + null, + null, + null, + null + ] + } ); + } );+
The type allows you to specify how the data for this column will be sorted. +Four types (string, numeric, date and html (which will strip HTML tags +before sorting)) are currently available. Note that only date formats +understood by Javascript's Date() object will be accepted as type date. For +example: "Mar 26, 2008 5:03 PM". May take the values: 'string', 'numeric', +'date' or 'html' (by default). Further types can be adding through +plug-ins.
// Using aoColumnDefs + $(document).ready(function() { + $('#example').dataTable( { + "aoColumnDefs": [ + { "sType": "html", "aTargets": [ 0 ] } + ] + } ); + } ); + ++
// Using aoColumns + $(document).ready(function() { + $('#example').dataTable( { + "aoColumns": [ + { "sType": "html" }, + null, + null, + null, + null + ] + } ); + } );+
Defining the width of the column, this parameter may take any CSS value +(3em, 20px etc). DataTables applys 'smart' widths to columns which have not +been given a specific width through this interface ensuring that the table +remains readable.
// Using aoColumnDefs + $(document).ready(function() { + $('#example').dataTable( { + "aoColumnDefs": [ + { "sWidth": "20%", "aTargets": [ 0 ] } + ] + } ); + } ); + ++
// Using aoColumns + $(document).ready(function() { + $('#example').dataTable( { + "aoColumns": [ + { "sWidth": "20%" }, + null, + null, + null, + null + ] + } ); + } );+
Initialisation options that can be given to DataTables at initialisation +time.
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 (mDataProp) + $(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", "mDataProp": "engine" }, + { "sTitle": "Browser", "mDataProp": "browser" }, + { "sTitle": "Platform", "mDataProp": "platform" }, + { "sTitle": "Version", "mDataProp": "version" }, + { "sTitle": "Grade", "mDataProp": "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 ) { + $.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, oData) { + 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"&lgt;' + } ); + } );+
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" + } ); + } );+
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 string is shown in preference to sZeroRecords when the table is +empty of data (regardless of filtering). Note that this is an optional +parameter - if it is not given, the value of sZeroRecords will be used +instead (either the default or given value).
$(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sEmptyTable": "No data available in table" + } + } ); + } );+
This string gives information to the end user about the information that +is current on display on the page. The _START_, _END_ and _TOTAL_ +variables are all dynamically replaced as the table display updates, and +can be freely moved or removed as the language requirements change.
$(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sInfo": "Got a total of _TOTAL_ entries to show (_START_ to _END_)" + } + } ); + } );+
Display information string for when the table is empty. Typically the +format of this string should match sInfo.
$(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sInfoEmpty": "No entries to show" + } + } ); + } );+
When a user filters the information in a table, this string is appended +to the information (sInfo) to give an idea of how strong the filtering +is. The variable _MAX_ is dynamically updated.
$(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sInfoFiltered": " - filtering from _MAX_ records" + } + } ); + } );+
If can be useful to append extra information to the info string at times, +and this variable does exactly that. This information will be appended to +the sInfo (sInfoEmpty and sInfoFiltered in whatever combination they are +being used) at all times.
$(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sInfoPostFix": "All records shown are derived from real information." + } + } ); + } );+
DataTables has a build in number formatter (fnFormatNumber) which is used +to format large numbers that are used in the table information. By +default a comma is used, but this can be trivially changed to any +character you wish with this parameter.
$(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sInfoThousands": "'" + } + } ); + } );+
Detail the action that will be taken when the drop down menu for the +pagination length option is changed. The '_MENU_' variable is replaced +with a default select list of 10, 25, 50 and 100, and can be replaced +with a custom select box if required.
// Language change only + $(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sLengthMenu": "Display _MENU_ records" + } + } ); + } ); + ++
// Language and options change + $(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sLengthMenu": 'Display records' + } + } ); + } );+
When using Ajax sourced data and during the first draw when DataTables is +gathering the data, this message is shown in an empty row in the table to +indicate to the end user the the data is being loaded. Note that this +parameter is not used when loading data by server-side processing, just +Ajax sourced data with client-side processing.
$(document).ready( function() { + $('#example').dataTable( { + "oLanguage": { + "sLoadingRecords": "Please wait - loading..." + } + } ); + } );+
Text which is displayed when the table is processing a user action +(usually a sort command or similar).
$(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sProcessing": "DataTables is currently busy" + } + } ); + } );+
Details the actions that will be taken when the user types into the +filtering input text box. The variable "_INPUT_", if used in the string, +is replaced with the HTML text box for the filtering input allowing +control over where it appears in the string. If "_INPUT_" is not given +then the input box is appended to the string automatically.
// Input text box will be appended at the end automatically + $(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sSearch": "Filter records:" + } + } ); + } ); + ++
// Specify where the filter should appear + $(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sSearch": "Apply filter _INPUT_ to table" + } + } ); + } );+
All of the language information can be stored in a file on the +server-side, which DataTables will look up if this parameter is passed. +It must store the URL of the language file, which is in a JSON format, +and the object has the same properties as the oLanguage object in the +initialiser object (i.e. the above parameters). Please refer to one of +the example language files to see how this works in action.
$(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sUrl": "http://www.sprymedia.co.uk/dataTables/lang.txt" + } + } ); + } );+
Text shown inside the table records when the is no information to be +displayed after filtering. sEmptyTable is shown when there is simply no +information in the table at all (regardless of filtering).
$(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sZeroRecords": "No records to display" + } + } ); + } );+
Strings that are used for WAI-ARIA labels and controls only (these are not +actually visible on the page, but will be read by screenreaders, and thus +must be internationalised as well).
ARIA label that is added to the table headers when the column may be +sorted ascending by activing the column (click or return when focused). +Note that the column header is prefixed to this string.
$(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "oAria": { + "sSortAscending": " - click/return to sort ascending" + } + } + } ); + } );+
ARIA label that is added to the table headers when the column may be +sorted descending by activing the column (click or return when focused). +Note that the column header is prefixed to this string.
$(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "oAria": { + "sSortDescending": " - click/return to sort descending" + } + } + } ); + } );+
Pagination string used by DataTables for the two built-in pagination +control types ("two_button" and "full_numbers")
Text to use when using the 'full_numbers' type of pagination for the +button to take the user to the first page.
$(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "oPaginate": { + "sFirst": "First page" + } + } + } ); + } );+
Text to use when using the 'full_numbers' type of pagination for the +button to take the user to the last page.
$(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "oPaginate": { + "sLast": "Last page" + } + } + } ); + } );+
Text to use when using the 'full_numbers' type of pagination for the +button to take the user to the next page.
$(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "oPaginate": { + "sNext": "Next page" + } + } + } ); + } );+
Text to use when using the 'full_numbers' type of pagination for the +button to take the user to the previous page.
$(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "oPaginate": { + "sPrevious": "Previous page" + } + } + } ); + } );+
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.
$(document).ready( function() { + $('#example').dataTable( { + "oSearch": {"sSearch": "Initial search"} + } ); + } )+
Flag to indicate if the filtering should be case insensitive or not
Flag to indicate if the search term should be interpreted as a +regular expression (true) or not (false) and therefore and special +regex characters escaped.
Flag to indicate if DataTables is to use its smart filtering or not.
Applied search term
Extension object for DataTables that is used to provide all extension options.
Note that the DataTable.ext object is available through
+jQuery.fn.dataTable.ext where it may be accessed and manipulated. It is
+also aliased to jQuery.fn.dataTableExt for historic reasons.
Plug-in filtering functions - this method of filtering is complimentary to the default +type based filtering, and a lot more comprehensive as it allows you complete control +over the filtering logic. Each element in this array is a function (parameters +described below) that is called for every row in the table, and your logic decides if +it should be included in the filtered data set or not. +
// The following example shows custom filtering being applied to the fourth column (i.e. + // the aData[3] index) based on two input values from the end-user, matching the data in + // a certain range. + $.fn.dataTableExt.afnFiltering.push( + function( oSettings, aData, iDataIndex ) { + var iMin = document.getElementById('min').value * 1; + var iMax = document.getElementById('max').value * 1; + var iVersion = aData[3] == "-" ? 0 : aData[3]*1; + if ( iMin == "" && iMax == "" ) { + return true; + } + else if ( iMin == "" && iVersion < iMax ) { + return true; + } + else if ( iMin < iVersion && "" == iMax ) { + return true; + } + else if ( iMin < iVersion && iVersion < iMax ) { + return true; + } + return false; + } + );+
Plug-in sorting functions - this method of sorting is complimentary to the default type +based sorting that DataTables does automatically, allowing much greater control over the +the data that is being used to sort a column. This is useful if you want to do sorting +based on live data (for example the contents of an 'input' element) rather than just the +static string that DataTables knows of. The way these plug-ins work is that you create +an array of the values you wish to be sorted for the column in question and then return +that array. Which pre-sorting function is run here depends on the sSortDataType parameter +that is used for the column (if any). This is the corollary of ofnSearch for sort +data. +
// Updating the cached sorting information with user entered values in HTML input elements + jQuery.fn.dataTableExt.afnSortData['dom-text'] = function ( oSettings, iColumn ) + { + var aData = []; + $( 'td:eq('+iColumn+') input', oSettings.oApi._fnGetTrNodes(oSettings) ).each( function () { + aData.push( this.value ); + } ); + return aData; + }+
Feature plug-ins - This is an array of objects which describe the feature plug-ins that are +available to DataTables. These feature plug-ins are accessible through the sDom initialisation +option. As such, each feature plug-in must describe a function that is used to initialise +itself (fnInit), a character so the feature can be enabled by sDom (cFeature) and the name +of the feature (sFeature). Thus the objects attached to this method must provide: +
// How TableTools initialises itself. + $.fn.dataTableExt.aoFeatures.push( { + "fnInit": function( oSettings ) { + return new TableTools( { "oDTSettings": oSettings } ); + }, + "cFeature": "T", + "sFeature": "TableTools" + } );+
Type detection plug-in functions - DataTables utilises types to define how sorting and +filtering behave, and types can be either be defined by the developer (sType for the +column) or they can be automatically detected by the methods in this array. The functions +defined in the array are quite simple, taking a single parameter (the data to analyse) +and returning the type if it is a known type, or null otherwise. +
// Currency type detection plug-in: + jQuery.fn.dataTableExt.aTypes.push( + function ( sData ) { + var sValidChars = "0123456789.-"; + var Char; + + // Check the numeric part + for ( i=1 ; i+
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' ) ); + } );+
Index for what 'this' index API functions should use
Container for all private functions in DataTables so they can be exposed externally
Pre-processing of filtering data plug-ins - When you assign the sType for a column +(or have it automatically detected for you by DataTables or a type detection plug-in), +you will typically be using this for custom sorting, but it can also be used to provide +custom filtering by allowing you to pre-processing the data and returning the data in +the format that should be filtered upon. This is done by adding functions this object +with a parameter name which matches the sType for that target column. This is the +corollary of afnSortData for filtering data. +
$.fn.dataTableExt.ofnSearch['title-numeric'] = function ( sData ) { + return sData.replace(/\n/g," ").replace( /<.*?>/g, "" ); + }+
Storage for the various classes that DataTables uses - jQuery UI suitable
Pagination plug-in methods - The style and controls of the pagination can significantly +impact on how the end user interacts with the data in your table, and DataTables allows +the addition of pagination controls by extending this object, which can then be enabled +through the sPaginationType initialisation parameter. Each pagination type that +is added is an object (the property name of which is what sPaginationType refers +to) that has two properties, both methods that are used by DataTables to update the +control's state. +
$.fn.dataTableExt.oPagination.four_button = { + "fnInit": function ( oSettings, nPaging, fnCallbackDraw ) { + nFirst = document.createElement( 'span' ); + nPrevious = document.createElement( 'span' ); + nNext = document.createElement( 'span' ); + nLast = document.createElement( 'span' ); + + nFirst.appendChild( document.createTextNode( oSettings.oLanguage.oPaginate.sFirst ) ); + nPrevious.appendChild( document.createTextNode( oSettings.oLanguage.oPaginate.sPrevious ) ); + nNext.appendChild( document.createTextNode( oSettings.oLanguage.oPaginate.sNext ) ); + nLast.appendChild( document.createTextNode( oSettings.oLanguage.oPaginate.sLast ) ); + + nFirst.className = "paginate_button first"; + nPrevious.className = "paginate_button previous"; + nNext.className="paginate_button next"; + nLast.className = "paginate_button last"; + + nPaging.appendChild( nFirst ); + nPaging.appendChild( nPrevious ); + nPaging.appendChild( nNext ); + nPaging.appendChild( nLast ); + + $(nFirst).click( function () { + oSettings.oApi._fnPageChange( oSettings, "first" ); + fnCallbackDraw( oSettings ); + } ); + + $(nPrevious).click( function() { + oSettings.oApi._fnPageChange( oSettings, "previous" ); + fnCallbackDraw( oSettings ); + } ); + + $(nNext).click( function() { + oSettings.oApi._fnPageChange( oSettings, "next" ); + fnCallbackDraw( oSettings ); + } ); + + $(nLast).click( function() { + oSettings.oApi._fnPageChange( oSettings, "last" ); + fnCallbackDraw( oSettings ); + } ); + + $(nFirst).bind( 'selectstart', function () { return false; } ); + $(nPrevious).bind( 'selectstart', function () { return false; } ); + $(nNext).bind( 'selectstart', function () { return false; } ); + $(nLast).bind( 'selectstart', function () { return false; } ); + }, + + "fnUpdate": function ( oSettings, fnCallbackDraw ) { + if ( !oSettings.aanFeatures.p ) { + return; + } + + // Loop over each instance of the pager + var an = oSettings.aanFeatures.p; + for ( var i=0, iLen=an.length ; i+
Sorting plug-in methods - Sorting in DataTables is based on the detected type of the +data column (you can add your own type detection functions, or override automatic +detection using sType). With this specific type given to the column, DataTables will +apply the required sort from the functions in the object. Each sort type must provide +two mandatory methods, one each for ascending and descending sorting, and can optionally +provide a pre-formatting method that will help speed up sorting by allowing DataTables +to pre-format the sort data only once (rather than every time the actual sort functions +are run). The two sorting functions are typical Javascript sort methods: +
// Case-sensitive string sorting, with no pre-formatting method + $.extend( $.fn.dataTableExt.oSort, { + "string-case-asc": function(x,y) { + return ((x < y) ? -1 : ((x > y) ? 1 : 0)); + }, + "string-case-desc": function(x,y) { + return ((x < y) ? 1 : ((x > y) ? -1 : 0)); + } + } ); + ++
// Case-insensitive string sorting, with pre-formatting + $.extend( $.fn.dataTableExt.oSort, { + "string-pre": function(x) { + return x.toLowerCase(); + }, + "string-asc": function(x,y) { + return ((x < y) ? -1 : ((x > y) ? 1 : 0)); + }, + "string-desc": function(x,y) { + return ((x < y) ? 1 : ((x > y) ? -1 : 0)); + } + } );+
Storage for the various classes that DataTables uses
How should DataTables report an error. Can take the value 'alert' or 'throw'
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
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 + } ); + } );+
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 decendents, 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 incombination 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)] 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 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(); + }+
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 ); + } );+
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(); + }+
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 predraw 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' ) ); + } );+
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 |
DataTables extension options and plug-ins. This namespace acts as a collection "area"
+for plug-ins that can be used to extend the default DataTables behaviour - indeed many
+of the build in methods use this method to provide their own capabilities (sorting methods
+for example).
Note that this namespace is aliased to jQuery.fn.dataTableExt so it can be readily accessed
+and modified by plug-ins.
Plug-in filtering functions - this method of filtering is complimentary to the default +type based filtering, and a lot more comprehensive as it allows you complete control +over the filtering logic. Each element in this array is a function (parameters +described below) that is called for every row in the table, and your logic decides if +it should be included in the filtered data set or not. +
// The following example shows custom filtering being applied to the fourth column (i.e. + // the aData[3] index) based on two input values from the end-user, matching the data in + // a certain range. + $.fn.dataTableExt.afnFiltering.push( + function( oSettings, aData, iDataIndex ) { + var iMin = document.getElementById('min').value * 1; + var iMax = document.getElementById('max').value * 1; + var iVersion = aData[3] == "-" ? 0 : aData[3]*1; + if ( iMin == "" && iMax == "" ) { + return true; + } + else if ( iMin == "" && iVersion < iMax ) { + return true; + } + else if ( iMin < iVersion && "" == iMax ) { + return true; + } + else if ( iMin < iVersion && iVersion < iMax ) { + return true; + } + return false; + } + );+
Plug-in sorting functions - this method of sorting is complimentary to the default type +based sorting that DataTables does automatically, allowing much greater control over the +the data that is being used to sort a column. This is useful if you want to do sorting +based on live data (for example the contents of an 'input' element) rather than just the +static string that DataTables knows of. The way these plug-ins work is that you create +an array of the values you wish to be sorted for the column in question and then return +that array. Which pre-sorting function is run here depends on the sSortDataType parameter +that is used for the column (if any). This is the corollary of ofnSearch for sort +data. +
// Updating the cached sorting information with user entered values in HTML input elements + jQuery.fn.dataTableExt.afnSortData['dom-text'] = function ( oSettings, iColumn ) + { + var aData = []; + $( 'td:eq('+iColumn+') input', oSettings.oApi._fnGetTrNodes(oSettings) ).each( function () { + aData.push( this.value ); + } ); + return aData; + }+
Feature plug-ins - This is an array of objects which describe the feature plug-ins that are +available to DataTables. These feature plug-ins are accessible through the sDom initialisation +option. As such, each feature plug-in must describe a function that is used to initialise +itself (fnInit), a character so the feature can be enabled by sDom (cFeature) and the name +of the feature (sFeature). Thus the objects attached to this method must provide: +
// How TableTools initialises itself. + $.fn.dataTableExt.aoFeatures.push( { + "fnInit": function( oSettings ) { + return new TableTools( { "oDTSettings": oSettings } ); + }, + "cFeature": "T", + "sFeature": "TableTools" + } );+
Type detection plug-in functions - DataTables utilises types to define how sorting and +filtering behave, and types can be either be defined by the developer (sType for the +column) or they can be automatically detected by the methods in this array. The functions +defined in the array are quite simple, taking a single parameter (the data to analyse) +and returning the type if it is a known type, or null otherwise. +
// Currency type detection plug-in: + jQuery.fn.dataTableExt.aTypes.push( + function ( sData ) { + var sValidChars = "0123456789.-"; + var Char; + + // Check the numeric part + for ( i=1 ; i+
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' ) ); + } );+
Index for what 'this' index API functions should use
Container for all private functions in DataTables so they can be exposed externally
Pre-processing of filtering data plug-ins - When you assign the sType for a column +(or have it automatically detected for you by DataTables or a type detection plug-in), +you will typically be using this for custom sorting, but it can also be used to provide +custom filtering by allowing you to pre-processing the data and returning the data in +the format that should be filtered upon. This is done by adding functions this object +with a parameter name which matches the sType for that target column. This is the +corollary of afnSortData for filtering data. +
$.fn.dataTableExt.ofnSearch['title-numeric'] = function ( sData ) { + return sData.replace(/\n/g," ").replace( /<.*?>/g, "" ); + }+
Storage for the various classes that DataTables uses - jQuery UI suitable
Pagination plug-in methods - The style and controls of the pagination can significantly +impact on how the end user interacts with the data in your table, and DataTables allows +the addition of pagination controls by extending this object, which can then be enabled +through the sPaginationType initialisation parameter. Each pagination type that +is added is an object (the property name of which is what sPaginationType refers +to) that has two properties, both methods that are used by DataTables to update the +control's state. +
$.fn.dataTableExt.oPagination.four_button = { + "fnInit": function ( oSettings, nPaging, fnCallbackDraw ) { + nFirst = document.createElement( 'span' ); + nPrevious = document.createElement( 'span' ); + nNext = document.createElement( 'span' ); + nLast = document.createElement( 'span' ); + + nFirst.appendChild( document.createTextNode( oSettings.oLanguage.oPaginate.sFirst ) ); + nPrevious.appendChild( document.createTextNode( oSettings.oLanguage.oPaginate.sPrevious ) ); + nNext.appendChild( document.createTextNode( oSettings.oLanguage.oPaginate.sNext ) ); + nLast.appendChild( document.createTextNode( oSettings.oLanguage.oPaginate.sLast ) ); + + nFirst.className = "paginate_button first"; + nPrevious.className = "paginate_button previous"; + nNext.className="paginate_button next"; + nLast.className = "paginate_button last"; + + nPaging.appendChild( nFirst ); + nPaging.appendChild( nPrevious ); + nPaging.appendChild( nNext ); + nPaging.appendChild( nLast ); + + $(nFirst).click( function () { + oSettings.oApi._fnPageChange( oSettings, "first" ); + fnCallbackDraw( oSettings ); + } ); + + $(nPrevious).click( function() { + oSettings.oApi._fnPageChange( oSettings, "previous" ); + fnCallbackDraw( oSettings ); + } ); + + $(nNext).click( function() { + oSettings.oApi._fnPageChange( oSettings, "next" ); + fnCallbackDraw( oSettings ); + } ); + + $(nLast).click( function() { + oSettings.oApi._fnPageChange( oSettings, "last" ); + fnCallbackDraw( oSettings ); + } ); + + $(nFirst).bind( 'selectstart', function () { return false; } ); + $(nPrevious).bind( 'selectstart', function () { return false; } ); + $(nNext).bind( 'selectstart', function () { return false; } ); + $(nLast).bind( 'selectstart', function () { return false; } ); + }, + + "fnUpdate": function ( oSettings, fnCallbackDraw ) { + if ( !oSettings.aanFeatures.p ) { + return; + } + + // Loop over each instance of the pager + var an = oSettings.aanFeatures.p; + for ( var i=0, iLen=an.length ; i+
Sorting plug-in methods - Sorting in DataTables is based on the detected type of the +data column (you can add your own type detection functions, or override automatic +detection using sType). With this specific type given to the column, DataTables will +apply the required sort from the functions in the object. Each sort type must provide +two mandatory methods, one each for ascending and descending sorting, and can optionally +provide a pre-formatting method that will help speed up sorting by allowing DataTables +to pre-format the sort data only once (rather than every time the actual sort functions +are run). The two sorting functions are typical Javascript sort methods: +
// Case-sensitive string sorting, with no pre-formatting method + $.extend( $.fn.dataTableExt.oSort, { + "string-case-asc": function(x,y) { + return ((x < y) ? -1 : ((x > y) ? 1 : 0)); + }, + "string-case-desc": function(x,y) { + return ((x < y) ? 1 : ((x > y) ? -1 : 0)); + } + } ); + ++
// Case-insensitive string sorting, with pre-formatting + $.extend( $.fn.dataTableExt.oSort, { + "string-pre": function(x) { + return x.toLowerCase(); + }, + "string-asc": function(x,y) { + return ((x < y) ? -1 : ((x > y) ? 1 : 0)); + }, + "string-desc": function(x,y) { + return ((x < y) ? 1 : ((x > y) ? -1 : 0)); + } + } );+
Storage for the various classes that DataTables uses
How should DataTables report an error. Can take the value 'alert' or 'throw'
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
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.
Template object for the column information object in DataTables. This object
+is held in the settings aoColumns array and contains all the information that
+DataTables needs about each individual column.
Note that this object is related to DataTable.defaults.columns
+but this one is the internal data store for DataTables's cache of columns.
+It should NOT be manipulated outside of DataTables. Any configuration should
+be done through the initialisation options.
A list of the columns that sorting should occur on when this column +is sorted. That this property is an array allows multi-column sorting +to be defined for a column (for example first name / last name columns +would benefit from this). The values are integers pointing to the +columns to be sorted on (typically it will be a single integer pointing +at itself, but that doesn't need to be the case).
Define the sorting directions that are applied to the column, in sequence +as the column is repeatedly sorted upon - i.e. the first value is used +as the sorting direction when the column if first sorted (clicked on). +Sort it again (click again) and it will move on to the next index. +Repeat until loop.
Flag to indicate if the column is searchable, and thus should be included +in the filtering or not.
Flag to indicate if the column is sortable or not.
When using fnRender, you have two options for what to do with the data, +and this property serves as the switch. Firstly, you can have the sorting +and filtering use the rendered value (true - default), or you can have +the sorting and filtering us the original value (false). +NOTE* It is it is advisable now to use mDataProp as a function and make +use of the 'type' that it gives, allowing (potentially) different data to +be used for sorting, filtering, display and type detection.
Flag to indicate if the column is currently visible in the table or not
Developer definable function that is called whenever a cell is created (Ajax source, +etc) or processed for input (DOM source). This can be used as a compliment to fnRender +allowing you to modify the DOM element (add background colour for example) when the +element is available (since it is not when fnRender is called).
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | nTd | element | The TD node that has been created | ||
2 | sData | * | The Data for the cell | ||
3 | oData | array | object | The data for the whole row | ||
4 | iRow | int | The row index for the aoData data store |
Function to get data from a cell in a column. You should never +access data directly through _aData internally in DataTables - always use +the method attached to this property. It allows mDataProp to function as +required. This function is automatically assigned by the column +initialisation method
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oData | array | object | The data array/object for the array + (i.e. aoData[]._aData) | ||
2 | sSpecific | string | The specific data type you want to get - + 'display', 'type' 'filter' 'sort' |
The data for the cell from the given row's data
Custom display function that will be called for the display of each cell +in this column.
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | o | object | Object with the following parameters: | ||
o.iDataRow | int | The row in aoData | |||
o.iDataColumn | int | The column in question | |||
4 | {array | o.aData The data for the row in question | |||
5 | o.oSettings | object | The settings object for this DataTables instance |
The string you which to use in the display
Function to set data for a cell in the column. You should never +set the data directly to _aData internally in DataTables - always use +this method. It allows mDataProp to function as required. This function +is automatically assigned by the column initialisation method
+ | Name | +Type | +Attributes | +Default | +Description | +
---|---|---|---|---|---|
1 | oData | array | object | The data array/object for the array + (i.e. aoData[]._aData) | ||
2 | sValue | * | Value to set |
Property to read the value for the cells in the column from the data +source array / object. If null, then the default content is used, if a +function is given then the return from the function is used.
Unique footer TH/TD element for this column (if there is one). Not used +in DataTables as such, but can be used for plug-ins to reference the +footer for each column.
Unique header TH/TD element for this column - this is what the sorting +listener is attached to (if sorting is enabled.)
The class to apply to all TD elements in the table's TBODY for the column
When DataTables calculates the column widths to assign to each column, +it finds the longest string in each column and then constructs a +temporary table and reads the widths from that. The problem with this +is that "mmm" is much wider then "iiii", but the latter is a longer +string - thus the calculation can go wrong (doing it properly and putting +it into an DOM object and measuring that is horribly(!) slow). Thus as +a "work around" we provide this option. It will append its value to the +text that is found to be the longest string for the column - i.e. padding.
Allows a default value to be given for a column's data, and will be used +whenever a null data source is encountered (this can be because mDataProp +is set to null, or because the data source itself is null).
Name for the column, allowing reference to the column by name as well as +by index (needs a lookup to work by name).
Custom sorting data type - defines which of the available plug-ins in +afnSortData the custom sorting will use - if any is defined.
Class to be applied to the header element when sorting on this column
Class to be applied to the header element when sorting on this column - +when jQuery UI theming is used.
Title of the column - what is seen in the TH element (nTh).
Column sorting and filtering type
Width of the column
Width of the column when it was first "encountered"
Template object for the way in which DataTables holds information about +each individual row. This is the object format used for the settings +aoData array.
TR element for the row
Data object from the original data source for the row. This is either +an array if using the traditional form of DataTables, or an object if +using mDataProp options. The exact type will depend on the passed in +data from the data source, or will be an array if using DOM a data +source.
Template object for the way in which DataTables holds information about +search information for the global filter and individual column filters.
Flag to indicate if the filtering should be case insensitive or not
Flag to indicate if the search term should be interpreted as a +regular expression (true) or not (false) and therefore and special +regex characters escaped.
Flag to indicate if DataTables is to use its smart filtering or not.
Applied search term
DataTables settings object - this holds all the information needed for a
+given table, including configuration, data and current application of the
+table options. DataTables does not have a single instance for each DataTable
+with the settings attached to that instance, but rather instances of the
+DataTable "class" are created on-the-fly as needed (typically by a
+$().dataTable() call) and the settings object is then applied to that
+instance.
Note that this object is related to DataTable.defaults but this
+one is the internal data store for DataTables's cache of columns. It should
+NOT be manipulated outside of DataTables. Any configuration should be done
+through the initialisation options.
Array referencing the nodes which are used for the features. The +parameters of this object match what is allowed by sDom - i.e. +
Sorting that is applied to the table. Note that the inner arrays are +used in the following manner: +
Sorting that is always applied to the table (i.e. prefixed in front of +aaSorting). +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Array of indexes which are in the current display (after filtering etc)
Array of indexes for display - no filtering
List of options that can be used for the user selectable length menu. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Store information about each column that is in use
Store data information - see DataTable.models.oRow for detailed +information.
Destroy callback functions - for plug-ins to attach themselves to the +destroy so they can clean up markup and events.
Array of callback functions for draw callback functions
Store information about the table's footer
Callback function for the footer on each draw.
Store information about the table's header
Callback functions for the header on each draw.
Callback functions for when the table has been initialised.
Information about open rows. Each object in the array has the parameters +'nTr' and 'nParent'
Callback functions for just before the table is redrawn. A return of +false will be used to cancel the draw.
Store the applied search for each column - see +DataTable.models.oSearch for the format that is used for the +filtering information for each column.
Callback functions array for every time a row is inserted (i.e. on a draw).
Array of callback functions for row created function
Functions which are called prior to sending an Ajax request so extra +parameters can easily be sent to the server
Array of callback functions for state loading. Each array element is an +object with the following parameters: +
Callbacks for operating on the settings object once the saved state has been +loaded
Callbacks for modifying the settings that have been stored for state saving +prior to using the stored values to restore the state.
Array of callback functions for state saving. Each array element is an +object with the following parameters: +
Callbacks for modifying the settings to be stored for state saving, prior to +saving state.
Search data array for regular expression searching
If restoring a table - we should restore its striping classes as well
Classes to use for the striping of a table. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Note if draw should be blocked while getting data
Indicate if when using server-side processing the loading of data +should be deferred until the second draw. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Indicate if a redraw is being done - useful for Ajax
Flag attached to the settings object so you can check in the draw +callback if filtering has been done in the draw. Deprecated in favour of +events.
Indicate if all required information has been read in
Flag to indicate if jQuery UI marking and classes should be used. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Indicate that if multiple rows are in the header and there is more than +one unique cell per column, if the top one (true) or bottom one (false) +should be used for sorting / title by DataTables. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Flag attached to the settings object so you can check in the draw +callback if sorting has been done in the draw. Deprecated in favour of +events.
Callback function for cookie creation. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Format numbers for display. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Function to get the server-side data. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
The cookie duration (for bStateSave) in seconds. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Counter for the draws that the table does. Also used as a tracker for +server-side processing
Draw index (iDraw) of the last error when parsing the returned data
tabindex attribute value that is added to DataTables control elements, allowing +keyboard navigation of the table and its controls.
The last jQuery XHR object that was used for server-side data gathering. +This can be used for working with the XHR information in one of the +callbacks
DIV container for the footer scrolling table if scrolling
DIV container for the footer scrolling table if scrolling
The TABLE node for the main table
Cache the wrapper node (contains all DataTables controlled elements)
Permanent ref to the tbody element
Permanent ref to the tfoot element - if it exists
Permanent ref to the thead element
The classes to use for the table
Initialisation object that is used for the table
The DataTables object for this table
State that was loaded from the cookie. Useful for back reference
Property from a given object from which to read the table data from. This +can be an empty string (when not server-side processing), in which case +it is assumed an an array is given directly. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Source url for AJAX data for the table. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
The cookie name prefix. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
If restoring a table - we should restore its width
Dictate the positioning of DataTables' control elements - see +DataTable.model.oInit.sDom. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Unique identifier for each instance of the DataTables object. If there +is an ID on the table node, then it takes that value, otherwise an +incrementing internal counter is used.
Which type of pagination should be used. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Send the XHR HTTP method - GET or POST (could be PUT or DELETE if +required). +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Cache the table ID for quick access
Paging display length
Paging start point - aiDisplay index
Set the display end point - aiDisplay index
Get the number of records in the current record set, after filtering
Get the number of records in the current record set, before filtering
Primary features of DataTables and their enablement state.
Flag to say if DataTables should automatically try to calculate the +optimum table and columns widths (true) or not (false). +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Delay the creation of TR and TD elements until they are actually +needed by a driven page draw. This can give a significant speed +increase for Ajax source and Javascript source data, but makes no +difference at all fro DOM and server-side processing tables. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Enable filtering on the table or not. Note that if this is disabled +then there is no filtering at all on the table, including fnFilter. +To just remove the filtering input use sDom and remove the 'f' option. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Table information element (the 'Showing x of y records' div) enable +flag. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Present a user control allowing the end user to change the page size +when pagination is enabled. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Pagination enabled or not. Note that if this is disabled then length +changing must also be disabled. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Processing indicator enable flag whenever DataTables is enacting a +user request - typically an Ajax request for server-side processing. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Server-side processing enabled flag - when enabled DataTables will +get all data from the server for every draw - there is no filtering, +sorting or paging done on the client-side. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Sorting enablement flag. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Apply a class to the columns which are being sorted to provide a +visual highlight or not. This can slow things down when enabled since +there is a lot of DOM interaction. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
State saving enablement flag. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Information callback function. See +DataTable.defaults.fnInfoCallback
This string is shown in preference to sZeroRecords when the table is +empty of data (regardless of filtering). Note that this is an optional +parameter - if it is not given, the value of sZeroRecords will be used +instead (either the default or given value).
$(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sEmptyTable": "No data available in table" + } + } ); + } );+
This string gives information to the end user about the information that +is current on display on the page. The _START_, _END_ and _TOTAL_ +variables are all dynamically replaced as the table display updates, and +can be freely moved or removed as the language requirements change.
$(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sInfo": "Got a total of _TOTAL_ entries to show (_START_ to _END_)" + } + } ); + } );+
Display information string for when the table is empty. Typically the +format of this string should match sInfo.
$(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sInfoEmpty": "No entries to show" + } + } ); + } );+
When a user filters the information in a table, this string is appended +to the information (sInfo) to give an idea of how strong the filtering +is. The variable _MAX_ is dynamically updated.
$(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sInfoFiltered": " - filtering from _MAX_ records" + } + } ); + } );+
If can be useful to append extra information to the info string at times, +and this variable does exactly that. This information will be appended to +the sInfo (sInfoEmpty and sInfoFiltered in whatever combination they are +being used) at all times.
$(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sInfoPostFix": "All records shown are derived from real information." + } + } ); + } );+
DataTables has a build in number formatter (fnFormatNumber) which is used +to format large numbers that are used in the table information. By +default a comma is used, but this can be trivially changed to any +character you wish with this parameter.
$(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sInfoThousands": "'" + } + } ); + } );+
Detail the action that will be taken when the drop down menu for the +pagination length option is changed. The '_MENU_' variable is replaced +with a default select list of 10, 25, 50 and 100, and can be replaced +with a custom select box if required.
// Language change only + $(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sLengthMenu": "Display _MENU_ records" + } + } ); + } ); + ++
// Language and options change + $(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sLengthMenu": 'Display records' + } + } ); + } );+
When using Ajax sourced data and during the first draw when DataTables is +gathering the data, this message is shown in an empty row in the table to +indicate to the end user the the data is being loaded. Note that this +parameter is not used when loading data by server-side processing, just +Ajax sourced data with client-side processing.
$(document).ready( function() { + $('#example').dataTable( { + "oLanguage": { + "sLoadingRecords": "Please wait - loading..." + } + } ); + } );+
Text which is displayed when the table is processing a user action +(usually a sort command or similar).
$(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sProcessing": "DataTables is currently busy" + } + } ); + } );+
Details the actions that will be taken when the user types into the +filtering input text box. The variable "_INPUT_", if used in the string, +is replaced with the HTML text box for the filtering input allowing +control over where it appears in the string. If "_INPUT_" is not given +then the input box is appended to the string automatically.
// Input text box will be appended at the end automatically + $(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sSearch": "Filter records:" + } + } ); + } ); + ++
// Specify where the filter should appear + $(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sSearch": "Apply filter _INPUT_ to table" + } + } ); + } );+
All of the language information can be stored in a file on the +server-side, which DataTables will look up if this parameter is passed. +It must store the URL of the language file, which is in a JSON format, +and the object has the same properties as the oLanguage object in the +initialiser object (i.e. the above parameters). Please refer to one of +the example language files to see how this works in action.
$(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sUrl": "http://www.sprymedia.co.uk/dataTables/lang.txt" + } + } ); + } );+
Text shown inside the table records when the is no information to be +displayed after filtering. sEmptyTable is shown when there is simply no +information in the table at all (regardless of filtering).
$(document).ready(function() { + $('#example').dataTable( { + "oLanguage": { + "sZeroRecords": "No records to display" + } + } ); + } );+
Store the applied global search information in case we want to force a +research or compare the old search to a new one. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Flag to indicate if the filtering should be case insensitive or not
Flag to indicate if the search term should be interpreted as a +regular expression (true) or not (false) and therefore and special +regex characters escaped.
Flag to indicate if DataTables is to use its smart filtering or not.
Applied search term
Scrolling settings for a table.
Indicate if DataTables should be allowed to set the padding / margin +etc for the scrolling header elements or not. Typically you will want +this. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
When the table is shorter in height than sScrollY, collapse the +table container down to the height of the table (when true). +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Infinite scrolling enablement flag. Now deprecated in favour of +using the Scroller plug-in. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Width of the scrollbar for the web-browser's platform. Calculated +during table initialisation.
Space (in pixels) between the bottom of the scrolling container and +the bottom of the scrolling viewport before the next page is loaded +when using infinite scrolling. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Viewport width for horizontal scrolling. Horizontal scrolling is +disabled if an empty string. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Width to expand the table to when using x-scrolling. Typically you +should not need to use this. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
Viewport height for vertical scrolling. Vertical scrolling is disabled +if an empty string. +Note that this parameter will be set by the initialisation routine. To +set a default use DataTable.defaults.
t |
You may specify a function for each column to render the available data in a specific manner which will be called when the table is drawn. In this example I've appended the rendering engine version to the rendering engine name in the first column, and hidden the version column.
+ +Rendering engine | +Browser | +Platform(s) | +Engine version | +CSS grade | +
---|---|---|---|---|
Trident | +Internet Explorer 4.0 | +Win 95+ | +4 | +X | +
Trident | +Internet Explorer 5.0 | +Win 95+ | +5 | +C | +
Trident | +Internet Explorer 5.5 | +Win 95+ | +5.5 | +A | +
Trident | +Internet Explorer 6 | +Win 98+ | +6 | +A | +
Trident | +Internet Explorer 7 | +Win XP SP2+ | +7 | +A | +
Trident | +AOL browser (AOL desktop) | +Win XP | +6 | +A | +
Gecko | +Firefox 1.0 | +Win 98+ / OSX.2+ | +1.7 | +A | +
Gecko | +Firefox 1.5 | +Win 98+ / OSX.2+ | +1.8 | +A | +
Gecko | +Firefox 2.0 | +Win 98+ / OSX.2+ | +1.8 | +A | +
Gecko | +Firefox 3.0 | +Win 2k+ / OSX.3+ | +1.9 | +A | +
Gecko | +Camino 1.0 | +OSX.2+ | +1.8 | +A | +
Gecko | +Camino 1.5 | +OSX.3+ | +1.8 | +A | +
Gecko | +Netscape 7.2 | +Win 95+ / Mac OS 8.6-9.2 | +1.7 | +A | +
Gecko | +Netscape Browser 8 | +Win 98SE+ | +1.7 | +A | +
Gecko | +Netscape Navigator 9 | +Win 98+ / OSX.2+ | +1.8 | +A | +
Gecko | +Mozilla 1.0 | +Win 95+ / OSX.1+ | +1 | +A | +
Gecko | +Mozilla 1.1 | +Win 95+ / OSX.1+ | +1.1 | +A | +
Gecko | +Mozilla 1.2 | +Win 95+ / OSX.1+ | +1.2 | +A | +
Gecko | +Mozilla 1.3 | +Win 95+ / OSX.1+ | +1.3 | +A | +
Gecko | +Mozilla 1.4 | +Win 95+ / OSX.1+ | +1.4 | +A | +
Gecko | +Mozilla 1.5 | +Win 95+ / OSX.1+ | +1.5 | +A | +
Gecko | +Mozilla 1.6 | +Win 95+ / OSX.1+ | +1.6 | +A | +
Gecko | +Mozilla 1.7 | +Win 98+ / OSX.1+ | +1.7 | +A | +
Gecko | +Mozilla 1.8 | +Win 98+ / OSX.1+ | +1.8 | +A | +
Gecko | +Seamonkey 1.1 | +Win 98+ / OSX.2+ | +1.8 | +A | +
Gecko | +Epiphany 2.20 | +Gnome | +1.8 | +A | +
Webkit | +Safari 1.2 | +OSX.3 | +125.5 | +A | +
Webkit | +Safari 1.3 | +OSX.3 | +312.8 | +A | +
Webkit | +Safari 2.0 | +OSX.4+ | +419.3 | +A | +
Webkit | +Safari 3.0 | +OSX.4+ | +522.1 | +A | +
Webkit | +OmniWeb 5.5 | +OSX.4+ | +420 | +A | +
Webkit | +iPod Touch / iPhone | +iPod | +420.1 | +A | +
Webkit | +S60 | +S60 | +413 | +A | +
Presto | +Opera 7.0 | +Win 95+ / OSX.1+ | +- | +A | +
Presto | +Opera 7.5 | +Win 95+ / OSX.2+ | +- | +A | +
Presto | +Opera 8.0 | +Win 95+ / OSX.2+ | +- | +A | +
Presto | +Opera 8.5 | +Win 95+ / OSX.2+ | +- | +A | +
Presto | +Opera 9.0 | +Win 95+ / OSX.3+ | +- | +A | +
Presto | +Opera 9.2 | +Win 88+ / OSX.3+ | +- | +A | +
Presto | +Opera 9.5 | +Win 88+ / OSX.3+ | +- | +A | +
Presto | +Opera for Wii | +Wii | +- | +A | +
Presto | +Nokia N800 | +N800 | +- | +A | +
Presto | +Nintendo DS browser | +Nintendo DS | +8.5 | +C/A1 | +
KHTML | +Konqureror 3.1 | +KDE 3.1 | +3.1 | +C | +
KHTML | +Konqureror 3.3 | +KDE 3.3 | +3.3 | +A | +
KHTML | +Konqureror 3.5 | +KDE 3.5 | +3.5 | +A | +
Tasman | +Internet Explorer 4.5 | +Mac OS 8-9 | +- | +X | +
Tasman | +Internet Explorer 5.1 | +Mac OS 7.6-9 | +1 | +C | +
Tasman | +Internet Explorer 5.2 | +Mac OS 8-X | +1 | +C | +
Misc | +NetFront 3.1 | +Embedded devices | +- | +C | +
Misc | +NetFront 3.4 | +Embedded devices | +- | +A | +
Misc | +Dillo 0.8 | +Embedded devices | +- | +X | +
Misc | +Links | +Text only | +- | +X | +
Misc | +Lynx | +Text only | +- | +X | +
Misc | +IE Mobile | +Windows Mobile 6 | +- | +C | +
Misc | +PSP browser | +PSP | +- | +C | +
Other browsers | +All others | +- | +- | +U | +
Rendering engine | +Browser | +Platform(s) | +Engine version | +CSS grade | +
$(document).ready(function() { + $('#example').dataTable( { + "aoColumnDefs": [ + { + "fnRender": function ( oObj, sVal ) { + return sVal +' '+ oObj.aData[3]; + }, + "aTargets": [ 0 ] + }, + { "bVisible": false, "aTargets": [ 3 ] }, + { "sClass": "center", "aTargets": [ 4 ] } + ] + } ); +} );+ + + + +