Unobtrusive Table Sort Script (revisited)

My first free Sunday morning in what seems like an epoch produces a complete rewrite of the original (and by far most popular) lab experiment, the “Unobtrusive Table Sort Script”, that addresses speed issues present within version #1.

At a glance…

• Plays nicely with the JavaScript global namespace (the script creates and reuses only one JavaScript object)
• Multiple columns can be sorted at once by pressing Shift while selecting the columns using either the keyboard or mouse
• The new script sorts (on average – based on my very non-scientific calculations), 5 times faster than its predecessor
• The plug-in architecture makes writing custom sort functions a breeze
• The script can highlight both alternate rows and full columns on a table by table basis.
• Like its predecessor, the script is fully keyboard accessible
• The script can correctly determine a columns datatype should a datatype not be explicitly defined (datatypes determined are limited to numbers, text, currency values and dates)
• The script is smart enough not to sort columns containing identical data
• Sort routines can be initiated using JavaScript
• Tables can be automatically sorted on a column (or columns) of your choice, even in reverse order
• Before-sort and after-sort callback functions (or Object.methods) can be defined for individual tables

The Slowdown

The original script attempted to grab the inner text of every TD node within the column to be sorted, each and every time the sort routine was activated. This was an extremely processor intensive action and the main cause of slowdown during the sort of large tables. While a limited “cache” system was offered, it relied heavily on use of the JavaScript “in” operator, which is itself notoriously slow to process.

Speeding things up

The new script addresses these issues by creating and storing an internal representation of the parsed table data the very first time that one of the table’s sortable TH nodes is activated (a 2D matrix of the table data). The data stored within this internal object is then reused during each subsequent sort action. This means that there is a slight processing overhead the first time the sort is activated (as an internal representation of the table’s data has to be created) but subsequent sorts, on any of the table’s columns, are much faster than in the previous incarnation of the script.

A listing of sample sort times for a 100 row table can be located within the dynamic table creation demo.

Initiating the sort process using JavaScript

As it was an uncommonly-common request for the first version of the script, the abilty to initiate the sort using JavaScript has been integrated into the rewrite. To initiate a sort, call the following method:

  
 fdTableSort.jsWrapper(yourTableId, colNums); 
  
  

Passing in the id of the table to be sorted and either an Integer stipulating the position of a single column to be sorted, or an array stipulating a set of columns to be sorted i.e. the following JavaScript statement:

  
 fdTableSort.jsWrapper("salesTax", [0,1,4]); 
  
  

will initiate the sort routine on columns 0, 1 and 4 of the table with an id of “salesTax”. An example of initiating the sort routine in this way can be seen within the JavaScript initiated sort demo.

Please note, if a callback function has been defined, in this case, it is not called after the sort routine completes.

Sortable datatypes

The script can currently sort dates (dd-mm-yyyy, mm-dd-yyyy or yyyy-mm-dd formats accepted), currency values (£, $, €, ¥ and ¤), numbers/floats and finally, plain-text (sorted in a case-insensitive manner). Additionally, the character used as the date divider (i.e. the character that separates the date parts) can be “/”, “-”, “.” or “ “ (space).

A note on the date format

The script currently favours the American date format of “mm-dd-yyyy”. This is the first format that all dates are tested against during the data preparation phase, which means that European dates such as 10-08-2006 (i.e. the 10th August 2006) will be parsed as the 8th October 2006.

Should your dates be of the European format “dd-mm-yyyy”, add the class sortable-date-dmy to the TH node instead of the class sortable-date, this will tell the script to attempt to parse a DMY format date before attempting to parse a MDY format date.

A note on sorting numeric data

The sortNumeric method bundled with the source code is quite ruthless with the data passed to it. It will replace any character not valid for use within a floating point number and then attempt to parse a float from the result.

This means that the sortNumeric method can be used to sort all manner of numeric column data, for example; columns containing percentages e.g. -22%, 34.6% etc do not require a bespoke sort function in order to be sorted – giving the column the className sort-numeric will suffice.

Row and column highlighting

The script enables both row and column highlighting.

Zebra striping the table rows

Should the table be given the class rowstyle-something, each alternate table row is given the class something after the table has been sorted i.e giving the table a class of rowstyle-alternate will tell the script to give each alternate row the class alternate.

Highlighting the currently sorted column

Should the table be given the class of colstyle-something, each TD node within the sorted column is given the class something after the table has been sorted i.e giving the table the class colstyle-alternate will tell the script to give each TD node within the sorted column the class alternate.

Making any column sortable

To make any table column sortable, just give the associated table header (TH) tag the class sortable, the script will automatically determine the column datatype, make the entire table header clickable (and not just the text contained within) and create the appropriate up/down arrow within the header when clicked (using the ↑ & ↓ characters).

