Download Data
- Overview
- CSV Downloads
- XLSX Downloads
- JSON Downloads
- JSON Lines Downloads
- PDF Downloads
- HTML Downloads
- Custom File Formatter
- Advanced Options
- Callbacks
- Events
Overview
Tabulator allows you to download/export the table data as a file directly from your browser, no server needed.
The download will contain the text values of all data currently visible in the table, matching the current column layout, column titles, sorting and filtering.
You have a choice of four file types to choose from:
- csv - Comma separated value file
- json - JSON formatted text file
- xlsx - Excel File (Requires the SheetJS Library)
- pdf - PDF File (Requires the jsPDF Library and jsPDF-AutoTable Plugin)
- html - HTML Table file
To trigger a download, call the download function, passing the file type (from the above list) as the first argument, and an optional second argument of the file name for the download (if this is left out it will be "Tabulator.ext"). The optional third argument is an object containing any setup options for the formatter, such as the delimiter choice for CSV's).
table.download("csv", "data.csv"); //download table data as a CSV formatted file with a file name of data.csv
An optional third argument can be used to pass an options object to a downloader. Each downloader had a specific set of options availablefor this argument
table.download("xlsx", "data.xlsx", {}); //download table data as a XLSX formatted file with a file name of data.xlsx
Download To New Browser Tab
If you want to open the generated file in a new browser tab rather than downloading it straight away, you can use the downloadToTab function. This is particularly useful with the PDF downloader, as it allows you to preview the resulting PDF in a new browser tab
table.downloadToTab("pdf"); //convert table to PDF and open in new tab
Tabulator has no control over how browsers handle the opening of files in new browser tabs, depending on the browser and its configuration some files may open smoothly in a new tab, others may trigger a download prompt.
Download Contents
The download table will contain column header groups, row groups, data trees and column calculations.
You can choose to remove any of these from the output data by setting the values in the downloadConfig option in the table definition:
var table = new Tabulator("#example-table", {
downloadConfig:{
columnHeaders:false, //do not include column headers in downloaded table
columnGroups:false, //do not include column groups in column headers for downloaded table
rowHeaders:false, //do not include row headers in downloaded table
rowGroups:false, //do not include row groups in downloaded table
columnCalcs:false, //do not include column calcs in downloaded table
dataTree:false, //do not include data tree in downloaded table
},
});
Availabilitity
Not all downloaders support column header groups, row groups and column calculations, see the documentation for each downloader for full information.
Field Data
It is worth noting that only columns with a field set in their definitions will be included in the output, this is because exports are generated from table data, and if a column has no field it has no data.
Row Range
By default, only the active rows (rows that have passed filtering) will be included in the download the downloadRowRange option takes a Row Range Lookup value and allows you to choose which rows are included in the download output:
- visible - Rows currently visible in the table viewport
- active - Rows currently in the table (rows that pass current filters etc - default)
- selected - Rows currently selected by the selection module (this includes not currently active rows)
- all - All rows in the table regardless of filters
var table = new Tabulator("#example-table", {
downloadRowRange:"selected", //change default selector to selected
});
You can override the downloadRowRange option when downloading a file but passing the Row Range Lookup value into the optional fourth argument of the download function:
table.download("csv", "data.csv", {}, "visible"); //include only rows visible in the table viewport in the download output
Grouped Data
The all option is not available for grouped data. This is because grouping is carried out after filtering in Tabulators data processing pipeline, so only filtered data ever makes it into groups.
Data Trees
The all option is not available for nested data. This is because child row generation is carried out after filtering in Tabulators data processing pipeline, so only filtered data ever makes it into groups.
CSV Download
Config Options
The CSV downloader does not support grouped column headers, row groups or column calculations, because of the limited way to representing these in CSV data
Custom CSV Delimiters
By default CSV files are created using a comma (,) delimiter. If you need to change this for any reason the you can pass the options object with a delimiter property to the download function which will then use this delimiter instead of the comma.
table.download("csv", "data.csv", {delimiter:"."}); //download a CSV file that uses a fullstop (.) delimiter
Byte Order Mark
If you need the output CSV to include a byte order mark (BOM) to ensure that output with UTF-8 characters can be correctly interpreted across different applications, you should set the bom option to true
table.download("csv", "data.csv", {bom:true}); //include BOM in output
XLSX Download
Sheet Name
You can set the name of the sheet in the xlsx download, using the sheetName property in the options object
table.download("xlsx", "data.xlsx", {sheetName:"MyData"}); //download a xlsx file that has a sheet name of "MyData"
Valid Characters
The sheet name must be a valid Excel sheet name, and cannot include any of the following characters \, /, *, [, ], :, ?
File Compression
The contents of the xlsx document is automatically compressed to significantly reduce the size of the generated file.
Automatic compression can be disabled by setting the compress option to false in the options object:
table.download("xlsx", "data.xlsx", {compress:false}); //prevent compression of output file
SheetJS Options
You can configure the workbook using the native SheetJS workbook setup options with the optional documentProcessingcallback. This function is called when the workbook is ready to be created. The first argument is the workbook object complete with all the sheet data. It must return the updated workbook
table.download("xlsx", "data.xlsx", {
documentProcessing:function(workbook){
//workbook - sheetJS workbook object
//set some properties on the workbook file
workbook.Props = {
Title: "SheetJS Tutorial",
Subject: "Test",
CreatedDate: new Date(2017,12,19)
};
return workbook;
}
}); //download a xlsx file using SheetJS properties
SheetJS File Write Options
You can configure the type of file output using the native SheetJS file writing options with the optional writeOptions option.
table.download("xlsx", "data.wk3", {
writeOptions:{
bookType:"wk3", //save file in lotus notes format
}
});
Multi Table Download
You can pull the data from multiple Tabulators into one xlsx file, using the sheets property of the options object.
This accepts an object, with the keys of each property being the sheet name, and the values being the tables to draw the data from, this can either be a string representing the query selector, or a DOM Node. If you pass a value of true it will use the current table. The order of the keys determines the order of the sheets
var sheets = {
"Accounts Data": "#accounts-table", //first tab with table set using a query selector
"Example Data": true, //second tab, generated from this table
"Finance Data" : financeTable, //third tab with table set to DOM Node
};
table.download("xlsx", "AllData.xlsx", {sheets:sheets}); //download a Xlsx file that has a tab for each table
JSON Download
The json downloader will format data as a JSON formatted array of row objects
Change Field Names
You can use the titleDownload column definition to set the name of the field in the json output
{title:"Name", field:"name", titleDownload:"Persons Name"}
JSON Lines Download
The jsonLines downloader will format data as a series of JSON encoded row objects separated by carriage returns.
This format is commonly used in conjunction with Apache Spark, Hadoop and Hive.
PDF Download
UTF-8 Support
The autotable plugin does not currently fully support UTF-8 with its built-in fonts. This Git Hub Issue contains a workaround for adding UTF-8 enabled fonts if needed
Setup Options
There are a number of options you can pass into the PDF downloader to configure the output
- orientation - the orientation of the page, either portrait or landscape (default value of landscape)
- title - optional page title
- rowGroupStyles - style object for row group headers if used (if you want to override the default styling), it can take any of the standard Autotable style options
- rowCalcStyles - style object for column calculation rows if used (if you want to override the default styling), it can take any of the standard Autotable style options
- jsPDF - an optional object that will be passed into the jsPDF constructor and can take any of the standard jsPDF options
- autoTable - an optional object that can be used to configure advanced styling on the table if needed, this can take ay of the standard AutoTable options
- documentProcessing - an optional callback that is passed the jsPDF document object after the auto-table creation to allow full customisation of the PDF, see the jsPDF document for a full list of methods that can be called on this object
table.download("pdf", "data.pdf", {
orientation:"portrait", //set page orientation to portrait
title:"Dynamics Quotation Report", //add title to report
jsPDF:{
unit:"in", //set units to inches
},
autoTable:{ //advanced table styling
styles: {
fillColor: [100, 255, 255]
},
columnStyles: {
id: {fillColor: 255}
},
margin: {top: 60},
},
documentProcessing:function(doc){
//carry out an action on the doc object
}
});
AutoTable Function
You can also pass a function into the autoTable property, this should return the autoTable config object. The jsPDF document object will be passed in as the first argument of this function which will allow you to call any of the jsPDF API functions on the document, so you can for example add additional text to your PDF or set the font.
table.download("pdf", "data.pdf", {
orientation:"portrait", //set page orientation to portrait
autoTable:function(doc){
//doc - the jsPDF document object
//add some text to the top left corner of the PDF
doc.text("SOME TEXT", 1, 1);
//return the autoTable config options object
return {
styles: {
fillColor: [200, 00, 00]
},
};
},
});
Custom File Formatter
If you want to create a custom file type from the table data then you can pass a function to the type argument, instead of a string value. At the end of this function you must call the setFileContents function, passing the formatted data and the mime type.
//custom file formatter
var fileFormatter = function(list, options, setFileContents){
//list - an array of export rows representing one row of data for the table;
//options - the options object passed from the download function
//setFileContents - function to call to pass the formatted data to the downloader
var fileContents = [];
//iterate over rows
list.forEach((row) => {
var item = [];
switch(row.type){
case "header":
//handle header rows
case "group":
//handle group header rows
case "calc":
//handle calculation rows
case "row":
//iterate over the columns in a row
row.columns.forEach((col) => {
if(col){
item.push(col.value);
}
});
fileContents.push(item.join(delimiter));
break;
}
});
//trigger file download, passing the formatted data and mime type
setFileContents(names.join(", "), "text/plain");
}
//trigger file download
table.download(fileFormatter, "test.txt");
Note: You can find out more about data URI's Here.
Export List
The list argument passed into the formatter contains all of the information you should need to layout your table. It is an array of ExportRow objects. Each object represents a row of data in the table arranged in the order they currently appear. You should iterate over this array to built each row of your output data.
ExportRow Object
The ExportRow object has 4 properties to describe the row it represents:
- type - the type of row, this can have one of 4 values:
- row - A standard row from the table
- calc - A calculation row
- group - A row group header
- header - a row of column headers (column titles)
- component - The Component Object for the row or group that the ExporRow represents
- indent - if the row is either a group or a data tree child, this value contains an integer representing which level the row is on, the greater the number the more indented the row should be
- columns - an array of ExportColumn objects representing the columns on the row.
It takes the following format
{
type: "row",
component: RowComponent,
indent: 0,
columns: [ExportColumn, ExportColumn, ExportColumn],
}
The columns property of the ExportRow object contains an array of ExportColumn objects representing the columns on the row. in the case of tables with column groups this array can also include null values representing spaces where columns would have been if not for a neighbouring column taking up multiple columns or rows, such as a column group header. These null values are included to help deal with rowspan and colspan alignment and in most cases can be ignored. (an example of where they can come in useful can be found in the built-in xlsx downloader)
{
type: "row",
component: RowComponent,
indent: 0,
columns: [null, ExportColumn, ExportColumn, null, ExportColumn],
}
When dealing with group type ExportRow objects the columns array will contain only one ExportColumn that represents the value for the group header row
ExportColumn Object
The ExportColumn object has 5 properties to describe the column it represents:
- value - The value of the cell or title of the column header
- width - The width in columns, generally this has a value of 1, but when dealing with grouped column headers this describes how many columns wide the column group should be, in the case of group headers this shows as the number of columns in the table to esure the group header is full width
- height - The height of the cell in rows, generally this has a value of 1, but when dealing with grouped column headers this describes how rows hight the cell should be to allow for neighbouring grouped columun headers
- depth - This usually has a value of 1, in the case of grouped column headers, this shows how many levels of child columns the group has
- component - The Component Object for the column that the ExporColumn represent
For a standard cell in a row it would take the following format:
{
value: "Bob Monkhouse",
width: 1,
height: 1,
depth: 1,
component: ColumnComponent,
}
For a column group header containing two child rows it would look like this:
{
value: "Column Group",
width: 2, //the group header is two columns wide
height: 1,
depth: 2, //the group header is made up of two levels, itself and its children
component: ColumnComponent,
}
For a column header next to a column group header containing two child rows it would look like this:
{
value: "Age",
width: 1,
height: 2, //the column header has a rowspan of 2 to match the height of the column group next to it
depth: 1,
component: ColumnComponent,
}
For a cell representing a group header it would take the following format:
{
value: "Green", //group header title
width: 7, //total number of columns in table to ensure column header is full width
height: 1,
depth: 1,
component: GroupnComponent, //component object for the group of the header
}
HTML Download
Styling
By default the HTML output is a simple unstyled table. if you would like to match the current table styling you can set the style property to true in the options object
table.download("html", "data.html", {style:true}); //download a html table with matching styling
Advanced Options
Column Visibility
By default all visibile columns will be included in the downloaded file, to customize your download, the download option in the column definition can be used to determine the visibility of each column in the download output.
Include Hidden Column in Download
By default hidden columns are not included in the download, If you want to force a particular column to show in the download, even if it is hidden, you can set the download property in its column definition object to true:
var table = new Tabulator("#example-table", {
columns:[
{title:"id", field:"id", visible:false, download:true} //force hidden field to show in download
]
});
Hide Column In Download
If you don't want to show a particular column in the downloaded data you can set the download property in its column definition object to false:
var table = new Tabulator("#example-table", {
columns:[
{title:"Hidden Column", field:"secret", download:false} //hide data in download
]
});
Variable Visibility
For more complex usage cases you can pass a callback function to the download option, this will be called just before the download is started. The function will be passed the Column Component of its column as the first argument and should return a boolean indicating the columns download visibility.
var table = new Tabulator("#example-table", {
columns:[
{title:"id", field:"id", download:function(column){
//column - column component for current column
return true; //make column visible in download
}}
]
});
Change Column Title in Download
You can add a custom column title to be used in the downloaded data instead of the usual title by setting the titleDownload property in the column definition object:
var table = new Tabulator("#example-table", {
columns:[
{title:"Name", field:"name", titleDownload:"Full Name"} //change column title to "Full Name" in download
]
});
Download Accessors
You can use the accessorDownload and accessorDownloadParams options on a column definition to alter the value of data in a column before it is added to the download.
The example below will transform all ages into a boolean, showing if they are over 18 or not. The accessorDownloadParams is used to pass the age limit to the accessor so the same accessor function can be used on multiple columns with different age limits:
var ageAccessor = function(value, data, type, params, column){
return value >= params.legalAge;
}
{title:"Under Age", field:"age", accessorDownload:ageAccessor, accessorDownloadParams:{legalAge:18} }
Full details of how accessors work can be found in the Accessors Documentation.
Group Header
When downloading, you may want to apply a different group header from the one usualy used in the table. You can now do this using the groupHeaderDownload table option, which takes the same inputs as the standard groupHeader property.
var table = new Tabulator("#example-table", {
groupHeader: function(value, count, data, group){
return value + "<span style='color:#d00; margin-left:10px;'>(" + count + " item)</span>";
},
groupHeaderDownload: function(value, count, data, group){
return value;
},
});
Passing a value of false into groupHeaderDownload will cause the header to show the groups key as plain text
Intercept & Manipulate Download Blob
The downloadEncoder callback allows you to intercept the download file data before the users is prompted to save the file.
The first argument of the function is the file contents returned from the downloader, the second argument is the suggested mime type for the output. The function is should return a blob of the file to be downloaded.
var table = new Tabulator("#example-table", {
downloadEncoder:function(fileContents, mimeType){
//fileContents - the unencoded contents of the file
//mimeType - the suggested mime type for the output
//custom action to send blob to server could be included here
return new Blob([fileContents], {type:mimeType}); //must return a blob to proceed with the download, return false to abort download
}
});
If you would prefer to abort the download you can return false from this callback. This could be useful for example if you want to send the created file to a server via ajax rather than allowing the user to download the file.
Callbacks
A range of callbacks are available for downloads. See the Download Callbacks section for more information.
Events
A range of events are available for downloads. See the Download Events section for more information.