# 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
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://tableexport.travismclarke.com/master.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
|