Notes
Changes
- In v2.27.0, the
output_callback
now includes aurl
parameter. - In v2.25.2, updated the
output_saveRows
option to accept a function. - In v2.25.1, the
output_callback
can return modified data instead of a boolean. - In v2.22.4, added
output_formatContent
callback function which allows for extra formatting of cell content (e.g. convert'&'
→'&'
). - In v2.22.2,
- The data-attribute used by the
output_dataAttrib
can now be an empty string. - Update
output_saveRows
option, it now includes the ability to set a jQuery filter selector.- For example, if you want to only output rows with an active checkbox, set this option to
'.checked'
(default class added by the checkbox parser contained in the "parser-input-select.js" file). - To output only visible active checkboxes, set this option to
'.checked:visible'
. - To output rows without an active checkbox, set this option to
':not(.checked)'
, etc. - More details can be found in the options section.
- For example, if you want to only output rows with an active checkbox, set this option to
- Fix issue with
output_hiddenColumns
causing an empty output.
- The data-attribute used by the
- In v2.22.0,
- Added the BOM back to the UTF-8 csv downloadable file to support unicode characters in Excel.
- Add
output_hiddenColumns
which includes hidden columns in the output whentrue
.
- In v2.21.0, added the
output_includeFooter
option. - In v2.17.5, the need to modify the server's content disposition no longer exists.
- In v2.17.0,
- Added the
output_ignoreColumns
option & modified theoutput_callback
parameters. - Added
output_duplicateSpans
option to duplicate (whentrue
) colspan & rowspan content across cells.
- Added the
- In v2.16.4, added the
output_encoding
option.
Requirements
- This widget will only work in tablesorter version 2.8+ and jQuery version 1.7+.
To download a file with the set filename and extension, the server'sContent-disposition
needs to be set- This widget now uses a method available in modern browsers (IE10+) to download files without the need for server side modifications
- Support in older browsers (IE9 and older) have not been throughly tested.
Features & Usage
- This widget can output the table data to:
- JSON
- Array of arrays
- Text with any separator (comma, tab, etc).
- Rowspan and colspan are supported by this widget. Please take note of additional information in the "Rowspan and colspan" section below.
- This demo uses Bootstrap to create the download button dropdown for each table allowing the user to choose the settings
- Using Bootstrap was kind of a pain in the butt... any click inside would close the dropdown.
- I am sure there are better alternatives as the download button and popup are all completely customizable.
- The download dropdown code is probably overly complicated because it is set up for two tables & allows modifying almost all of the options.
- The only thing needed to output the table code (download or open a popup) is to trigger the following event after all of your widget options are set as desired:
$table.trigger('outputTable');
Known Issues
- Some versions of Safari do not fully support direct downloading, nor will you be able to save the file with the set file name; for more details please refer to this issue.
Credit
- This widget uses heavily modified code from:
- HTML Table to CSV (License unknown)
- Download-File-JS (Apache v2.0)
- Download demo from ebidel/html5demos
Basic Setup
Using the default settings of this widget will:
This is an example of how to setup a table using only the default settings:
- Output csv to a popup window.
- Only include the last header row (if there are more than one rows).
- Only include filtered rows (all rows will be included, even if the filter widget isn't being used).
- Will only output the table cell text (ignoring any HTML).
This is an example of how to setup a table using only the default settings:
HTML
<button class="download">Get CSV</button> <table class="tablesorter"> <!-- .... --> </table>
Script
$(function () { var $table = $('table'); $('.download').click(function(){ // tell the output widget do it's thing $table.trigger('outputTable'); }); $table.tablesorter({ theme: 'blue', widgets: ['zebra', 'output'] }); });Modification of the
.htaccess
is no longer required
.htaccess
The Content-disposition headers may need to be set in order to make downloads work properly in IE. So.htaccess
can look like:
<FilesMatch "\.(?i:csv|txt)$"> ForceType application/octet-stream Header set Content-Disposition attachment </FilesMatch>
Setup Example (php)
Thanks to TheSin- for sharing this setup which includes the necessary php to allow file download with the proper filename and extension (original Gist)
Rowspan and colspan
- Even though tablesorter does not currently support
rowspan
andcolspan
within the tbody (except in child rows), this widget does support them. - When the widget encounters a
colspan
:- The colspan will be processed such that the data will be applied to each cell as if the colspan did not exist. So a header row that looks like this:
<th>data</th><th colspan="2">values</th>
will produce an output like this:data, values, values
- Important But, if a JSON output is chosen, the resulting object for a row cannot contain duplicate keys.
[{ "data" : "0", "values" : "1", "values" : "2" }] // becomes [{ "data" : "0", "values" : "2" }]
So, in order to fix this, any key (header name) with a colspan will have the column index added to the end (see theoutput_callbackJSON
option). So the same HTML above will produce the following output:[{ "data" : "0", "values" : "1", "values(2)" : "2" }]
- The colspan will be processed such that the data will be applied to each cell as if the colspan did not exist. So a header row that looks like this:
- When the widget encounters a
rowspan
:- The rowspan will be processed such that the data will be applied to each cell as if the rowspan did not exist. So if two header rows looks like this:
<tr> <th rowspan="2">line</th> <th colspan="3">values</th> </tr> <tr> <th>value1</th> <th>value2</th> <th>value3</th> </tr>
And theoutput_headerRows
istrue
, the output will look like this:line,values,values,values line,value1,value2,value3 1,1.1,1.2,1.3 1,1.4,1.5,1.5
-
Important But, if a JSON output is chosen, and
output_headerRows
is set tofalse
, only header names from the last row will be applied to the output. The HTML above will produce this output:
[ { "line" : "1", "value1" : "1.1", "value2" : "1.2", "value3" : "1.3" }, { "line" : "1", "value1" : "1.4", "value2" : "1.5", "value3" : "1.5" } ]
If theoutput_headerRows
is set totrue
, the header names from the second row will be applied to alternating rows and the header with acolspan
will get uniques names using theoutput_callbackJSON
option. So the same HTML above will produce the following output:[ { "line" : "1", "values" : "1.1", "values(2)" : "1.2", "values(3)" : "1.3" }, { "line" : "1", "value1" : "1.4", "value2" : "1.5", "value3" : "1.5" } ]
- The rowspan will be processed such that the data will be applied to each cell as if the rowspan did not exist. So if two header rows looks like this:
Options
Output widget default options (added inside of tablesorter widgetOptions
)
TIP! Click on the link in the option column to reveal full details (or toggle|show|hide all) or double click to update the browser location.
Option | Default | Description |
---|---|---|
output_separator | ',' |
This option allows you to set the output as JSON, Array, or change the separator between cell data with text output:
When the output is created, and it this option doesn't match either "json" or "array" , each block of table cell data will be separated by this setting.This is the result with this option set to "," and with the table filtered with Rank :
Rank,First,Last,Age,Total,Discount,Date 111,Peter,Parker,28,$9.99,20%,"Jul 6, 2006 8:14 AM" 166,Bruce Lee,Evans,22,$13.19,11%,"Jan 18, 2007 9:12 AM"When this option is set to "array" , this will be the resulting output:
[ [ "Rank", "First", "Last", "Age", "Total", "Discount", "Date" ], [ "111", "Peter", "Parker", "28", "$9.99", "20%", "Jul 6, 2006 8:14 AM" ], [ "166", "Bruce Lee", "Evans", "22", "$13.19", "11%", "Jan 18, 2007 9:12 AM" ], ]Note this requires JSON.stringify , or the result will be a flattened array.And when this option is set to "json" , the resulting output will be a valid JSON format:[ { "Rank" : "111", "First": "Peter", "Last": "Parker", "Age": "28", "Total": "$9.99", "Discount": "20%", "Date": "Jul 6, 2006 8:14 AM" }, { "Rank": "166", "First": "Bruce Lee", "Last": "Evans", "Age": "22", "Total": "$13.19", "Discount": "11%", "Date": "Jan 18, 2007 9:12 AM" } ]Note this also requires JSON.stringify , or the result will show [ [object Object], ... ] in the output.
|
output_ignoreColumns | [ ] |
Add the zero-based column index to this array to ignore specific columns (v2.17.0)
For example, to use this option to hide the first column, set it as follows: output_ignoreColumns : [ 0 ] Note This option will work properly with tables that contain rowspans & colspans. |
output_includeFooter | false |
Change this option to true to include the <tfoot> rows in the output (v2.21.0)
|
output_dataAttrib | 'data-name' |
This option allows you to override any table cell (thead or tbody ) text with the contents of this data-attribute (v2.22.2)
In the below example, the header text is obtained from this set data-attribute. If the data-attribute doesn't exist, then the header name is obtained from the actual header text. The data-attribute can be an empty string (v2.22.2). <thead> <tr> <th>Rank</th> <th data-name="First">First Name</th> <th data-name="Last">Last Name</th> <th>Age</th> <th>Total</th> <th>Discount</th> <th>Date</th> </tr> </thead> Notice in this output that the "First" and "Last" columns match the contents of the Rank,First,Last,Age,Total,Discount,Date* NOTE * The core plugin uses the data-text attribute for text extraction. If you want to use the same data for both, make the data-attributes match!
|
output_headerRows | false |
Setting this option to true will include all header rows while processing a JSON output.
If this option is set to false , only the last row of the table header will be used as a key names for the tbody values; this does assume that the last table row in the header contains all of the header cell names & does not contain any colspan .
|
output_delivery | 'popup' |
Change this option to either 'popup' or 'download' to set the destination of the output.
When setting this option, only the first letter is required ( 'p' or 'd' ) :
output_delivery : 'p' |
output_saveRows | 'filtered' |
Change this option to either 'filtered' , 'visible' , 'all' , a jQuery filter selector (v2.25.1) to set to match rows to be added to the output, or a jQuery filter callback function (v2.25.2).
Even if this option is set to *NOTE* When setting this option,
|
output_duplicateSpans | true |
When true , colspan & rowspan content is duplicated in the output
By default, any tbody cells that are included in the colspan or rowspan will have the cell's content duplicated in the output. When set to false , the cells within the colspan or rowspan will be empty.Here is an example of the second table output with this option set to false :
line,values,values,values line,value1,value2,value3 1,1.1,1.2,1.3 ,1.4,1.5, 2,2.1,2.2,2.3 ,2.4,2.5, 3,3.1,3.2,3.3 ,3.4,3.5, 4,4.1,,4.2 ,,,4.3This option does not affect thead cells, they will always have duplicated content. |
output_replaceQuote | '\u201c;' |
When a table cell contains a quote, it needs to be modified to differentiate it from cell content that is wrapped in quotes.
Quotes are necessary to maintain the integrity of the output data when any cell content contains either the separator or carriage returns. In order to do this, this widget replaces any quotes within cell content with this character. By default, this replacement character is a left double quote ( “ , shown as it's unicode equivalent '\u201c;' ).
output_replaceQuote : '\u201c;' // left double quoteIn the demo below, additional examples of a single quote ( ' ) and escaped double quote (\" ) are added as selectable buttons.
Rank,First,Last,Age,Total,Discount,Date 1,Philip Aaron Wong,Johnson Sr Esq,25,$5.95,22%,"Jun 26, 2004 7:22 AM" 21,John,“Robin“\n\tHood,33,$19.99,25%,"Dec 10, 2002 5:14 AM" 013,Clark,“Old man“ Kent Sr.,18,$15.89,44%,"Jan 12, 2003 11:14 AM" 16,Jim,“Jimmy“ Franco,24,-$14.19,24%,"Jan 14, 2004 11:23 AM" 55,Dennis,“Charley“ Bronson,65,$123.00,32%,"Jan 20, 2001 1:12 PM" |
output_includeHTML | false |
This option, if true tells the widget to include any HTML within the table cells.
Only cells within the table body will include HTML. The table header has a lot of extra markup for the sorting arrows, so it is automatically stripped of HTML. |
output_trimSpaces | true |
This option, if true tells the widget to remove any leading and trailing (white)space characters
Leading and trailing whitespace characters include newlines, spaces, non-breaking spaces and tabs. Any of these whitespace characters in the middle of the table cell will always be preserved. *NOTE* carriage returns in the middle of the table cell content will be stripped out if this option is set to true .
|
output_wrapQuotes | false |
This option, if true wrap the output of all table cell content in quotes.
This is the output of the widget when the age column is filtered for results in the range . "Rank","First","Last","Age","Total","Discount","Date" "1","Philip Aaron Wong","Johnson Sr Esq","25","$5.95","22%","Jun 26, 2004 7:22 AM" "111","Peter","Parker","28","$9.99","20%","Jul 6, 2006 8:14 AM" "21","John","'Robin'\n\tHood","33","$19.99","25%","Dec 10, 2002 5:14 AM" "9","Martha","delFuego","25","$22.09","12%","Jun 11, 2011 10:55 AM"Notice that every block of data is wrapped in a quote. When this option is false , only blocks that contain a newline or separator (comma, by default) will be wrapped in quotes. Here is the same data set without this option set:
Rank,First,Last,Age,Total,Discount,Date 1,Philip Aaron Wong,Johnson Sr Esq,25,$5.95,22%,"Jun 26, 2004 7:22 AM" 111,Peter,Parker,28,$9.99,20%,"Jul 6, 2006 8:14 AM" 21,John,'Robin'\n\tHood,33,$19.99,25%,"Dec 10, 2002 5:14 AM" 9,Martha,delFuego,25,$22.09,12%,"Jun 11, 2011 10:55 AM"Only the dates, which contain commas, are wrapped in quotes. |
output_popupStyle | 'width=500,height=300' |
If the data is sent to a popup window, the features set by this option are applied (do not include any spaces).
Set the desired popup window features within this string. For a full list of features, please refer to the Mozilla Developer Network: Window.open documentation page (look for strWindowFeatures parameters).The <textarea> within the popup window is set with 100% width and height.
|
output_saveFileName | 'mytable.csv' |
When downloading, this option sets the filename of the output. |
output_formatContent | null | This callback is executed after the content of a table cell has been processed.
Default setting & how to use this option: output_formatContent : function( c, wo, data ) { // data.isHeader (boolean) = true if processing a header cell // data.$cell = jQuery object of the cell currently being processed // data.content = processed cell content (spaces trimmed, quotes added/replaced, etc) // ********** // use data.$cell.html() to get the original cell content return data.content .replace(/fred/ig, '') // because we don't like fred // because HTML is being processed, you might want to also replace HTML codes .replace(/&/g, '&') // convert '&' → '&' }If you want to replace all HTML codes, check out the he library; then you can use this code (Fred would be happy): output_formatContent : function( c, wo, data ) { // replace all HTML shortcut codes // (e.g. 'foo © bar ≠ baz 𝌆 qux' → 'foo © bar ≠ baz 𝌆 qux' ) return he.decode( data.content ); } |
output_callback | {see description} | Return true or modified data in this callback to continue the download or open the popup (v2.25.1).
In v2.27.0, a url parameter was added to the callback. In v2.25.1, this callback can return modified data for output. As of v2.17.0 (v2.27.0) , the callback function was modified to pass
function(config, data, url){ // return data.replace( /Mary Smith/g, 'Mary Smith-Jones' ); // v2.25.1+ return true; }After table processing has completed, this callback function is exectued. If true is not returned, the processed data will not open a popup, nor download the data.
output_callback : function(config, data, url) { // send output to the console only console.log(data); return false; }If you are using the pager and want to provide the entire table in the output, use this callback as follows: function(config, data, url) { // This is only an example, but you could set it up so that a "&csv=1" // parameter in the url to signal the server to provide the csv for the // entire table using the current filters, sort, etc. if (url) { return $.getJSON(url + "&csv=1") .done(function(data){ return data.csv; }) .fail(function() { alert('no go on CSV'); return false; }); } return true; } |
output_callbackJSON | {see description} | JSON callback executed when a colspan is encountered in the header.
Default setting & how to use this option: output_callbackJSON : function($cell, txt, cellIndex) { return txt + '(' + (cellIndex + col) + ')'; }For more details on why this option is necessary, see the "Rowspan and colspan" section above. |
output_encoding | {see description} | Default encoding setting (2.16.4; 2.17.5)
As of 2.17.5, this option no longer needs to be modified to specifically make this widget download files that will work in Excel. The method used to download has been completely changed. The downloads still need an encoding setting, but this option is now set to a default of output_encoding : 'data:application/octet-stream;charset=utf8,' The information below is no longer relavant:
With the default settings (utf-8 no BOM), Excel does not properly encode accented characters unless the csv file is imported. Depending on the characters used, there are various methods which will allow proper encoding, but no one method is ideal. So this option can be set to allow the user to try different encodings. Set it as follows:
// output data type (with BOM or Windows-1252 is needed for excel) // NO BOM : 'data:text/csv;charset=utf8,' // With BOM : 'data:text/csv;charset=utf8,%EF%BB%BF' // WIN 1252 : 'data:text/csv;charset=windows-1252,' // ANSI (subset of ISO-8859-1) output_encoding : 'data:text/csv;charset=utf8,'Note The commas are important! |
$.tablesorter.output.replaceCR = '\x0d\x0a'; $.tablesorter.output.replaceTab = '\x09';
Demo
Search in the Discount column
Table showing filter & pager support
Rank | First Name | Last Name | Age | Total | Discount | Date | |
---|---|---|---|---|---|---|---|
Rank | First Name | Last Name | Age | Total | Discount | Date | |
1 | Philip Aaron Wong | Johnson Sr Esq | 25 | $5.95 | 22% | Jun 26, 2004 7:22 AM | |
11 | Aaron | "doc" Hibert | 12 | $2.99 | 5% | Aug 21, 2009 12:21 PM | |
12 | Brandon Clark | Henry Jr | 51 | $42.29 | 18% | Oct 13, 2000 1:15 PM | |
111 | Peter | Parker | 28 | $9.99 | 20% | Jul 6, 2006 8:14 AM | |
21 | John | "Robin" Hood | 33 | $19.99 | 25% | Dec 10, 2002 5:14 AM | |
013 | Clark | "Old man" Kent Sr. | 18 | $15.89 | 44% | Jan 12, 2003 11:14 AM | |
005 | Bruce | Almighty Esq | 45 | $153.19 | 44% | Jan 18, 2021 9:12 AM | |
10 | Alex | Dumass | 13 | $5.29 | 4% | Jan 8, 2012 5:11 PM | |
16 | Jim | "Jimmy" Franco | 24 | -$14.19 | 24% | Jan 14, 2004 11:23 AM | |
166 | Bruce Lee | Evans | 22 | $13.19 | 11% | Jan 18, 2007 9:12 AM | |
100 | Brenda Dexter | McMasters | 18 | $55.20 | 15% | Feb 12, 2010 7:23 PM | |
55 | Dennis | "Charley" Bronson | 65 | $123.00 | 32% | Jan 20, 2001 1:12 PM | |
9 | Martha | delFuego | 25 | $22.09 | 12% | Jun 11, 2011 10:55 AM |
Table showing output widget rowspan & colspan support
line | values | ||
---|---|---|---|
value1 | value2 | value3 | |
1 | 1.1 | 1.2 | 1.3 |
1.4 | 1.5 | ||
2 | 2.1 | 2.2 | 2.3 |
2.4 | 2.5 | ||
3 | 3.1 | 3.2 | 3.3 |
3.4 | 3.5 | ||
4 | 4.1 | 4.2 | |
4.3 |