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:
  1. 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:
  1. 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:
  1. 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:
  1. 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:
  1. string - HTML string to show
  2. 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:
  1. 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:
  1. boolean - Show the print view if true or not given. If false, then terminate the print view and return to normal.
  2. 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:
  1. 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:
  1. 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:
  1. 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:
  1. Object - Zeroclipboard instance used for the Flash movie
  2. 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:
  1. 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... */
} );