Forcing a columns sort algorithm

Should a column contain a mix of datatypes (or should you know the column datatype), it is advised that you explicitly set the sort algorithm by adding one of the following classNames to the associated table header (TH) tag: sortable-numeric, sortable-currency, sortable-text , sortable-date, sortable-date-dmy or sortable-keep (which keeps the row in it’s original order).

Sorting multiple columns

The script can now sort multiple columns. Just hold down the Shift key while selecting the columns to sort (either with the keyboard or with the mouse).

Forcing a column to “reverse sort” by default

Should you wish to sort a column in reverse order by default, just give the associated TH node the className favour-reverse (Note the English spelling of favour). The default reverse sort is only taken into consideration when sorting on a single column.

Stipulating custom sort functions

Should you wish to stipulate your own custom sort function, add the class sortable-yourCustomFunctionName to the table header (TH) tag; for example, adding the class sortable-myCustomSortFunction will tell the script to call a JavaScript function named myCustomSortFunction in order to sort that column’s data.

The name of your custom sort function may only contain letters (a-Z) and the underscore character. Function names containing other characters will not be recognised.

The function name has been limited in this way as it is defined within a className, which itself can only contain a subset of the full ASCII character set i.e. while “$” is a valid JavaScript function name, it is not a valid character to use within a className.

Available custom sort functions

A few custom sort functions have been written and made available for those who might need them. They currently include:

• A function to sort by IP address
• A function to sort English longhand date formats e.g. 12th April 2006
• A function to sort (English) dateTime e.g. 12th April 1992 at 13:44:23
• A function to sort twelve-hour timestamps e.g. 12:32a.m.
• A function to sort numbers stipulated in Scientific Notation e.g. -32.45 e 0.32
• A function to sort on fileSize i.e. 22kb, 3mb, 1.3gb
• A function to sort images on the value of their “src” attribute
• A function to sort alphaNumeric data e.g. a, b, 1a, 2d, 33.4z, -2.4s

The functions can now be seen in action on their own custom function demo page.

Preprocessing the column data

Should your custom sort function require more than just the inner text of the TD node or should you wish to keep your custom sort as fast as possible, it is necessary to write a complimentary “prepare data” function. This function is called just once, during the creation of the data object for the table. The function should have the same name as your custom sort function with “PrepareData” added to the end.

An example custom sort function

In order to write a custom sort function “sortImage” that sorts images within the table’s TD cells using the value of their “src” attribute, two functions are required; “sortImage” and “sortImagePrepareData”.

The “sortImagePrepareData” function will be used to parse the image’s “src” attribute, which is then stored within the table’s data object to be used during the sort routine e.g.

    
  // Returns the "src" attribute of the first image 
  // "PrepareData" functions are passed both the TD node
  // and the TD node's inner text. In this case, we use the
  // tdNode and not the inner text.
  function sortImagePrepareData(tdNode, innerText) {
        var img = tdNode.getElementsByTagName('img');
        return img.length ? img[ 0 ].src : "";
  }
    
  

The “sortImage” function will then use this data during the sort i.e:

    
   // Uses the data prepared in “sortImagePrepareData”
  function sortImage(a, b) {
        // Get the data for the current column from the
        // two arrays passed in as arguments like so…
        var aa = a[fdTableSort.pos];
        var bb = b[fdTableSort.pos];

        // Sort the data 
        if(aa == bb) return 0;
        if(aa < bb)  return -1;
        return 1;
  }
   
  

The “PrepareData” functions are not obligatory and are only called by the script if they exist.

It is worthwhile to note though, that sort routines will be much faster whenever the column data has been parsed in advance by an associated “PrepareData” function.

A few more custom sort function examples (including the above “sortImage” function) can be viewed in the custom sort functions demo

Sorting the table automatically

The script will automatically sort any table that has been given the class sortable-onload-N immediately after the window.onload event fires – where N specifies a className of the form “-colNumber[ r ]” – with “colNumber” being replaced by the integer value of the column to sort and the optional “r” (remove the square brackets and spaces!) stipulating that the
column is to be sorted in reverse.

Multiple columns can be stipulated at once, for example, the classname sortable-onload-3r-4r-5 will automatically sort the table on column 4 (reverse sort), then column 5 (again, using a reverse sort) and finally, column 6.

Please note: the column index starts at 0 and not 1.

Preparing an already sorted column

If you have already sorted the table on a specific column or set of columns when the page is generated, it is necessary to indicate this to the script.

This can be done by adding the following className to the table sortable-onload-show-N, where N specifies a className of the form “-colNumber[ r ]” i.e. an identical className to the form discussed above.

This enables the script to create the appropriate up/down arrows within and set the appropriate className on the table headers without it having to actually sort the table data.

