API
This extension has now been retired and has been replaced by the Buttons and Select extensions. The documentation is retained for legacy reference only. New projects should use Buttons and Select in preference to TableTools.
When working with TableTools, there will be times when you want to interaction with it more than just setting up buttons and actions for them. You might want to modify the data set used for file exporting, or work with the row selection options that TableTools provides. For this you should use the API.
There are two types of API methods that TableTools provides:
- Instance - provided by a given instance of TableTools
- Static - provided by the static TableTools object itself
Typically you will use the static methods to get the instance of TableTools which applies to a given DataTable, and then perform actions using the instance methods. The instance can also be obtained by initialising TableTools with the keyword new
and manually insetting the created node, rather than having DataTables do it automatically.
Instance methods
fnCalcColRatios
Show details
|
Get a string (comma separated) of column proportions that are used in the table display. Typically the only use for this is to pass this information to the PDF generator so it can size columns as needed. |
Default: |
|
Input parameters: |
- Object - button configuration
|
Return parameter: |
String - column proportions in a comma separated list |
Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "pdf",
"fnClick": function( nButton, oConfig, flash ) {
this.fnSetText( flash,
"title:My document\n"+
"colWidth:"+ this.fnCalcColRatios(oConfig) +"\n"+
"--/TableToolsOpts--\n" +
this.fnGetTableData(oConfig)
);
}
}
]
}
} );
} );
|
fnDeselect
Show details
|
Deselect an individual row |
Default: |
|
Input parameters: |
- node - The TR element in the table to deselect
|
Return parameter: |
void |
Code example: |
$(document).ready( function () {
$('#example1').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"sRowSelect": "single"
}
} );
var oTT = TableTools.fnGetInstance( 'example1' );
var nRow = $('#example tbody tr')[0];
// Select the first row in the table
oTT.fnSelect( nRow );
// Now deselect the row
oTT.fnDeselect( nRow );
} );
|
fnGetSelected
Show details
|
Get an array of the TR nodes which have been selected by the end user. |
Default: |
|
Input parameters: |
Optional: {boolean} filtered - Get rows from the filtered table (true) only, or all rows (false, default). |
Return parameter: |
Array - TR nodes which have been selected by the end user |
Code example: |
$(document).ready( function () {
$('#example1').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"sRowSelect": "multi"
}
} );
var oTT = TableTools.fnGetInstance( 'example1' );
var aSelectedTrs = oTT.fnGetSelected();
/* perform operations on TR elements in the aSelectedTrs array */
/* ... */
} );
|
fnGetSelectedData
Show details
|
Get the data source objects/arrays from DataTables for the selected rows (same as fnGetSelected followed by fnGetData on each row from the table). |
Default: |
|
Input parameters: |
void |
Return parameter: |
Array - Data from the TR nodes which are currently selected |
Code example: |
$(document).ready( function () {
$('#example1').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"sRowSelect": "single"
}
} );
var oTT = TableTools.fnGetInstance( 'example1' );
var aData = oTT.fnGetSelectedData();
/* perform operations on array elements in the aData array ... */
} );
|
fnGetSelectedIndexes
Show details
|
2.2.2 Get the indexes for the rows that have been selected in the DataTable. |
Default: |
|
Input parameters: |
Optional: {boolean} filtered - Get rows from the filtered table (true) only, or all rows (false, default). |
Return parameter: |
Array - List of row indexes |
Code example: |
$(document).ready( function () {
$('#example1').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"sRowSelect": "single"
}
} );
var tt = TableTools.fnGetInstance( 'example1' );
var indexes = tt.fnGetSelectedIndexes();
/* perform operations on array elements in the indexes array ... */
} );
|
fnGetTableData
Show details
|
Get the data from the table formatted as a string based on the parameters "mColumns", "sFieldBoundary" and "sFieldSeperator". This can then be sent to Flash for file saving, to the server via Ajax or any other manipulation you want to perform. |
Default: |
|
Input parameters: |
- Object - Button configuration (specifically interested in mColumns, sFieldBoundary and sFieldSeperator
|
Return parameter: |
String - data from the table |
Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "copy",
"fnClick": function ( nButton, oConfig, flash ) {
this.fnSetText( flash, this.fnGetTableData(oConfig) );
}
}
]
}
} );
} );
|
fnGetTitle
Show details
|
Get the page title. |
Default: |
|
Input parameters: |
- Object - button configuration (specifically interested in the sTitle parameter).
|
Return parameter: |
String - page title |
Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "copy",
"fnClick": function ( nButton, oConfig, flash ) {
/* Copy to clipboard with the page title */
this.fnSetText( flash, this.fnGetTitle( oConfig ) +"\n\n"+
this.fnGetTableData(oConfig) );
}
}
]
}
} );
} );
|
fnInfo
Show details
|
Show an information element to the end user (as used by the copy to clipboard and print view options to tell the user what is going on). |
Default: |
|
Input parameters: |
- string - HTML string to show
- int - duration that the information display will be shown for (mS)
|
Return parameter: |
|
Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "text",
"fnClick": function( nButton, oConfig ) {
this.fnInfo( "My information button!" );
}
}
]
}
} );
} );
|
fnIsSelected
Show details
|
Check with TableTools if a given TR row has been selected by the user or not. |
Default: |
|
Input parameters: |
- Node - TR node to check
|
Return parameter: |
Boolean - true if selected, false if not. |
Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip'
} );
var oTT = TableTools.fnGetInstance( 'example1' );
if ( oTT.fnIsSelected( $('#example tbody tr:eq(0)')[0] ) ) {
alert( 'First row is selected' );
} else {
alert( 'First row is not selected' );
}
} );
|
fnPrint
Show details
|
Programmatically enable or disable the print view. |
Default: |
|
Input parameters: |
- boolean - Show the print view if true or not given. If false, then terminate the print view and return to normal.
- object - Configuration for the print view (parameters are
bShowAll - show all rows in the table if true, sInfo , information message displayed as an overlay, and sMessage , HTML string to show that the
top of the document - will be included in the printed document.
|
Return parameter: |
|
Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "text",
"fnClick": function( nButton, oConfig ) {
this.fnPrint( true, oConfig );
}
}
]
}
} );
} );
|
fnResizeButtons
Show details
|
Recalculate the height and width to apply to the Flash movie used for copy / save actions. This is useful for when TableTools has been initialised in a hidden element (for example a tab) where the height and width can't be initially calculated. |
Default: |
|
Input parameters: |
Void |
Return parameter: |
Void |
Code example: |
$(document).ready(function() {
$("#tabs").tabs( {
"active": function(event, ui) {
var jqTable = $('table.display', ui.panel);
if ( jqTable.length > 0 ) {
var oTableTools = TableTools.fnGetInstance( jqTable[0] );
if ( oTableTools != null && oTableTools.fnResizeRequired() )
{
/* A resize of TableTools' buttons and DataTables' columns is only required on the
* first visible draw of the table
*/
jqTable.dataTable().fnAdjustColumnSizing();
oTableTools.fnResizeButtons();
}
}
}
} );
$('#example1').dataTable( {
"bJQueryUI": true,
"sPaginationType": "full_numbers",
"sDom": '<"H"Tfr>t<"F"ip>'
} );
$('#example2').dataTable( {
"bJQueryUI": true,
"sPaginationType": "full_numbers",
"sDom": '<"H"Tfr>t<"F"ip>'
} );
} );
|
fnResizeRequired
Show details
|
Find out if a resize of the buttons (fnResizeButtons) is required or not. This can happen when TableTools is initialised in a hidden element (for example a tab). |
Default: |
|
Input parameters: |
Void |
Return parameter: |
Boolean - true is a resize is required, false otherwise |
Code example: |
$(document).ready(function() {
$("#tabs").tabs( {
"show": function(event, ui) {
var jqTable = $('table.display', ui.panel);
if ( jqTable.length > 0 ) {
var oTableTools = TableTools.fnGetInstance( jqTable[0] );
if ( oTableTools != null && oTableTools.fnResizeRequired() )
{
/* A resize of TableTools' buttons and DataTables' columns is only required on the
* first visible draw of the table
*/
jqTable.dataTable().fnAdjustColumnSizing();
oTableTools.fnResizeButtons();
}
}
}
} );
$('#example1').dataTable( {
"bJQueryUI": true,
"sPaginationType": "full_numbers",
"sDom": '<"H"Tfr>t<"F"ip>'
} );
$('#example2').dataTable( {
"bJQueryUI": true,
"sPaginationType": "full_numbers",
"sDom": '<"H"Tfr>t<"F"ip>'
} );
} );
|
fnSelect
Show details
|
Select an individual row |
Default: |
|
Input parameters: |
- node - The TR element in the table to select
|
Return parameter: |
void |
Code example: |
$(document).ready( function () {
$('#example1').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"sRowSelect": "single"
}
} );
// Select the first row in the table automatically
var oTT = TableTools.fnGetInstance( 'example1' );
oTT.fnSelect( $('#example tbody tr')[0] );
} );
|
fnSelectAll
Show details
|
Select all rows in the table. |
Default: |
|
Input parameters: |
- boolean - Select only filtered rows (true). Optional - default false.
|
Return parameter: |
void |
Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip'
} );
var oTT = TableTools.fnGetInstance( 'example1' );
oTT.fnSelectAll();
} );
|
fnSelectNone
Show details
|
Deselect all rows in the table. |
Default: |
|
Input parameters: |
- boolean - Deselect only filtered rows (true). Optional - default false.
|
Return parameter: |
void |
Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip'
} );
var oTT = TableTools.fnGetInstance( 'example1' );
oTT.fnSelectNone();
} );
|
fnSetText
Show details
|
Set the text for a Flash movie clip. This method must be used to set the text used when using a Flash button for copy to clipboard or file saving. |
Default: |
|
Input parameters: |
- Object - Zeroclipboard instance used for the Flash movie
- String - String to set the movie clip to use
|
Return parameter: |
void |
Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "copy",
"sButtonText": "Static text!",
"fnClick": function ( nButton, oConfig, flash ) {
this.fnSetText( flash, "Hello from TableTools!" );
}
}
]
}
} );
} );
|
Static methods
fnGetInstance
Show details
|
This method can be used to get the master instance of TableTools for any given table. |
Default: |
|
Input parameters: |
- String or Node - If a string then it should be the ID of the table in question, otherwise it should be the table node in question.
|
Return parameter: |
TableTools instance or null if not found |
Code example: |
$(document).ready( function () {
$('#example1').dataTable( {
"sDom": 'T<"clear">lfrtip'
} );
$('#example2').dataTable( {
"sDom": 'T<"clear">lfrtip'
} );
var TableTools1 = TableTools.fnGetInstance( 'example1' );
/* perform some action on the "example1" table's TableTools instance... */
} );
|
fnGetMasters
Show details
|
Get an array of all TableTool master instances on the page. TableTools can have multiple instances for each DataTable, but can have only one 'master' per table, and it is with this one that API actions should typically be used with. |
Default: |
|
Input parameters: |
void |
Return parameter: |
void |
Code example: |
$(document).ready( function () {
$('#example1').dataTable( {
"sDom": 'T<"clear">lfrtip'
} );
$('#example2').dataTable( {
"sDom": 'T<"clear">lfrtip'
} );
var aoTableTools = TableTools.fnGetMasters();
/* perform some action on all TableTools instances... */
} );
|