csvHtml5

Since: Buttons 1.0.0

Create and save a CSV file that contains the data from the table (HTML5).
Please note - this property requires the Buttons extension for DataTables.

Description

This button provides the end user with the ability to save the table's data into a locally created Comma Separated Values (CSV) file. That file can then be used by variety of programs including spreadsheet and data analysis applications.

If your table has a header or footer with multiple rows, these will all be included in the export. If the header or footer contains colspan or rowspan cells, they will be filled in by an empty string, since CSV is a plain text file and has no way to represent cells that span over others.

Options

This button can have the following options set in its configuration object to customise its actions and display, in addition to those options which are available for all buttons (e.g. buttons.buttons.text):

`action`

Type: function
Default: Unset

Create and save a CSV file.

`bom`

Type: boolean
Default: false
Since: 1.2.2

Option to include UTF-8 Byte Order Mark (true) or not (false). This is disabled by default as the Unicode Standard states that the use of a BOM is neither required nor recommended for UTF-8.

`charset`

Type: string
Default: null

Character set to use in the file export. When null is used (default) the document's character set will be read and used (document.characterSet). The addition of a character set can be disabled by setting this property to false.

`className`

Type: string
Default: buttons-csv buttons-html5

The button's class name. See buttons.buttons.className for details.

`customize`

Type: function
Default: undefined
Since: 1.1.1

Function that can be used to modify the contents of the exported data. The function takes two parameters, the data as configured by the button and the button's configuration object. The value that the function returns is the value that will be used for the export.

This can be particularly useful if you wish to add a company header or footer, description data or any other information to the exported data.

As of Buttons 1.5.2 this function is passed three parameters:

The CSV data as a string
The button configuration object
A DataTables API instance for the table the button belongs to.

`escapeChar`

Type: string
Default: "

Character to use as the escape character for CSV data. This will be prefixed to any data found in the fields which matches that set by the fieldBoundary option. It is a configurable option as different applications can require different options - however the default matches RFC4180.

`exportOptions`

Type: object
Default: {}

Select the data to be gathered from the DataTable for export. This includes options for which columns, rows, ordering and search. Please see the buttons.exportData() method for full details - the object given by this parameter is passed directly into that action to gather the required data.

`extension`

Type: string
Default: .csv

The extension to give the created file name.

`fieldBoundary`

Type: string
Default: "

The character(s) used to enclose each field in the plain text representation of the table that is saved in th CSV file. This is automatically added at the start and end of each cell's data.

`fieldSeparator`

Type: string
Default: ,

The character(s) used to separate fields in the plain text representation of the table that is saved in the CSV file.

`filename`

Type: string|function
Default: *

File name to give the created file (plus the extension defined by the extension option). The special character * is automatically replaced with the value read from the host document's title tag.

`footer`

Type: boolean
Default: true

Indicate if the table footer should be included in the exported data or not. Please note that the default for this parameter was updated in Buttons 3.0 to be true. In earlier versions it was false.

`header`

Type: boolean
Default: true

Indicate if the table header should be included in the exported data or not.

`newline`

Type: string
Default: \n

The character(s) used to separate the lines of data. Please note that on Windows client's the default is \r\n. All other platforms have a default or \n only.

`text`

Type: string
Default: CSV

The button's display text. The text can be configured using this option (see buttons.buttons.text) or the buttons.copy option of the DataTables language object.

Examples

DataTables initialisation: Use the HTML5 CSV button:

new DataTable('#myTable', {
	layout: {
		topStart: {
			buttons: ['csvHtml5']
		}
	}
});

DataTables initialisation: Use the csv button type to alias the HTML button options.:

new DataTable('#myTable', {
	layout: {
		topStart: {
			buttons: ['csv']
		}
	}
});

DataTables initialisation: Use the exportOptions to save all data, regardless of filtering:

new DataTable('#myTable', {
	layout: {
		topStart: {
			buttons: [
				{
					extend: 'csvHtml5',
					text: 'Copy all data',
					exportOptions: {
						modifier: {
							search: 'none'
						}
					}
				}
			]
		}
	}
});