tablesorter

Internally, all triggered events use jQuery's triggerHandler method to get around the issue of events triggered on a nested table bubbling up to the parent table; e.g. we don't want a "sortEnd" event to trigger on a parent table when a nested table has completed sorting.

To add an event listener to a table created by the build widget, you will need to use the initialized callback:

<!-- empty wrapper before the table has been built -->
<div id="wrapper"></div>

$(function() {
  $('#wrapper').tablesorter({
    theme: 'blue',
    widgets: ['zebra'],
    data : dataObject,
    initialized: function(table) {
      $(table).on('sortStart', function() {
        alert('ok');
      });
    }
  });
});

<div id="wrapper">
  <table class="tablesorter-blue">
    <!-- ... -->
  </table>
</div>

<!-- jQuery -->
<script src="js/jquery-latest.min.js"></script>

<!-- Tablesorter: required -->
<link rel="stylesheet" href="../css/theme.blue.css"> <!-- choose any theme -->
<script src="../js/jquery.tablesorter.js"></script>

<!-- build table widget -->
<script type="text/javascript" src="../js/widgets/widget-build-table.js"></script>

Notes

• The array is set up such that it is an array of arrays. The outer array contains each row array, and within each row array is the cell text.
• Using an array is limiting, so addtional options have been added:
  • (build_headers & build_footers) have been added allowing customizing the headers and/or footers.
  • The rows option sets the number of headers rows to include from the data source. Zero is not an option since tablesorter requires a thead in place before it will initialize.
  • The classes array sets each header cell (th) class name.
  • The text array within these options will override any text obtained from the data source.
  • The widths array, only in the build_headers option, sets column widths by building <col> elements within a <colgroup.
  • Adding class names to the tbody rows or cells isn't easily accomplished, but you can bind to the build complete event ('tablesorter-build-complete') and add them yourself.

HTML

<div id="array2Table"></div>

Javascript

$(function() {
  var arry = [
    [ 'ID', 'Name', 'Age', 'Date' ], // header
    [ 'A42b', 'Parker', 28, 'Jul 6, 2006 8:14 AM' ],  // row 1
    [ 'A255', 'Hood', 33, 'Dec 10, 2002 5:14 AM' ],   // row 2
    [ 'A33', 'Kent', 18, 'Jan 12, 2003 11:14 AM' ],   // row 3
    [ 'A1', 'Franklin', 45, 'Jan 18, 2001 9:12 AM' ], // row 4
    [ 'A102', 'Evans', 22, 'Jan 18, 2007 9:12 AM' ],  // row 5
    [ 'A42a', 'Everet', 22, 'Jan 18, 2007 9:12 AM' ], // row 6
    [ 'ID', 'Name', 'Age', 'Date' ]  // footer
  ];

  $('#array2Table').tablesorter({
    theme: 'blue',
    widgets: ['zebra'],
    widgetOptions : {
      // build_type   : 'array', // can sometimes be detected if undefined
      build_source : arry,
      build_headers : {
        rows    : 1,  // Number of header rows from the csv
        classes : [], // Header classes to apply to cells
        text    : [], // Header cell text
        widths  : [ '15%', '30%', '15%', '40%' ] // set header cell widths
      },
      build_footers : {
        rows    : 1,   // Number of header rows from the csv
        classes : [],  // Footer classes to apply to cells
        text    : [ 'ID (a###)', 'Last Name', 'Age (joined)', 'Date (joined)' ] // Footer cell text
      }
    }
  });
});

Result

Notes

• We start out with a string and split it into a useable array of arrays.
• The settings are similair to the Array (javascript variable) code above with the exception of using the build_processing function to create the array.
  • The string is set up to separate each row by a semi-colon, then each cell by a comma.
  • The first split is needed to create an array of rows .split(';')
  • The second split can be accomplished using .split(',') on each row of the array, but instead we use the build table widget function $.tablesorter.buildTable.splitCSV(cells, ','); to ensure that the split doesn't occur if the separator is within double quotes (note the footer text).
  • Then just return this newly built array back to the build table widget (see the full code below).

HTML

<div id="string2Table"></div>

Javascript

