Ordering plug-in development

DataTables has built in support to correctly order the most common data types that are displayed in a table, but there will still be times when you find you have data that is not orders as you might expect. One option is to use orthogonal data so data that DataTables understands is used for ordering (for example a date might be given as an integer timestamp rather than a formatted string). Another option is to use an ordering plug-in.

An ordering plug-in provides DataTables with the code required to be able to sort any arbitrary data type. For example you might have file sizes with their postfix operators (MB, KB, etc) or an enum of options that you want to order in a particular way.

What ordering function DataTables uses for a particular column of data is defined thought use of the columns.type option. This is automatically detected by default (type detection plug-ins can also be written), but you can manually specify what the data type is to use your plug-in.

Plug-ins are defined by attaching the sorting functions to the DataTable.ext.type.order object. Three functions can be specified:

• {type}-pre - Pre-deformatting method. Used to convert the formatted data into orderable data
• {type}-asc - Ascending ordering method
• {type}-desc - Descending ordering method

Pre-deformatting

Typically you will need to define only a -pre method. This function is executed on each data point to be ordered before the ordering actually occurs, allowing the data to be formatted into something that can be ordered using Javascript's built-in Array.prototype.sort(). It takes a single argument (the data) and the return value should be the de-formatted data.

For example, consider the following:

DataTable.ext.type.order['file-size-pre'] = function ( data ) {
    var units = data.replace( /[\d\.]/g, '' ).toLowerCase();
    var multiplier = 1;

    if ( units === 'kb' ) {
        multiplier = 1000;
    }
    else if ( units === 'mb' ) {
        multiplier = 1000000;
    }
    else if ( units === 'gb' ) {
        multiplier = 1000000000;
    }

    return parseFloat( data ) * multiplier;
};

With the columns.type option set to file-size, data such as "11GB, 200KB, etc" will now be ordered correctly.

Custom ascending / descending methods

Should you wish to provide custom ordering methods for ascending and descending functions, they take exactly the same form as an array compare function for Array.prototype.sort().

Note that in DataTables 1.10 a pre-formatter cannot be used with custom -asc and -desc methods - to use custom ordering functions you cannot apply a pre-formatter. This limitation will be addressed in the next major version of DataTables.

For example you might have:

function format ( a ) {
    var units = data.replace( /[\d\.]/g, '' ).toLowerCase();
    var multiplier = 1;

    if ( units === 'kb' ) {
        multiplier = 1000;
    }
    else if ( units === 'mb' ) {
        multiplier = 1000000;
    }
    else if ( units === 'gb' ) {
        multiplier = 1000000000;
    }

    return parseFloat( data ) * multiplier;
}

$.extend( DataTable.ext.type.order, {
    "file-size-asc": function ( a, b ) {
        a = format( a );
        b = format( b );
        return ((a < b) ? -1 : ((a > b) ? 1 : 0));
    },
 
    "file-size-desc": function ( a, b ) {
        a = format( a );
        b = format( b );
        return ((a < b) ? 1 : ((a > b) ? -1 : 0));
    }
} );

Existing plug-ins

You might find that another DataTables user has already created a plug-in that matched your requirements. Plug-ins are published on this site and also available on the DataTables CDN.

Publish your plug-in

If you create an ordering plug-in for DataTables, please let us know!. Others will likely benefit for your plug-in and I (and the community as a whole) will be very grateful for your contribution.