buttons.exportData()

Since: Buttons 1.0.0

Obtain data from the DataTable that is suitable for exporting.
Please note - this property requires the Buttons extension for DataTables.

Description

It is relatively common to wish to use Buttons to obtain the data from a DataTable so it can be exported in some form (copy to clipboard, save to Excel, etc). As this operation can be required by a number of plug-in button types, Buttons provides this method for DataTables to quickly and easily obtain data from a DataTable in a form that is suitable for export.

In essence this method will return an object that contains header, footer and body information from the table. It is then up to the caller to decide how to export that data - for example with a CSV file you would join the items for each row using commas and then join the rows with new lines.

As of Buttons 1.5.0 the exported data from this method will automatically attempt to determine if any rows in the table are selected. If they are, the export will be restricted to those rows. If no rows are selected, the full data set will be exported.

If this behaviour is not what you desire, set the selected option of the modifier object to be null. It will then include all rows in the export, regardless of any rows being selected. Equally, if you want to force the export to include only selected rows, even if no rows are selected (i.e. none would be exported), set this parameter to be true.

Type

function buttons.exportData( [ options ] )

Description:

Obtain data from a DataTable that is suitable for exporting by saving into a file or copying to clipboard.

Parameters:

Name Type Optional

	Name	Type	Optional
1	`options`	`object`	Yes
	This option is used to define what data will be read from the table, and how that data will be modified (if at all) to be suitable for export. The object can have the following properties: `row-selector` `rows` - The row selector to use. Default - all rows `column-selector` `columns` - The column selector to use. Default - all columns `selector-modifier` `modifier` - How the ordering and search state of the table should be applied. Default - `{search: 'applied', order: 'applied'}` `string` `orthogonal` - What orthogonal data type to request when getting the data for a cell. Default `display` - i.e. the data shown in the table. `boolean` `stripHtml` - Indicate if HTML should be stripped from the read data if there is any (`true`) or not (`false`). Default - `true`. `boolean` `stripNewlines` - Indicate if newline characters should be stripped from the read data if there are any (`true`) or not (`false`). Default - `true`. `boolean` `decodeEntities` - Indicate if HTML entities should be decoded (`true`) or not (`false`) - for example `>` would become `>`. For larger tables you may wish to disable this option as it can decrease performance. Default - `true`. `boolean` `escapeExcelFormula` (since 3.2.0) - Prefix spreadsheet formulas in individual cells with an apostrophe to prevent them from being executed immediately on loading the spreadsheet. This is particularly important when using CSV and importing into Excel. Default - `false` (although default enabled for the `csv` button type). `boolean` `trim` - Indicate if the read data should have white space trimmed from the start and end of the value (`true`) or not (`false`). Default - `true`. `object` `format` (since 1.1.0) - Container object for the cell formatting functions that the export will use `function` `format.header` - Function that will be used to format the data in the header cells - default function will strip HTML tags. The returned value is used in the exported data for the column headers. Three arguments are passed in: The cell's innerHTM Cell's column index. The cell node (since Buttons 1.2.2) `function` `format.footer` - Function that will be used to format the data in the footer cells. - default function will strip HTML tags. The returned value is used in the exported data for the column footer. Three arguments are passed in: The cell's innerHTML Cell's column index The cell node (since Buttons 1.2.2) `function` `format.body` - Function that will be used to format the data from the table's body cells - default function will strip HTML tags. The returned value is used in the exported data for each cell. Four arguments are passed in: The cell's innerHTML Cell's row index Cell's column index The cell node (since Buttons 1.2.2) `function` `customizeData` (since Buttons 1.5.2) - Function that can be used to modify the data used for the export, after all of it has been gathered and pre-processed by the above formatting options. A single argument is passed in and no return parameter is expected (mutate the object passed in to alter the data): Data for export. This is an object with the following properties: `header` - Array of data for the header `footer` - Array of data for the footer `body` - 2D array of data for the body.

options

object

Yes

This option is used to define what data will be read from the table, and how that data will be modified (if at all) to be suitable for export.

The object can have the following properties:

row-selector rows - The row selector to use. Default - all rows
column-selector columns - The column selector to use. Default - all columns
selector-modifier modifier - How the ordering and search state of the table should be applied. Default - {search: 'applied', order: 'applied'}
string orthogonal - What orthogonal data type to request when getting the data for a cell. Default display - i.e. the data shown in the table.
boolean stripHtml - Indicate if HTML should be stripped from the read data if there is any (true) or not (false). Default - true.
boolean stripNewlines - Indicate if newline characters should be stripped from the read data if there are any (true) or not (false). Default - true.
boolean decodeEntities - Indicate if HTML entities should be decoded (true) or not (false) - for example > would become >. For larger tables you may wish to disable this option as it can decrease performance. Default - true.
boolean escapeExcelFormula (since 3.2.0) - Prefix spreadsheet formulas in individual cells with an apostrophe to prevent them from being executed immediately on loading the spreadsheet. This is particularly important when using CSV and importing into Excel. Default - false (although default enabled for the csv button type).
boolean trim - Indicate if the read data should have white space trimmed from the start and end of the value (true) or not (false). Default - true.
object format (since 1.1.0) - Container object for the cell formatting functions that the export will use
- function format.header - Function that will be used to format the data in the header cells - default function will strip HTML tags. The returned value is used in the exported data for the column headers. Three arguments are passed in:
1. The cell's innerHTM
2. Cell's column index.
3. The cell node (since Buttons 1.2.2)
- function format.footer - Function that will be used to format the data in the footer cells. - default function will strip HTML tags. The returned value is used in the exported data for the column footer. Three arguments are passed in:
1. The cell's innerHTML
2. Cell's column index
3. The cell node (since Buttons 1.2.2)
- function format.body - Function that will be used to format the data from the table's body cells - default function will strip HTML tags. The returned value is used in the exported data for each cell. Four arguments are passed in:
1. The cell's innerHTML
2. Cell's row index
3. Cell's column index
4. The cell node (since Buttons 1.2.2)
- function customizeData (since Buttons 1.5.2) - Function that can be used to modify the data used for the export, after all of it has been gathered and pre-processed by the above formatting options. A single argument is passed in and no return parameter is expected (mutate the object passed in to alter the data):
1. Data for export. This is an object with the following properties:
- header - Array of data for the header
- footer - Array of data for the footer
- body - 2D array of data for the body.

Returns:

object

An object which has three parameters:

header - An array of header data for the selected columns
footer - An array of footer data for the selected columns
body - An array of arrays, which each inner array representing a row, and its items being the cells for the selected columns.

Examples

Get all data in the table for export:

var table = new DataTable('#myTable');

var data = table.buttons.exportData();
// Do something with the 'data' variable

Export only selected rows (with the Select extension):

var table = new DataTable('#myTable');

var data = table.buttons.exportData({
	modifier: {
		selected: true
	}
});
// Do something with the 'data' variable

Get the data for the visible columns only:

var table = new DataTable('#myTable');

var data = table.buttons.exportData({
	columns: ':visible'
});
// Do something with the 'data' variable

Format the header cells - adding the column index:

var table = new DataTable('#myTable');

var data = table.buttons.exportData({
	format: {
		header: function (data, columnIdx) {
			return columnIdx + ': ' + data;
		}
	}
});
// Do something with the 'data' variable