Stupid-table-plugin

A stupidly small and simple jQuery table sorter plugin

View the Project on GitHub joequery/Stupid-Table-Plugin

Stupid jQuery Table Sort

This is a stupidly simple, absurdly lightweight jQuery table sorting plugin. As long as you understand basic JavaScript sorting, you can make this plugin do as much or as little as you want.

Table of Contents

Philosophy

Most table sorting plugins try to account for a limitless number of data types and their limitless ways of being presented. This leads to an extremely bloated code base with only a tiny portion of the code ever used by your project.

This plugin avoids that issue by letting you define your own ways of sorting table columns. The plugin internally recognizes "int", "string", "string-ins" (case-insensitive) and "float", so simple data tables will take very little effort on your part. See the README for more details.

Basic usage

Here's a simple example. Click a header to sort the table by that column.

int float string
15 -.18 banana
95 36 coke
2 -152.5 apple
-53 88.5 zebra
195 -858 orange
This is achieved with the following JS
  $("#simpleTable").stupidtable();
And the following HTML
<table id="simpleTable">
    <thead>
        <tr>
        <th data-sort="int">int</th>
        <th data-sort="float">float</th>
        <th data-sort="string">string</th>
        </tr>
    </thead>
    <tbody>
  ...
  ... (rest of the table)

Custom sorts

Here is a slightly more complex table, which implements a custom sort on the Date column.

int float string Can't sort me! date Letter frequency
15 -.18 banana arbitrary Mar 15, 1986E
95 36 pointless Feb 27, 2086T
2 -152.5 silly Aug 07, 2004A
-53 88.5 hello eccentric Sep 15, 2002O
195 -858 orange garbage Mar 15, 1986I

Here's how we created a sort function to sort dates in the format seen in the example above.

JS
var date_from_string = function(str){
    var months = ["jan","feb","mar","apr","may","jun","jul",
    "aug","sep","oct","nov","dec"];
    var pattern = "^([a-zA-Z]{3})\\s*(\\d{2}),\\s*(\\d{4})$";
    var re = new RegExp(pattern);
    var DateParts = re.exec(str).slice(1);

    var Year = DateParts[2];
    var Month = $.inArray(DateParts[0].toLowerCase(), months);
    var Day = DateParts[1];
    return new Date(Year, Month, Day);
}

var table = $("#complexTable").stupidtable({
    "date":function(a,b){
        // Get these into date objects for comparison.
        aDate = date_from_string(a);
        bDate = date_from_string(b);

        return aDate - bDate;
    }
});
HTML
<table id="complexTable">
  <thead>
    <tr>
      <th data-sort="int" >int</th>
      <th data-sort="float">float</th>
      <th data-sort="string">string</th>
      <th>Can't sort me!</th>
      <th data-sort="date">date</th>
      <th data-sort="int">Letter frequency</th>
    </tr>
  </thead>
  ...
  ... (rest of the table)

Machine-friendly sort values vs Human-friendly display values

However, we can sometimes avoid the need for a custom sort by providing a machine-friendly sort value to the Stupid Table while displaying a human-friendly form of the sort value to the user.

Consider the Date custom sort we built above: If a server-side process generates the table, the process probably uses some strftime() function to get dates to appear that way. This means we should also have access to the timestamp. It is much easier to perform an integer sort on the timestamp as opposed to parsing the date string out into the components necessary for the Date() JavaScript constructor!

Using data-sort-value="myvalue" on a table cell tells Stupid Table to use "myvalue" as the basis of the sort instead of the contents of the cell. So to apply our example, we should

  1. Tell Stupid Table the Date column will be an integer type
  2. Pass the timestamp of the date to data-sort-value on the table cell
  3. Pass the formatted date into the contents of the table cell
The end result looks like

<th data-sort="int">Date</th>
...
...
<td data-sort-value="1335798463">Apr 30, 2012</td>

Callbacks

The complex table above uses a custom callback to add an arrow to the table headers after the table is sorted. To execute a callback after the table is sorted, bind on the 'aftertablesort' event. Here's how the arrow effect was achieved:

var table = $("#complexTable").stupidtable({
    // Sort functions here
});

table.bind('aftertablesort', function (event, data) {
    // data.column - the index of the column sorted after a click
    // data.direction - the sorting direction (either asc or desc)

    var th = $(this).find("th");
    th.find(".arrow").remove();
    var arrow = data.direction === "asc" ? "↑" : "↓";
    th.eq(data.column).append('<span class="arrow">' + arrow +'</span>');
});

Similarly, you can also bind on 'beforetablesort' to execute a callback before the sort actually takes place when a column is clicked.

More examples