DataTables logo DataTables

via Ad Packs

Button options

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.

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 it's text, but leaving all other properties as they are.

$(document).ready( function () {
	$('#example').dataTable( {
		"sDom": 'T<"clear">lfrtip',
		"oTableTools": {
			"aButtons": [
				{
					"sExtends":    "text",
					"sButtonText": "Hello world"
				}
			]
		}
	} );
} );

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:
  1. * - The value from the cell's data
  2. int - The column number being read
Return parameter: Data to export
Code example: 
$(document).ready( function () {
	$('#example').dataTable( {
		"sDom": 'T<"clear">lfrtip',
		"oTableTools": {
			"aButtons": [
				{
					"sExtends":    "text",
					"fnCellRender": function ( sValue, iColumn ) {
						// 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:
  1. node - The button element which has activated the callback
  2. object - the button definition object, with all initialisation properties for the button.
  3. 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:
  1. node - The button element which has activated the callback
  2. object - the button definition object, with all initialisation properties for the button.
  3. object - Zeroclipboard instance for controlling the Flash button. Note that this is given as null for non-flash based buttons.
  4. 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:
  1. node - The button element which has activated the callback
  2. 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:
  1. node - The button element which has activated the callback
  2. object - the button definition object, with all initialisation properties for the button.
  3. 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( 'Mosue out' );
					}
				}
			]
		}
	} );
} );
fnMouseover
Show details 		Callback function for when the mouse if hovered over the button.
Default:
Input parameters:
  1. node - The button element which has activated the callback
  2. object - the button definition object, with all initialisation properties for the button.
  3. 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:
  1. node - The button element which has activated the callback
  2. object - the button definition object, with all initialisation properties for the button.
  3. 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",
					"fnClick": function ( nButton, oConfig, nRow ) {
						alert( 'Row selected' );
					}
				}
			]
		}
	} );
} );
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"
				}
			]
		}
	} );
} );
sButtonClassHover
Show details 		Set the class of the button when the mouse is over it. Note that you cannot rely on the :hover pseudo class due to use of Flash in some buttons, which captures the mouse event. Non-flash buttons also use this method for hover class in order to ensure consistency.
Default:
Type: String
Code example: 
$(document).ready( function () {
	$('#example').dataTable( {
		"sDom": 'T<"clear">lfrtip',
		"oTableTools": {
			"aButtons": [
				{
					"sExtends":     "csv",
					"sButtonClassHover": "my_hover_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 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": "ajax",
					"sButtonText": "Special columns",
					"mColumns": [ 0, 1, 4 ]
				},
				{
					"sExtends": "ajax",
					"sButtonText": "Visible columns",
					"mColumns": "visible"
				}
			]
		}
	} );
} );
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"
				}
			]
		}
	} );
} );