Button options
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.
Frequently when using TableTools, you will wish to modify the behaviour of the predefined buttons to match the interaction needed for your web-site or web-application. This is achieved by making use of the options for each of the button types that TableTools presents. There are a number of button types: flash, print, text, ajax and collection, built into TableTools, and each have their own properties as described below.
- Common options
- Ajax options
- Collection options
- Flash options
- Print options
- Text options
The basic principle of modifying the button properties in TableTools is that you define a custom button, based on one of the predefined types and extend it (overwriting the default properties as needed). In the example below, we create a new button be extending the 'text' predefined button and setting its text, but leaving all other properties as they are.
Common options (apply to all button types)
fnCellRender
Show details
|
Used to modify the data that has been read from the table through the fnGetTableData API method (used for exporting data). This allows pre-processing of the data before exporting it - for example stripping certain parts of the HTML or postfixing
other data. |
| Default: |
|
| Input parameters: |
- * - The value from the cell's data
- int - The column number being read
- node - The TR element for the row
- int - The internal DataTables cache index for the row (based on fnGetPosition)
|
| Return parameter: |
Data to export |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "text",
"fnCellRender": function ( sValue, iColumn, nTr, iDataIndex ) {
// Append the text 'TableTools' to column 5
if ( iColumn === 5 ) {
return sValue +" TableTools";
}
return sValue;
}
}
]
}
} );
} );
|
fnClick
Show details
|
Callback function for when a button has been clicked on. |
| Default: |
|
| Input parameters: |
- node - The button element which has activated the callback
- object - the button definition object, with all initialisation properties for the button.
- object - Zeroclipboard instance for controlling the Flash button. Note that this is given as null for non-flash based buttons.
|
| Return parameter: |
void |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "text",
"fnClick": function ( nButton, oConfig, oFlash ) {
alert( 'Mouse click' );
}
}
]
}
} );
} );
|
fnComplete
Show details
|
This callback function is activated when whatever action the button needs to take has been completed. This is particularly useful for Flash based buttons since it is activated after whatever action Flash has taken (such as saving a file). |
| Default: |
|
| Input parameters: |
- node - The button element which has activated the callback
- object - the button definition object, with all initialisation properties for the button.
- object - Zeroclipboard instance for controlling the Flash button. Note that this is given as null for non-flash based buttons.
- string - the text returned from the Flash movie clip.
|
| Return parameter: |
void |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "text",
"fnComplete": function ( nButton, oConfig, oFlash, sFlash ) {
alert( 'Button action complete' );
}
}
]
}
} );
} );
|
fnInit
Show details
|
Callback function which is called when the button has been created an initialised by the TableTools code. This allows modification of the button before it is inserted into the DOM (adding a class for example). |
| Default: |
|
| Input parameters: |
- node - The button element which has activated the callback
- object - the button definition object, with all initialisation properties for the button.
|
| Return parameter: |
void |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "text",
"fnInit": function ( nButton, oConfig ) {
alert( 'Button initialised' );
}
}
]
}
} );
} );
|
fnMouseout
Show details
|
Callback function for when the mouse leaves a button. |
| Default: |
|
| Input parameters: |
- node - The button element which has activated the callback
- object - the button definition object, with all initialisation properties for the button.
- object - Zeroclipboard instance for controlling the Flash button. Note that this is given as null for non-flash based buttons.
|
| Return parameter: |
void |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "text",
"fnMouseout": function ( nButton, oConfig, oFlash ) {
alert( 'Mouse out' );
}
}
]
}
} );
} );
|
fnMouseover
Show details
|
Callback function for when the mouse if hovered over the button. |
| Default: |
|
| Input parameters: |
- node - The button element which has activated the callback
- object - the button definition object, with all initialisation properties for the button.
- object - Zeroclipboard instance for controlling the Flash button. Note that this is given as null for non-flash based buttons.
|
| Return parameter: |
void |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "text",
"fnMouseover": function ( nButton, oConfig, oFlash ) {
alert( 'Mosue over' );
}
}
]
}
} );
} );
|
fnSelect
Show details
|
Function which is called when a row is selected in the table. This allows operations to be performed on the button (such as adding and removing classes) when the table row selection changes state. |
| Default: |
|
| Input parameters: |
- node - The button element which has activated the callback
- object - the button definition object, with all initialisation properties for the button.
- node - the TR row node that was clicked upon.
|
| Return parameter: |
void |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "text",
"fnSelect": function ( nButton, oConfig, nRow ) {
alert( 'Row selected' );
}
}
]
}
} );
} );
|
oSelectorOpts
Show details
|
Control the data to be used from the source DataTable. DataTables has the ability to select which rows to use, and the order they are to be used in, through its $ API method. This option provides that ability for TableTools export buttons as well, so you can have only the current data exported (for example). |
| Default: |
|
| Type: |
object |
| Code example: |
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "copy",
"sButtonText": "Copy to clipboard",
"oSelectorOpts": {
page: 'current'
}
}
]
}
} );
|
sAction
Show details
|
The action tells TableTools what kind of button the newly created button should be treated as - the actions which can be performed with the button will depend on this setting. It can be one of: "flash_save", "flash_copy", "flash_pdf", "print",
"text" or "collection". |
| Default: |
|
| Type: |
String |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "xls",
"sAction": "flash_save"
}
]
}
} );
} );
|
sButtonClass
Show details
|
Set the class of a button when it is in the non-mouseover state. |
| Default: |
|
| Type: |
String |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "csv",
"sButtonClass": "my_button_class"
}
]
}
} );
} );
|
sButtonText
Show details
|
Set the text of a button to a custom string. |
| Default: |
|
| Type: |
String |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "csv",
"sButtonText": "Save a CSV file!"
}
]
}
} );
} );
|
sExtends
Show details
|
It is often useful to make use of the predefined buttons and extend them as needed. This property should match of one the predefined buttons to provide exactly that. |
| Default: |
|
| Type: |
String |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "text",
"sButtonText": "Hello world"
}
]
}
} );
} );
|
Ajax button options
bFooter
Show details
|
Include the footer in the exported data, or not. |
| Default: |
true |
| Type: |
Boolean |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "ajax",
"bFooter": false
}
]
}
} );
} );
|
bHeader
Show details
|
Include the header in the exported data, or not. |
| Default: |
true |
| Type: |
Boolean |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "ajax",
"bFooter": false
}
]
}
} );
} );
|
fnAjaxComplete
Show details
|
This is the method which is called when the Ajax load is completed. It is defined in the fnClick function for the Ajax button. |
| Default: |
|
| Input parameters: |
As per $.ajax() |
| Return parameter: |
void |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "ajax",
"fnAjaxComplete": function ( XMLHttpRequest, textStatus ) {
alert( 'Ajax complete' );
}
}
]
}
} );
} );
|
mColumns
Show details
|
This parameters defines which columns should be used as the data source for the export. The parameter can be a string with a value of 'all', 'visible' or 'hidden' - or an array of integers with the column indexes to be exported. Additional, as of TableTools 2.2.3 it can also be a function which returns an array of column indexes to be included in the output. The function takes a single argument, the DataTables settings object which can be used to obtain an API instance. |
| Default: |
all |
| Type: |
Mixed (String, Array of Integers or FUnction) |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "ajax",
"sButtonText": "Special columns",
"mColumns": [ 0, 1, 4 ]
},
{
"sExtends": "ajax",
"sButtonText": "Visible columns",
"mColumns": "visible"
}
]
}
} );
} );
$(document).ready(function() {
$('#example').DataTable( {
dom: 'T<"clear">lfrtip',
tableTools: {
aButtons: [ {
sExtends: 'copy',
mColumns: function ( ctx ) {
var api = new $.fn.dataTable.Api( ctx );
return api.columns( '.selected' ).indexes().toArray();
}
} ]
}
} );
} );
|
sAjaxUrl
Show details
|
This parameter is used by the Ajax button's default 'fnClick' function to define where the Ajax request should be sent. |
| Default: |
/xhr.php |
| Type: |
String |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "ajax",
"sAjaxUrl": "remote.php"
}
]
}
} );
} );
|
sFieldBoundary
Show details
|
Set the boundary character for CSV fields. Typically you will want this to be a single quote, but it can be useful to change. |
| Default: |
' |
| Type: |
String |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "ajax",
"sFieldBoundary": '"'
}
]
}
} );
} );
|
sFieldSeperator
Show details
|
Defines the character to use as a field separator for CSV fields. Typically this is a comma... |
| Default: |
, |
| Type: |
String |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "ajax",
"sFieldSeperator": "-"
}
]
}
} );
} );
|
Collection button options
aButtons
Show details
|
A collection in TableTools is a special button which when activated will show a drop down list of 'sub-buttons'. The sub-buttons are defined by the aButtons array, and take exactly the same parameter options as the top level buttons. |
| Default: |
|
| Type: |
Array |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
"copy",
"print",
{
"sExtends": "collection",
"sButtonText": "Save",
"aButtons": [ "csv", "xls", "pdf" ]
}
]
}
} );
} );
|
Flash button options
bBomInc
Show details
|
Defines if the Byte Order Mark (BOM) should be included at the start of the file. |
| Default: |
|
| Type: |
Boolean |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "csv",
"bBomInc": true
}
]
}
} );
} );
|
bFooter
Show details
|
Include the footer in the exported data, or not. |
| Default: |
|
| Type: |
Boolean |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "csv",
"bFooter": false
}
]
}
} );
} );
|
bHeader
Show details
|
Include the table header or not in the export. |
| Default: |
|
| Type: |
Boolean |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "csv",
"bHeader": false
}
]
}
} );
} );
|
bSelectedOnly
Show details
|
When this option is set to true, the data gathered from the table will be from only the rows which are selected by the end user (using the sRowSelect option) - all other data will be discarded (i.e. not used in the save / copy). If no rows are
selected, then all data is used. |
| Default: |
false |
| Type: |
Boolean |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"sRowSelect": "multi",
"aButtons": [
{
"sExtends": "csv",
"bSelectedOnly": true
}
]
}
} );
} );
|
mColumns
Show details
|
This parameters defines which columns should be used as the data source for the export. The parameter can either be a string with a value of 'all', 'visible', 'hidden' or 'sortable' - or an array of integers with the column indexes to be exported. |
| Default: |
|
| Type: |
Mixed (String or Array of Integers) |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "csv",
"sButtonText": "Special columns",
"mColumns": [ 0, 1, 4 ]
},
{
"sExtends": "csv",
"sButtonText": "Visible columns",
"mColumns": "visible"
}
]
}
} );
} );
|
sCharSet
Show details
|
This parameter defined what character set the saved file will use. It may take the value of either "utf8" or "utf16le". Typically you will want to use "utf8", but "utf16le" is useful for saving files which are to be read by Excel. |
| Default: |
|
| Type: |
String |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "csv",
"sCharSet": "utf16le"
}
]
}
} );
} );
|
sFieldBoundary
Show details
|
Set the boundary character for CSV fields. Typically you will want this to be a single quote, but it can be useful to change. |
| Default: |
|
| Type: |
String |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "csv",
"sFieldBoundary": '"'
}
]
}
} );
} );
|
sFieldSeperator
Show details
|
Defines the character to use as a field separator for CSV fields. Typically this is a comma (hence the CSV name!). |
| Default: |
|
| Type: |
String |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "csv",
"sFieldSeperator": "-"
}
]
}
} );
} );
|
sFileName
Show details
|
This parameter defines the name of the file that is to be saved. The special character "*" will be replaced by the HTML document's "TITLE" tag if it is present. Otherwise you can use this parameter to define the file name to be used. |
| Default: |
|
| Type: |
String |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "csv",
"sFileName": "TableTools - *.csv"
}
]
}
} );
} );
|
sNewLine
Show details
|
Defines the character(s) to be used to denote a newline in the exported data. The special string "auto" can be used to auto detect what newline character should be used (i.e. \r\n on Windows, \n on everything else). |
| Default: |
|
| Type: |
String |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "csv",
"sNewLine": "auto"
}
]
}
} );
} );
|
sPdfMessage
Show details
|
A free text input which can be used to add a custom description / summary to a PDF export. |
| Default: |
Empty string
|
| Type: |
String |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
"copy",
"csv",
"xls",
{
"sExtends": "pdf",
"sPdfMessage": "Your custom message would go here."
}
"print"
]
}
} );
} );
|
sPdfOrientation
Show details
|
Set the paper orientation for PDF output. |
| Default: |
portrait |
| Type: |
String ('landscape' or 'portrait') |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
"copy",
"csv",
"xls",
{
"sExtends": "pdf",
"sPdfOrientation": "landscape"
}
"print"
]
}
} );
} );
|
sPdfSize
Show details
|
Set the size of the paper used in the PDF saved file. |
| Default: |
A4 |
| Type: |
String - 'A[3-4]', 'letter', 'legal' or 'tabloid' |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
"copy",
"csv",
"xls",
{
"sExtends": "pdf",
"sPdfSize": "letter"
}
"print"
]
}
} );
} );
|
sTitle
Show details
|
Set the saved document's title / file name. In the case of a PDF file, this title is displayed in the document at the top (above the sMessage text, if given). If given as an empty string, TableTools will use the TITLE tag from the HTML document. |
| Default: |
|
| Type: |
String |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
"copy",
"csv",
"xls",
{
"sExtends": "pdf",
"sTitle": "My title"
}
"print"
]
}
} );
} );
|
sToolTip
Show details
|
Define the 'title' attribute for the button, such that the browser will display it as part of the standard tooltip display (typically a little yellow hover box). |
| Default: |
|
| Type: |
String |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "csv",
"sToolTip": "Save as CSV"
}
]
}
} );
} );
|
Print button options
bShowAll
Show details
|
This parameter can be used to cause TableTools to show either the current page only (false), or all records in the table (true). |
| Default: |
true |
| Type: |
Boolean |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "print",
"bShowAll": false
}
]
}
} );
} );
|
sInfo
Show details
|
TableTools will show an information message to the end user when the print display is started telling them what is happening and how to escape out of it. This message can be changed with this parameter. |
| Default: |
Print view
Please use your browser's print function to print this table. Press escape when finished. |
| Type: |
String |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "print",
"sInfo": "Please press escape when done"
}
]
}
} );
} );
|
sMessage
Show details
|
You can have TableTools put an information message at the top of the print display (for example a copyright message or title) using this parameter. |
| Default: |
|
| Type: |
String |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "print",
"sMessage": "Generated by DataTables"
}
]
}
} );
} );
|
Text button options
bFooter
Show details
|
Include the footer in the exported data, or not. |
| Default: |
true |
| Type: |
Boolean |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "text",
"bFooter": false
}
]
}
} );
} );
|
bHeader
Show details
|
Include the header in the exported data, or not. |
| Default: |
true |
| Type: |
Boolean |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "text",
"bHeader": false
}
]
}
} );
} );
|
mColumns
Show details
|
This parameters defines which columns should be used as the data source for the export. The parameter can either be a string with a value of 'all', 'visible' or 'hidden' - or an array of integers with the column indexes to be exported. |
| Default: |
all |
| Type: |
Mixed (String or Array of Integers) |
| Code example: |
$(document).ready( function () {
$('#example').dataTable( {
"sDom": 'T<"clear">lfrtip',
"oTableTools": {
"aButtons": [
{
"sExtends": "csv",
"sButtonText": "Special columns",
"mColumns": [ 0, 1, 4 ]
},
{
"sExtends": "csv",
"sButtonText": "Visible columns",
"mColumns": "visible"
}
]
}
} );
} );
|