$(function() {
  $('#string2Table').tablesorter({
    theme: 'blue',
    widgets: ['zebra'],
    widgetOptions: {
      build_type   : 'array',
      build_source : 'header 1,header 2,header 3;r1c1,r1c2,r1c3;r2c1,r2c2,r2c3;r3c1,r3c2,r3c3;"footer, 1","footer, 2","footer, 3"',
      build_processing : function(data, wo) {
        var rows = data.split(';');
        return $.each(rows, function(i,cells) {
          // similar to using rows[i] = cells.split(',') but the splitCSV script
          // doesn't split the cell if the separator (comma) is within double quotes
          rows[i] = $.tablesorter.buildTable.splitCSV(cells, ',');
        });
      }
    }
  });
});

Result

Notes

• A jQuery object targeting the CSV text can be passed to the build_source option.
• The widget detects that a jQuery object was passed to it, and grabs the HTML (not text) of the element.
  • Make sure not include HTML tags, or at least use the build_processing function to reformat the data.
  • The row of csv data is trimmed of extra tabs and spaces (only from the beginning & end of each row).
  • Building a table from CSV or array use the same script, so the same addtional options are available:
    • (build_headers & build_footers) have been added allowing customizing the headers and/or footers.
    • The rows option sets the number of headers rows to include from the data source. Zero is not an option since tablesorter requires a thead in place before it will initialize.
    • The classes array sets each header cell (th) class name.
    • The text array within these options will override any text obtained from the data source.
    • The widths array, only in the build_headers option, sets column widths by building <col> elements within a <colgroup.
    • Adding class names to the tbody rows or cells isn't easily accomplished, but you can bind to the build complete event ('tablesorter-build-complete') and add them yourself.
  • CSV data has two additional options used during data processing:
    • build_csvStartLine (default is 0) tells the csv build script which line in the csv data to start using to build the table. This is added in case comments or other data is above the table data.
    • build_csvSeparator (default is ",")
      • This sets the separator used within the csv data to separate each cell.
      • The original jquerycsvtotable plugin shows an example to process tab separated values (TSV) by setting this option to "\t".
      • Rows are determined by placing the data on a new line.
  • In this demo, the build_numbers sub-options addColumn and sortable are set to add a numeric column on the left side.
    • The addColumn option contains the name of the numeric column to be added to the header. Otherwise, set this option to false to not build this numeric column.
    • The sortable option makes that numeric column sortable.

HTML

<!--
 Note: if the csv data contains commas ("10,000 days") wrap it in quotes
-->
<div class="csv" style="display:none;">
  Album,Artist,Price (USD)
  Lateralus,Tool,$13.00
  Aenima,Tool,$12.00
  "10,000 days",Tool,$14.00
  Down In It,Nine Inch Nails,$3.00
  Broken,Nine Inch Nails,$6.00
  Muse,Black Holes and Revelations,$7.00
  Anon,"fake album, with comma", $1.00
  Album,Artist,Price (USD)
</div>

<div id="csv2Table"></div>

Javascript

$(function() {
  $('#csv2Table').tablesorter({
    theme: 'blue',
    widgets: ['zebra'],
    widgetOptions: {
      // *** build widget core ***
      build_type      : 'csv',
      build_source    : $('.csv'),
      build_complete  : 'tablesorter-build-complete', // triggered event when build completes

      // *** CSV & array ***
      build_headers   : {
        rows    : 1,   // Number of header rows from the csv
        classes : [],  // Header classes to apply to cells
        text    : [],  // Header cell text
        widths  : ['3%', '27%', '50%', '20%'] // set header cell widths
      },
      build_footers : {
        rows    : 1,   // Number of header rows from the csv
        classes : [],  // Footer classes to apply to cells
        text    : []   // Footer cell text
      },
      build_numbers : {
        addColumn : "#", // include row numbering column?
        sortable  : true // make column sortable?
      },

      // *** CSV options ***
      build_csvStartLine : 0,  // line within the csv to start adding to table
      build_csvSeparator : "," // csv separator
    }
  });
});

Result

Notes

• If the csv data is obtained via ajax instead of from a DOM element, only the build_source option needs to change, everything else stays the same.
  • Set the build_source to contain any ajax settings required to load the data.
  • In this case the csv file is contained within a text file (build.txt), so a url option is set to point to the file and the dataType option (set to html) is set so that ajax knows the type of file to access.
  • The remaining default settings were left out of the example below.
• Please note that browsers like Chrome will not allow you to access locally hosted (desktop) files. Test it with Firefox instead.

Build.txt file

