<?xml version="1.0" encoding="UTF-8" ?>
<dt-button library="Buttons">
	<name>csvHtml5</name>
	<summary>Create and save a CSV file that contains the data from the table (HTML5)</summary>
	<since>1.0.0</since>

	<requires>
		* Buttons' _HTML5 export button_ plug-in.
		* A browser that supports local file saving (IE10+, Chrome, Firefox, Opera).

		To ensure that all files required for CSV HTML5 export are included, the [DataTables download builder](/download) is recommend - select the _HTML5 export_ option.
	</requires>

	<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.

		This button requires a reasonably modern browser in order to operate (IE8 and 9 are not supported). For older browsers, the `b-button csvFlash` button provides similar file creation and save options using the Flash plug-in. The `b-button csv` button can be used to automatically select between this and the `b-button csvFlash` buttons based on the browser's capabilities.


		## Browser support

		The API methods used by this button are supported in the following browsers. If the browser being used does not support the requirements for this button, it simply will not be displayed.

		* Internet Explorer 10+
		  * IE9 and older are not supported as they do not support the `FileReader` API available in newer browsers.
		* Edge: Yes
		* Chrome: Yes
		* Opera: Yes
		* Safari: No
		  * Safari does not currently support the ability to download generated files ([see WebKit bug 156056](https://bugs.webkit.org/show_bug.cgi?id=156056)). As soon as this has been addressed in Safari it will be released here.
	</description>


	<option type="string" name="text" default="CSV">
		The button's display text. The text can be configured using this option (see `b-init buttons.buttons.text`) or the `buttons.copy` option of the DataTables `dt-init language` object.
	</option>

	<option type="string" name="className" default="buttons-csv buttons-html5">
		The button's class name. See `b-init buttons.buttons.className` for details.
	</option>

	<option type="function" name="action">
		Create and save a CSV file.
	</option>

	<option type="string" name="fieldSeparator" default=",">
		The character(s) used to separate fields in the plain text representation of the table that is copied to the system's clipboard.		
	</option>

	<option type="string" name="fieldBoundary" default='"'>
		The character(s) used to enclose each field in the plain text representation of the table that is copied to the system's clipboard. This is automatically added at the start and end of each cell's data.
	</option>

	<option type="string" name="newline" 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.
	</option>

	<option type="object" name="exportOptions" 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 `b-api buttons.exportData()` method for full details - the object given by this parameter is passed directly into that action to gather the required data.
	</option>

	<option type="boolean" name="header" default="true">
		Indicate if the table header should be included in the exported data or not.
	</option>

	<option type="boolean" name="footer" default="false">
		Indicate if the table footer should be included in the exported data or not.
	</option>

	<option type="string|function" name="filename" 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 `-tag title` tag.
	</option>

	<option type="string" name="extension" default=".csv">
		The extension to give the created file name.
	</option>

	<option type="boolean" name="bom" 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](http://utf8everywhere.org/#faq.boms) that the use of a BOM is neither required nor recommended for UTF-8.
	</option>

	<option type="string" name="charset" 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`.
	</option>

	<option type="string" name="escapeChar" 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](https://tools.ietf.org/html/rfc4180).
	</option>

	<option type="function" name="customize" 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:

		1. The CSV data as a string
		2. The button configuration object
		3. A DataTables API instance for the table the button belongs to.
	</option>


	<example title="DataTables initialisation: Use the HTML5 CSV button"><![CDATA[

$('#myTable').DataTable( {
	buttons: [
		'csvHtml5'
	]
} );

]]></example>

	<example title="DataTables initialisation: Use the `b-button csv` button type to automatically select between the Flash and HTML button options."><![CDATA[

$('#myTable').DataTable( {
	buttons: [
		'csv'
	]
} );

]]></example>

	<example title="DataTables initialisation: Use the `exportOptions` to save all data, regardless of filtering"><![CDATA[

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

]]></example>
</dt-button>