Zebra-striping the table

If you are not using the “sortable-onload-X” or “sortable-show-X” classNames but still want the table to be zebra-striped on page load, just give the table the className “onload-zebra”.

Indicating the sort is underway

Very large tables may take a while to sort which, without some sort of feedback, may leave users slightly bewildered as to why nothing seems to be happening after they have just clicked the table header.

To enable you to provide this feedback, both the page BODY and the TH node clicked by the user are temporarily assigned the class sort-active. This enables you to create appropriate styles that visually indicate to the user that the sort is underway (adding an animated gif to the background of the TH node for example). After the sort is complete, the class sort-active is removed from both the BODY and the TH nodes.

An example of using the sort-active className can be viewed within the Dynamic table creation demo – the currently active TH node displays an hourglass during the sort.

The callback functions

The script now includes the ability to call bespoke “callback” functions. The first function “sortInitiatedCallback()” is called immediately before the sort routine fires, the second function “sortCompleteCallback()” is called immediately after the sort routine completes. The two callback functions are passed the ID of the table as an argument.

Additionally, callBack functions can now be created for individual tables by creating a function named sortInitiatedCallbackXXX or sortCompleteCallbackXXX where XXX represents the ID of the table; for example, the script will attempt to call the function sortInitiatedCallbackTestTable and sortCompleteCallbackTestTable for a table with an ID of “TestTable”.

Stipulating Object.methods or bespoke JavaScript functions as a callback

You may wish to use an Object.method or a bespoke JavaScript function as a callback, to do this, just add one (or both) of the following class’s to the table’s className:

The className sortinitiatedcallback-XXX stipulates a function that will be called before the sort initiates, where XXX should be replaced with the name of the function in question.

Object.methods can be stipulated by converting the “dots” (i.e. the full-stops) to minus signs (-); for example, the className “sortinitiatedcallback-myObject-myMethod” will tell the script to call the “myMethod” method of the JavaScript Object “myObject” e.g. myObject.myMethod();

The className sortcompletecallback-XXX stipulates a function to be called after the sort has taken place. again, the XXX is replaced in an identical fashion to the XXX within sortinitiatedcallback-XXX.

Please Note: callback functions are only called should they exist so don’t fret about creating them should you not require the callback functionality.

An example of using a callback function can now be viewed within the callback function demo.

Creating your own progress indicator

Using callback functions in this way enables you to define your own progress indicator that appears whenever a sort is initiated and disappears when the sort completes.

Table pagination

As lots of people have been asking for the functionality, I’ve written a table pagination script that, as the name suggests, paginates tables automatically (i.e. splits large tables into smaller chunks). More information on the pagination script can be located within the article Client-Side Table Pagination Script.

Please Note: The pagination script does not rely on the tableSort script and can therefore be used independently of it.

Using images for the arrows

This version of the script enables images to be used in place of the arrows. The images should be defined within your CSS as follows:

    
   th.forwardSort
        {
        background:transparent url(your-down-arrow-image) no-repeat 0 0;
        }
  th.reverseSort
        {
        background:transparent url(your-up-arrow-image) no-repeat 0 0;
        }    
    
  

Additionally, the table should be given the class no-arrow which tells the script not to create the default arrow characters within the TH node.

Keeping things fast…

There are a few things that you can do to keep the script from slowing down:

1. Always stipulate the column datatype by using one of the explicit classNames sortable-date, sortable-date-dmy, sortable-numeric, sortable-currency, sortable-keep or sortable-text. Explicitly defining the datatype in this way means that the script does not have to try to deduce the column datatype and therefore saves many clock cycles during the initial data preparation phase.
2. Don’t use column highlighting on large tables as it takes time to grab the TD nodes and add or delete the appropriate class.
3. Write an associated “PrepareData” function for each of your bespoke sort functions.

A note for the Ajax’ers

Whenever you re-render a table (from an Ajax callback), just call the method fdTableSort.init, passing in the ID of the table that was just re-rendered. This will remove the original cached data object for the table in question and make sure an up-to-date version is created the first time the table is again sorted.

Calling the fdTableSort.init method with no arguments will clear all of the currently cached data objects and re-initialise all sortable tables.

Installing the script

Just add the following code within the HEAD section of your HTML document (remember to change the filepath to suit your installation):

    
 <script type="text/javascript" src="/the/path/to/tablesort.js"></script>
    
  

...and give both the TABLE and TH tags the required classNames (all classNames have been described within the article). Thats all there is too it.

The “table actions” plug-in

After countless requests, I’ve written a table actions plug-in to the script that enables zebra-striping, row selection and complex row, cell and column highlighting effects. More information can be found within the table actions post.

The License