Album,Artist,Price ($)
Lateralus,Tool,$13.00
Aenima,Tool,$12.00
"10,000 days",Tool,$14.00
Down In It,Nine Inch Nails,$3.00
Broken,Nine Inch Nails,$6.00
Muse,Black Holes and Revelations,$7.00
Anon,"fake album, with comma", $1.00
Album,Artist,Price ($)

HTML

<div id="csv2Table2"></div>

Javascript

$(function() {
  $('#csv2Table2').tablesorter({
    theme: 'blue',
    widgets: ['zebra'],
    widgetOptions: {
      // *** build widget core ***
      build_type      : 'csv',
      build_source    : { url: 'assets/csv.txt', dataType: 'text' },
      build_headers   : {
        widths  : ['30%', '50%', '20%'] // set header cell widths
      }
    }
  });
});

Result

Notes

HTML

<div id="object2Table"></div>

Javascript

$(function() {
  // object or JSON
  var dataObject = {
    headers : [
      [
        // each object/string is a cell
        { text: 'First Name', class: 'fname', width: '10%' }, // row 0 cell 1
        'Last Name',                                          // row 0 cell 2
        { text: 'Age', class: 'age', 'data-sorter' : false }, // row 0 cell 3
        'Total',                                              // row 0 cell 4
        { text: 'Discount', class : 'sorter-false' },         // row 0 cell 5
        { text: 'Date', class : 'date' }                      // row 0 cell 6
      ]
    ],
    footers : 'clone', // clone headers or assign array like headers
    rows : [
      // TBODY 1
      [ 'Peter', 'Parker',   28, '$9.99',   '20%', 'Jul 6, 2006 8:14 AM'   ], // row 1
      [ 'John',  'Hood',     33, '$19.99',  '25%', 'Dec 10, 2002 5:14 AM'  ], // row 2
      [ 'Clark', 'Kent',     18, '$15.89',  '44%', 'Jan 12, 2003 11:14 AM' ], // row 3

      // TBODY 2
      { newTbody: true, class: 'tablesorter-infoOnly' },
      { cells : [ { html: '<strong>Info Row</strong>', colSpan: 6 } ] },      // row 4

      // TBODY 3
      { newTbody: true },
      [ 'Bruce', 'Evans',    22, '$13.19',  '11%', 'Jan 18, 2007 9:12 AM'  ], // row 5
      [ 'Bruce', 'Almighty', 45, '$153.19', '44%', 'Jan 18, 2001 9:12 AM'  ], // row 6

      { class: 'specialRow',                                                  // row 7
        cells: [
          // each object/string is a cell
          { text: 'Fred', class: 'fname' },                                   // row 7 cell 1
          { text: 'Smith', class: 'lname' },                                  // row 7 cell 2
          { text: 18, class: 'age', 'data-info': "fake ID!, he's only 16" },  // row 7 cell 3
          { text: '$22.44', class: 'total' },                                 // row 7 cell 4
          '8%',                                                               // row 7 cell 5
          { text: 'Aug 20, 2012 10:15 AM', class: 'date' }                    // row 7 cell 6
        ],
        'data-info' : 'This row likes turtles'
      }
    ]
  };

  $('#object2Table').tablesorter({
    theme: 'blue',
    widgets: ['zebra'],
    data : dataObject, // same as using build_source (build_source would override this)
    widgetOptions : {
      // *** build object options ***
      build_objectRowKey    : 'rows',    // object key containing table rows
      build_objectCellKey   : 'cells',   // object key containing table cells (within the rows object)
      build_objectHeaderKey : 'headers', // object key containing table headers
      build_objectFooterKey : 'footers'  // object key containing table footers
    }
  });

});

Result

Notes

• The important difference between this demo and the javascript variable demo above is that this one retrieves a JSON file:
  • Set the build_source option to contain any ajax settings to load the json.
  • To load the json file, set the url option to point to the json file and the dataType set to "json".
  • The remaining default settings were left out of the example below.
