# TableExport
The simple, easy-to-implement library to export HTML tables to `xlsx`, `xls`, `csv`, and `txt` files.
[](https://tableexport.travismclarke.com/master) [](https://travis-ci.org/clarketm/TableExport) [](https://tableexport.travismclarke.com/master) [](https://tableexport.travismclarke.com/master)
## Docs
* [Migrating from **3.x** to **4.x**?](https://tableexport.travismclarke.com/docs/migrating_v3_to_v4)
* [Migrating from **4.x** to **5.x**?](https://tableexport.travismclarke.com/docs/migrating_v4_to_v5)
* [`v3` docs](https://tableexport.v3.travismclarke.com/) and [README](https://github.com/clarketm/TableExport/tree/3.x.x#getting-started):
* [`v4` docs](https://tableexport.travismclarke.com/READMEv4.html) and [README](https://github.com/clarketm/TableExport/tree/4.x.x#getting-started):
* [`v5` docs](https://tableexport.travismclarke.com/) and [README](https://github.com/clarketm/TableExport/#getting-started):
## Getting Started
### Install manually using `
...
```
### Install with Bower
```
$ bower install tableexport.js
```
### Install with npm
```
$ npm install tableexport
```
### CDN
| | uncompressed | compressed |
| :--------: | :----------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| **CSS** | [🔗](https://unpkg.com/tableexport/dist/css/tableexport.css) | [🔗](https://unpkg.com/tableexport/dist/css/tableexport.min.css) |
| **JS** | [🔗](https://unpkg.com/tableexport/dist/js/tableexport.js) | [🔗](https://unpkg.com/tableexport/dist/js/tableexport.min.js) |
| **Images** | — | [🔗xlsx](https://unpkg.com/tableexport/dist/img/xlsx.svg)[🔗xls](https://unpkg.com/tableexport/dist/img/xls.svg)[🔗csv](https://unpkg.com/tableexport/dist/img/csv.svg)[🔗txt](https://unpkg.com/tableexport/dist/img/txt.svg) |
### Dependencies
#### Required:
* [FileSaver.js](https://github.com/clarketm/FileSaver.js/)
#### Optional:
* [jQuery](https://jquery.com) (1.2.1 or higher)
* [Bootstrap](http://getbootstrap.com/getting-started/#download) (3.1.0 or higher)
#### Add-Ons:
In order to provide **Office Open XML SpreadsheetML Format ( `.xlsx` )** support, you must include the following third-party library in your project before both [FileSaver.js](https://github.com/clarketm/FileSaver.js/) and [TableExport](https://tableexport.travismclarke.com).
* [xlsx.core.js](https://github.com/SheetJS/js-xlsx) by *SheetJS*
> Including `xlsx.core.js` is **NOT** necessary if installing with [`Bower`](#install-with-bower) or [`npm`](#install-with-npm)
```markup
...
```
#### Older Browsers:
To support legacy browsers ( **Chrome** < 20, **Firefox** < 13, **Opera** < 12.10, **IE** < 10, **Safari** < 6 ) include the [Blob.js](https://github.com/clarketm/Blob.js/) polyfill before the [FileSaver.js](https://github.com/clarketm/FileSaver.js/) script.
* [Blob.js](https://github.com/clarketm/Blob.js) by *eligrey* (forked by *clarketm*)
> Including `Blob.js` is **NOT** necessary if installing with [`Bower`](#install-with-bower) or [`npm`](#install-with-npm)
```markup
...
```
## Usage
### JavaScript
To use this library, simple call the [`TableExport`](https://tableexport.travismclarke.com) constructor:
```javascript
new TableExport(document.getElementsByTagName("table"));
// OR simply
TableExport(document.getElementsByTagName("table"));
// OR using jQuery
$("table").tableExport();
```
Additional properties can be passed-in to customize the look and feel of your tables, buttons, and exported data.
Notice that by default, TableExport will create export buttons for three different filetypes *`xls`, `csv`, `txt`*. You can choose which buttons to generate by setting the `formats` property to the filetype(s) of your choice.
```javascript
/* Defaults */
TableExport(document.getElementsByTagName("table"), {
headers: true, // (Boolean), display table headers (th or td elements) in the , (default: true)
footers: true, // (Boolean), display table footers (th or td elements) in the , (default: false)
formats: ["xlsx", "csv", "txt"], // (String[]), filetype(s) for the export, (default: ['xlsx', 'csv', 'txt'])
filename: "id", // (id, String), filename for the downloaded file, (default: 'id')
bootstrap: false, // (Boolean), style buttons using bootstrap, (default: true)
exportButtons: true, // (Boolean), automatically generate the built-in export buttons for each of the specified formats (default: true)
position: "bottom", // (top, bottom), position of the caption element relative to table, (default: 'bottom')
ignoreRows: null, // (Number, Number[]), row indices to exclude from the exported file(s) (default: null)
ignoreCols: null, // (Number, Number[]), column indices to exclude from the exported file(s) (default: null)
trimWhitespace: true, // (Boolean), remove all leading/trailing newlines, spaces, and tabs from cell text in the exported file(s) (default: false)
RTL: false, // (Boolean), set direction of the worksheet to right-to-left (default: false)
sheetname: "id" // (id, String), sheet name for the exported spreadsheet, (default: 'id')
});
```
> **Note:** to use the `xlsx` filetype, you must include [js-xlsx](https://github.com/SheetJS/js-xlsx/blob/master/dist/xlsx.core.min.js); reference the [`Add-Ons`](#add-ons) section.
### Properties
* [`headers`](https://tableexport.v3.travismclarke.com/examples/headers_footers.html)
* [`footers`](https://tableexport.v3.travismclarke.com/examples/headers_footers.html)
* [`formats`](https://tableexport.v3.travismclarke.com/examples/formats-xlsx-xls-csv-txt.html)
* [`filename`](https://tableexport.v3.travismclarke.com/examples/filename.html)
* [`bootstrap`](https://tableexport.v3.travismclarke.com/examples/bootstrap.html)
* [`exportButtons`](https://tableexport.v3.travismclarke.com/examples/exportButtons.html)
* [`position`](https://tableexport.v3.travismclarke.com/examples/position.html)
* [`ignoreRows`](https://tableexport.v3.travismclarke.com/examples/ignore-row-cols-cells.html)
* [`ignoreCols`](https://tableexport.v3.travismclarke.com/examples/ignore-row-cols-cells.html)
* [`trimWhitespace`](https://tableexport.v3.travismclarke.com/examples/whitespace.html)
* [`RTL`](https://tableexport.v3.travismclarke.com/examples/right-to-left.html)
* [`sheetname`](https://tableexport.v3.travismclarke.com/examples/sheetname.html)
### Methods
TableExport supports additional methods (**getExportData**, **update**, **reset** and **remove**) to control the [`TableExport`](https://tableexport.travismclarke.com) instance after creation.
```javascript
/* First, call the `TableExport` constructor and save the return instance to a variable */
var table = TableExport(document.getElementById("export-buttons-table"));
```
#### [`getExportData`](https://tableexport.v3.travismclarke.com/examples/exportButtons.html)
```javascript
/* get export data */
var exportData = table.getExportData(); // useful for creating custom export buttons, i.e. when (exportButtons: false)
/*****************
** exportData ***
*****************
{
"export-buttons-table": {
xls: {
data: "...",
fileExtension: ".xls",
filename: "export-buttons-table",
mimeType: "application/vnd.ms-excel"
},
...
}
};
*/
```
#### [`getFileSize`](https://tableexport.v3.travismclarke.com/examples/exportButtons.html)
```javascript
var tableId = "export-buttons-table";
var XLS = table.CONSTANTS.FORMAT.XLS;
/* get export data (see `getExportData` above) */
var exportDataXLS = table.getExportData()[tableId][XLS];
/* get file size (bytes) */
var bytesXLS = table.getFileSize(exportDataXLS.data, exportDataXLS.fileExtension);
/**********************************
** bytesXLS (file size in bytes)
**********************************
352
*/
```
#### [`update`](https://tableexport.v3.travismclarke.com/examples/update_reset_remove.html)
```javascript
/* update */
table.update({
filename: "newFile" // pass in a new set of properties
});
```
#### [`reset`](https://tableexport.v3.travismclarke.com/examples/update_reset_remove.html)
```javascript
/* reset */
table.reset(); // useful for a dynamically altered table
```
#### [`remove`](https://tableexport.v3.travismclarke.com/examples/update_reset_remove.html)
```javascript
/* remove */
table.remove(); // removes caption and buttons
```
### Settings
Below are some of the popular configurable settings to customize the functionality of the library.
#### [`ignoreCSS`](https://tableexport.v3.travismclarke.com/examples/ignore-row-cols-cells.html)
```javascript
/**
* CSS selector or selector[] to exclude/remove cells (| or | ) from the exported file(s).
* @type {selector|selector[]}
* @memberof TableExport.prototype
*/
// selector
TableExport.prototype.ignoreCSS = ".tableexport-ignore";
// selector[]
TableExport.prototype.ignoreCSS = [".tableexport-ignore", ".other-ignore-class"];
// OR using jQuery
// selector
$.fn.tableExport.ignoreCSS = ".tableexport-ignore";
// selector[]
$.fn.tableExport.ignoreCSS = [".tableexport-ignore", ".other-ignore-class"];
```
#### [`emptyCSS`](https://tableexport.v3.travismclarke.com/examples/ignore-row-cols-cells.html)
```javascript
/**
* CSS selector or selector[] to replace cells ( | or | ) with an empty string in the exported file(s).
* @type {selector|selector[]}
* @memberof TableExport.prototype
*/
// selector
TableExport.prototype.emptyCSS = ".tableexport-empty";
// selector[]
TableExport.prototype.emptyCSS = [".tableexport-empty", ".other-empty-class"];
// OR using jQuery
// selector
$.fn.tableExport.emptyCSS = ".tableexport-empty";
// selector[]
$.fn.tableExport.emptyCSS = [".tableexport-empty", ".other-empty-class"];
```
```javascript
/* default charset encoding (UTF-8) */
TableExport.prototype.charset = "charset=utf-8";
/* default `filename` property if "id" attribute is unset */
TableExport.prototype.defaultFilename = "myDownload";
/* default class to style buttons when not using Bootstrap or the built-in export buttons, i.e. when (`bootstrap: false` & `exportButtons: true`) */
TableExport.prototype.defaultButton = "button-default";
/* Bootstrap classes used to style and position the export button, i.e. when (`bootstrap: true` & `exportButtons: true`) */
TableExport.prototype.bootstrapConfig = ["btn", "btn-default", "btn-toolbar"];
/* row delimeter used in all filetypes */
TableExport.prototype.rowDel = "\r\n";
```
```javascript
/**
* Format-specific configuration (default class, content, mimeType, etc.)
* @memberof TableExport.prototype
*/
formatConfig: {
/**
* XLSX (Open XML spreadsheet) file extension configuration
* @memberof TableExport.prototype
*/
xlsx: {
defaultClass: 'xlsx',
buttonContent: 'Export to xlsx',
mimeType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
fileExtension: '.xlsx'
},
xlsm: {
defaultClass: 'xlsm',
buttonContent: 'Export to xlsm',
mimeType: 'application/vnd.ms-excel.sheet.macroEnabled.main+xml',
fileExtension: '.xlsm'
},
xlsb: {
defaultClass: 'xlsb',
buttonContent: 'Export to xlsb',
mimeType: 'application/vnd.ms-excel.sheet.binary.macroEnabled.main',
fileExtension: '.xlsb'
},
/**
* XLS (Binary spreadsheet) file extension configuration
* @memberof TableExport.prototype
*/
xls: {
defaultClass: 'xls',
buttonContent: 'Export to xls',
separator: '\t',
mimeType: 'application/vnd.ms-excel',
fileExtension: '.xls',
enforceStrictRFC4180: false
},
/**
* CSV (Comma Separated Values) file extension configuration
* @memberof TableExport.prototype
*/
csv: {
defaultClass: 'csv',
buttonContent: 'Export to csv',
separator: ',',
mimeType: 'text/csv',
fileExtension: '.csv',
enforceStrictRFC4180: true
},
/**
* TXT (Plain Text) file extension configuration
* @memberof TableExport.prototype
*/
txt: {
defaultClass: 'txt',
buttonContent: 'Export to txt',
separator: ' ',
mimeType: 'text/plain',
fileExtension: '.txt',
enforceStrictRFC4180: true
}
},
//////////////////////////////////////////
// Configuration override example
//////////////////////////////////////////
/* Change the CSV (Comma Separated Values) `mimeType` to "application/csv" */
TableExport.prototype.formatConfig.xlsx.mimeType = "application/csv"
```
### CSS
[TableExport](https://tableexport.travismclarke.com) packages with customized [Bootstrap](http://getbootstrap.com/getting-started/#download) CSS stylesheets to deliver enhanced table and button styling. These styles can be *enabled* by initializing with the `bootstrap` property set to `true`.
```javascript
TableExport(document.getElementsByTagName("table"), {
bootstrap: true
});
```
When used alongside Bootstrap, there are four custom classes **`.xlsx`, `.xls`, `.csv`, `.txt`** providing button styling for each of the exportable filetypes.
### Browser Support
| | Chrome | Firefox | IE | Opera | Safari |
| :---------: | :----: | :-----: | :-: | :---: | :----: |
| **Android** | ✓ | ✓ | - | ✓ | - |
| **iOS** | ✓ | - | - | - | ✓ |
| **Mac OSX** | ✓ | ✓ | - | ✓ | ✓ |
| **Windows** | ✓ | ✓ | ✓ | ✓ | ✓ |
> A full list of [browser support](https://github.com/clarketm/FileSaver.js#supported-browsers) can be found in the [FileSaver.js](https://github.com/clarketm/FileSaver.js) README. Some [legacy browsers](https://github.com/clarketm/FileSaver.js#supported-browsers) may require an additional third-party dependency: [Blob.js](https://github.com/clarketm/Blob.js/)
### Examples
#### Customizing Properties
* [`headers`](https://tableexport.v3.travismclarke.com/examples/headers_footers.html)
* [`footers`](https://tableexport.v3.travismclarke.com/examples/headers_footers.html)
* [`formats`](https://tableexport.v3.travismclarke.com/examples/formats-xlsx-xls-csv-txt.html)
* [`filename`](https://tableexport.v3.travismclarke.com/examples/filename.html)
* [`bootstrap`](https://tableexport.v3.travismclarke.com/examples/bootstrap.html)
* [`exportButtons`](https://tableexport.v3.travismclarke.com/examples/exportButtons.html)
* [`position`](https://tableexport.v3.travismclarke.com/examples/position.html)
* [`ignoreRows`](https://tableexport.v3.travismclarke.com/examples/ignore-row-cols-cells.html)
* [`ignoreCols`](https://tableexport.v3.travismclarke.com/examples/ignore-row-cols-cells.html)
* [`trimWhitespace`](https://tableexport.v3.travismclarke.com/examples/whitespace.html)
* [`RTL`](https://tableexport.v3.travismclarke.com/examples/right-to-left.html)
* [`sheetname`](https://tableexport.v3.travismclarke.com/examples/sheetname.html)
#### Customizing Settings
* [`ignoreCSS`](https://tableexport.v3.travismclarke.com/examples/ignore-row-cols-cells.html)
* [`emptyCSS`](https://tableexport.v3.travismclarke.com/examples/ignore-row-cols-cells.html)
#### Miscellaneous
* [`rowspan`](https://tableexport.v3.travismclarke.com/examples/rowspan-colspan.html)
* [`colspan`](https://tableexport.v3.travismclarke.com/examples/rowspan-colspan.html)
* [`cell data types`](https://tableexport.v3.travismclarke.com/examples/cell-data-types.html) (`string`, `number`, `boolean`, `date`)
* [`emoji`](https://tableexport.v3.travismclarke.com/examples/unicode-emoji.html)
* [`Arabic`](https://tableexport.v3.travismclarke.com/examples/arabic-language.html)
#### Skeletons
* [TableExport + RequireJS](https://github.com/clarketm/tableexport_requirejs_app) skeleton.
* [TableExport + Flask](https://github.com/clarketm/tableexport_flask_app) skeleton.
* [TableExport + Webpack 1](https://github.com/clarketm/tableexport_webpack-v1_app) skeleton.
* [TableExport + Angular 4 + Webpack 2](https://github.com/clarketm/tableexport_angular4_webpack2_app) skeleton.
### License
[TableExport](https://tableexport.travismclarke.com) is licensed under the terms of the [Apache-2.0](http://www.apache.org/licenses/LICENSE-2.0.html) License
### Going Forward
#### TODOs
* [x] Update JSDocs and TypScript definition file.
* [x] Fix bug with **CSV** and **TXT** `ignoreRows` and `ignoreCols` (rows/cols rendered as empty strings rather than being *removed*).
* [x] Reimplement and test the `update`, `reset`, and `remove` **TableExport** prototype properties without requiring jQuery.
* [x] Make jQuery as *peer dependency* and ensure proper **TableExport** rendering in browser, AMD, and CommonJS environments.
* [x] Force jQuery to be an optionally loaded module.
* [x] Use the enhanced [SheetJS](https://github.com/SheetJS/js-xlsx#supported-output-formats) `xls`, `csv`, and `txt` formats (exposed via `enforceStrictRFC4180` prototype property).
* [x] Allow `ignoreCSS` and `emptyCSS` to work with any `selector|selector[]` instead of solely a single CSS class.
* [x] Ensure (via testing) full consistency and backwards-compatibility for jQuery.
* [ ] Add **Export as PDF** support.
### Credits
Special thanks the the following contributors:
* [SheetJS](https://github.com/SheetJS) - js-xlsx
* [Eli Grey](https://github.com/eligrey) - FileSaver.js & Blob.js
|