The script is now released under a creative commons Attribution-ShareAlike 2.5 license. Should you use the script within a commercial context please think about clicking the payPal donate button – it’s certainly not an obligation but it would most certainly put a smile on my face.

Translations

An Italian translation of this article has been located at Consulente Informatico. Many thanks to Sergio Gandrus.

Demo, downloads and updates

Tested in Internet Explorer 6 & 7, Opera 9.01, Safari 3.0.3 (Windows) and Firefox 2.

View the table-sort demo, the custom sort functions demo page, the basic pagination demo, the sortCompleteCallback demo, the Dynamic table creation demo, the secondary/tertiary sort demo or download the uncompressed JavaScript source code (you can compress the script using Dean Edwards Packer if the size is an issue).

15/04/2008 (v4.9):

• Fixed a bug that didn’t zebra-stripe identical columns stipulated as “sortable-onload”

22/03/2008 (v4.8):

• Fixed a column highlighting bug

06/03/2008 (v4.7):

• Fixed a bug that stopped the hourglass showing during sorts

03/03/2008 (v4.6):

• Fixed a bug with the “sortable-onload-” functionality
• Integrated the “favour-reverse” functionality that means you can now stipulate that columns are to be sorted by default in reverse order
• Added the secondary/tertiary sort demo

01/02/2008 (v4.5):

• Changed the code to not remove child IMG nodes from sortable TH nodes

21/01/2008 (v4.4):

• zebra table support when the table className contains “onload-zebra”

27/12/2007 (v4.3):

• Embedded table support

19/12/2007 (v4.2):

• Added the ability to stipulate Object.methods as a callback function
• Better integration with the pagination script to remove the “flicker” present in previous versions as the pagination script redrew the table

14/12/2007 (v4.1):

• Added the ability to sort multiple columns onload
• Added the ability to “show” multiple presorted columns onload
• Changed the addClass and removeClass methods
• Separated the “redraw” code into it’s own method

15/11/2007 (v4.0):

• Fixed a Safari2 bug

23/10/2007 (v3.9):

• Added the “sortable-onload-show-N-reverse” functionality (thanks to Brett Harrison)

04/10/2007 (v3.8):

• Added the multi-column sort functionality
• Deprecated the sortDate method

28/05/2007 (v3.7):

• Fixed a bug that referenced getElementsByClassName and not getElementsByTagName

16/05/2007 (v3.6):

• Fixed a bug introduced within the last revision

05/04/2007 (v3.5):

• Fixed an identical column data bug

03/04/2007 (v3.4):

• Added a fix to support nested tables (Note: the solution requires that the parent table must have a tbody) – thanks to Chris for the fix

22/03/2007 (v3.3):

• Worked on Internet Explorer memory leaks
• Added code to correctly cleanup internal objects for the Ajax’ers

20/03/2007 (v3.2):

• Added a “sortable-keep” option
• Altered the jsWrapper function to not use the callback functions
• Unique callback functions can now be created for each table

02/03/2007 (v3.1):

• Fixed a bug in the parseDate method
• Removed a block of code that caused problems with dynamically created tables
• Fixed a few bugs in the custom sort functions

19/02/2007 (v3.0):

• Fixed a bug in the jsWrapper method
• Added rowspan support
• Many internal changes dealing with colspan & rowspan support

30/11/2006 (v2.9):

• Added the ability to have colspan’s within the non-sortable TH nodes
• Added a workaround for a Netscape 8.1.2. bug that crashed the browser when the script was initiated
• Added a disableTextSelection method that, not suprisingly, disables text selection on sortable TH nodes (in order to stop the browser highlighting the text within the node when the onclick event fires)

07/11/2006 (v2.8):

• Added the “automatic reverse sort” code.
• Changed the dateFormat function to accept a second parameter that tells the script to favour European d-m-y format dates
• The sortInitiated and sortComplete callback functions now get passed the ID of the table as an argument

02/11/2006 (v2.7):

• Changed the code to handle multiple TR’s within the table’s THEAD.
• Fixed an uppercase TFOOT reference

19/10/2006 (v2.6):

• Changed the license

12/10/2006 (v2.5):

• Fixed a bug when setting previously undefined classNames

04/10/2006 (v2.4):

• Altered the “prepareTableData” method to accept TD nodes that have no child nodes

02/10/2006 (v2.3):

• Altered the “prepareTableData” method to trim whitespace from the TD node’s innerText

18/09/2006 (v2.2):

• Fixed a bug within the sortNumeric method when sorting zero values

18/09/2006 (v2.1):

• Changed the sortNumeric method to be more robust
• Added a check to see if a TD node is a child of a TFOOT
• Changed the script to work with tables that have no THEAD or TBODY
• Rewrote the custom sort functions to adhere to the new “PrepareData” architecture