• Please see the "Object (javascript variable)" section above for more details on how to set up the JSON for this demo.
• Note that JSON formatting is very specific - only double quotes (") can be used to wrap attributes, all keys must be wrapped in quotes, no comments, etc.
• Always verify that the JSON is valid (use JSONLint) and realize that browsers like Chrome will not allow you to access locally hosted (desktop) JSON files. Test it with Firefox instead.

Javascript

$(function() {
  $('#object2Table2').tablesorter({
    theme: 'blue',
    widgets: ['zebra'],
    widgetOptions: {
      build_type   : 'json',
      build_source : { url: 'assets/build.json', dataType: 'json' }
    }
  });
});

Build.json file

{
  "headers": [
    [
      { "text": "First Name", "class": "fname", "width": "20%" },
      "Last Name",
      { "text": "Age", "class": "age", "data-sorter": false },
      "Total",
      { "text": "Discount", "class": "sorter-false" },
      { "text": "Date", "class": "date", "width": "20%" }
    ]
  ],
  "footers": "clone",
  "rows": [
    [ "Peter", "Parker", 28, "$9.99",  "20%", "Jul 6, 2006 8:14 AM"   ],
    [ "John",  "Hood",   33, "$19.99", "25%", "Dec 10, 2002 5:14 AM"  ],
    [ "Clark", "Kent",   18, "$15.89", "44%", "Jan 12, 2003 11:14 AM" ],

    { "newTbody": true, "class": "tablesorter-infoOnly" },
    { "cells": [ { "html": "<strong>JSON Info Row</strong>", "colspan": 6 } ] },

    { "newTbody": true },
    [ "Bruce", "Evans",    22, "$13.19",  "11%", "Jan 18, 2007 9:12 AM"  ],
    [ "Brice", "Almighty", 45, "$153.19", "44%", "Jan 18, 2001 9:12 AM"  ],

    { "class": "specialRow",
      "cells": [
        { "text": "Fred", "class": "fname" },
        { "text": "Smith", "class": "lname" },
        { "text": 18, "class": "age", "data-info": "fake ID!, he's only 16" },
        { "text": "$22.44", "class": "total" },
        "8%",
        { "text": "Aug 20, 2012 10:15 AM", "class": "date" }
      ],
      "data-info": "This row likes turtles"
    }
  ]
}

HTML (before)

<div id="object2Table2"></div>

HTML (after)

<div id="object2Table2">
  <table class="tablesorter tablesorter-blue" role="grid">
    <colgroup>
      <col style="width: 20%;">
      <col>
      <col>
      <col>
      <col>
      <col style="width: 20%;">
    </colgroup>
    <thead>
      <tr>
        <th class="fname">First Name</th>
        <th>Last Name</th>
        <th class="age" data-sorter="false">Age</th>
        <th>Total</th>
        <th class="sorter-false">Discount</th>
        <th class="date">Date</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Peter</td>
        <td>Parker</td>
        <td>28</td>
        <td>$9.99</td>
        <td>20%</td>
        <td>Jul 6, 2006 8:14 AM</td>
      </tr>
      <tr>
        <td>John</td>
        <td>Hood</td>
        <td>33</td>
        <td>$19.99</td>
        <td>25%</td>
        <td>Dec 10, 2002 5:14 AM</td>
      </tr>
      <tr>
        <td>Clark</td>
        <td>Kent</td>
        <td>18</td>
        <td>$15.89</td>
        <td>44%</td>
        <td>Jan 12, 2003 11:14 AM</td>
      </tr>
    </tbody>
    <tbody class="tablesorter-infoOnly">
      <tr>
        <td colspan="6">
          <strong>JSON Info Row</strong>
        </td>
      </tr>
    </tbody>
    <tbody>
      <tr>
        <td>Bruce</td>
        <td>Evans</td>
        <td>22</td>
        <td>$13.19</td>
        <td>11%</td>
        <td>Jan 18, 2007 9:12 AM</td>
      </tr>
      <tr>
        <td>Brice</td>
        <td>Almighty</td>
        <td>45</td>
        <td>$153.19</td>
        <td>44%</td>
        <td>Jan 18, 2001 9:12 AM</td>
      </tr>
      <tr class="specialRow" data-info="This row likes turtles">
        <td class="fname">Fred</td>
        <td class="lname">Smith</td>
        <td class="age" data-info="fake ID!, he's only 16">18</td>
        <td class="total">$22.44</td>
        <td>8%</td>
        <td class="date">Aug 20, 2012 10:15 AM</td>
      </tr>
    </tbody>
    <tfoot>
      <tr>
        <th class="fname">First Name</th>
        <th>Last Name</th>
        <th class="age" data-sorter="false">Age</th>
        <th>Total</th>
        <th class="sorter-false">Discount</th>
        <th class="date">Date</th>
      </tr>
    </tfoot>
  </table>
</div>

Result