Docs
- Migrating from 3.x to 4.x?
- Migrating from 4.x to 5.x?
v3
docs and README:v4
docs and README:v5
docs and README (below):
Getting Started
<script>
tags
Install manually using To use this library, include the FileSaver.js library, and TableExport library before the closing <body>
tag of your HTML document:
<script src="FileSaver.js"></script> ... <script src="tableexport.js"></script>
Install with Bower
$ bower install tableexport.js
Install with npm
$ npm install tableexport
CDN
unpkg
uncompressed | compressed | |
---|---|---|
CSS | ||
JS | ||
Images | — |
Dependencies
Required:
Optional:
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 and TableExport.
- xlsx.core.js by SheetJS
Including
xlsx.core.js
is NOT necessary if installing withBower
ornpm
<script src="xlsx.core.js"></script> <script src="FileSaver.js"></script> ... <script src="tableexport.js"></script>
Older Browsers:
To support legacy browsers ( Chrome < 20, Firefox < 13, Opera < 12.10, IE < 10, Safari < 6 ) include the Blob.js polyfill before the FileSaver.js script.
- Blob.js by eligrey (forked by clarketm)
Including
Blob.js
is NOT necessary if installing withBower
ornpm
<script src="Blob.js"></script> <script src="FileSaver.js"></script> ... <script src="tableexport.js"></script>
Usage
JavaScript
To use this library, simple call the TableExport
constructor:
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.
/* Defaults */ TableExport(document.getElementsByTagName("table"), { headers: true, // (Boolean), display table headers (th or td elements) in the <thead>, (default: true) footers: true, // (Boolean), display table footers (th or td elements) in the <tfoot>, (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; reference theAdd-Ons
section.
Properties
headers
footers
formats
filename
bootstrap
exportButtons
position
ignoreRows
ignoreCols
trimWhitespace
RTL
sheetname
Methods
TableExport supports additional methods (getExportData, update, reset and remove) to control the TableExport
instance after creation.
/* First, call the `TableExport` constructor and save the return instance to a variable */ var table = TableExport(document.getElementById("export-buttons-table"));
getExportData
/* 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
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
/* update */ table.update({ filename: "newFile" // pass in a new set of properties });
reset
/* reset */ table.reset(); // useful for a dynamically altered table
remove
/* remove */ table.remove(); // removes caption and buttons
Settings
Below are some of the popular configurable settings to customize the functionality of the library.
ignoreCSS
/** * CSS selector or selector[] to exclude/remove cells (<td> or <th>) 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
/** * CSS selector or selector[] to replace cells (<td> or <th>) 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"];
/* 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";
/** * 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 packages with customized Bootstrap CSS stylesheets to deliver enhanced table and button styling. These styles can be enabled by initializing with the bootstrap
property set to true
.
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 can be found in the FileSaver.js README. Some legacy browsers may require an additional third-party dependency: Blob.js
Examples
Customizing Properties
headers
footers
formats
filename
bootstrap
exportButtons
position
ignoreRows
ignoreCols
trimWhitespace
RTL
sheetname
Customizing Settings
Miscellaneous
rowspan
colspan
cell data types
(string
,number
,boolean
,date
)emoji
Arabic
Skeletons
- TableExport + RequireJS skeleton.
- TableExport + Flask skeleton.
- TableExport + Webpack 1 skeleton.
- TableExport + Angular 4 + Webpack 2 skeleton.
License
TableExport is licensed under the terms of the Apache-2.0 License
Going Forward
TODOs
- Update JSDocs and TypScript definition file.
- Fix bug with CSV and TXT
ignoreRows
andignoreCols
(rows/cols rendered as empty strings rather than being removed). - Reimplement and test the
update
,reset
, andremove
TableExport prototype properties without requiring jQuery. - Make jQuery as peer dependency and ensure proper TableExport rendering in browser, AMD, and CommonJS environments.
- Force jQuery to be an optionally loaded module.
- Use the enhanced SheetJS
xls
,csv
, andtxt
formats (exposed viaenforceStrictRFC4180
prototype property). - Allow
ignoreCSS
andemptyCSS
to work with anyselector|selector[]
instead of solely a single CSS class. - Ensure (via testing) full consistency and backwards-compatibility for jQuery.
- Add Export as PDF support.
Credits
Special thanks the the following contributors: