Sortable tables

Ask a question Design guidelines

Summary

Sortable Tables adds on to the core Tables component, allowing the table to be sorted by the header row. Some custom sorting options are available.

Status

API status: general
Web resource key: com.atlassian.auiplugin:aui-table-sortable
AMD Module key: N/A
Experimental API: 5.1
General API: 5.8

Examples

Issue key
Name
Age
Description
TEST-12 Cannot sort tables 2 Table sorting should be allowed
WIN-87 Issue Page doesn't load in IE 7 When loading issue page on IE it doesn't show
DRINK-7 Vending Machine is empty 1 Blocker

Code

Setup

To make a table sortable, you must add the aui and aui-table-sortable CSS classes to the table and also define the <thead> of the table.

Sortable Tables are determined at page load, so if a table is added to the DOM after page load then it must be declared as sortable in your own code.

Default sorting behaviour

Sortable tables attempt to automatically detect the best sorting method for a given column. The sorting method can be explicitly set by adding a CSS class to a column's th element. Most of the sorting methods are provided by the jQuery tablesorter plugin. Some custom sorting methods provided by AUI include:

  • aui-table-column-issue-key: Sorts JIRA issue keys so that they are in the correct ordering by project and then by issue id.
  • aui-table-column-unsortable: Disallows any sorting of this column.
Demo code
AخA
 
<table class="aui aui-table-sortable">
    <thead>
        <tr>
            <th class="aui-table-column-issue-key">Issue key</th>
            <th>Name</th>
            <th>Age</th>
            <th class="aui-table-column-unsortable">Description</th>
        <tr>
    </thead>
    <tbody>
        <tr>
            <td>TEST-12</td>
            <td>Cannot sort tables</td>
            <td>2</td>
            <td>Table sorting should be allowed</td>
        </tr>
        <tr>
            <td>WIN-87</td>
            <td>Issue Page doesn't load in IE</td>
            <td>7</td>
            <td>When loading issue page on IE it doesn't show</td>
        </tr>
        <tr>
            <td>DRINK-7</td>
            <td>Vending Machine is empty</td>
            <td>1</td>
            <td>Blocker</td>
        </tr>
    </tbody>
</table>

Custom sorting behaviour

Through the jQuery tablesorter plugin API, it is possible to define your own sorting behaviour. The following is an example of how you might order a "Priority" column using a non-alphabetical sort order.

Demo code
Result
Issue key
Priority
Last updated
Summary
TEST-12 High Table sorting should be allowed
WIN-87 Blocker Issue Page doesn't load in IE
DRINK-7 Low Vending Machine is empty
TEST-7 Medium My hovercraft is full of eels
​x
 
<table id="custom-parser-example" class="aui aui-table-sortable">
    <thead>
    <tr>
        <th class="aui-table-column-issue-key">Issue key</th>
        <th class="sorter-priority">Priority</th>
        <th>Last updated</th>
        <th>Summary</th>
    <tr>
    </thead>
    <tbody>
    <tr>
        <td>TEST-12</td>
        <td>High</td>
        <td><time datetime="2017-04-20T14:00Z0">April 20, 2017</time></td>
        <td>Table sorting should be allowed</td>
    </tr>
    <tr>
        <td>WIN-87</td>
        <td>Blocker</td>
        <td><time datetime="2018-04-23T11:30Z0">April 23, 2018</time></td>
        <td>Issue Page doesn't load in IE</td>
    </tr>
    <tr>
        <td>DRINK-7</td>
        <td>Low</td>
        <td><time datetime="2018-04-01T17:30Z0">April 1, 2018</time></td>
        <td>Vending Machine is empty</td>
    </tr>
    <tr>
        <td>TEST-7</td>
        <td>Medium</td>
        <td><time datetime="2018-01-11T09:30Z0">January 11, 2018</time></td>
        <td>My hovercraft is full of eels</td>
    </tr>
    </tbody>
​
</table>
 
(function() {
    var priorityMap = {
        'high': 3,
        'blocker': 5,
        'low': 1,
        'medium': 2
    };
​
    AJS.$.tablesorter.addParser({
        id: 'priority',
        is: function(nodeValue, table, cell) {
            return false;
        },
        format: function(nodeValue, table, cell) {
            var raw = (nodeValue || '').toLowerCase().trim();
            return priorityMap[raw] || -1;
        },
        type: 'numeric'
    });
​
    // Since we added a new sorter, but the table was added at page load,
    // we'll need to kick off the sorting again.
    AJS.$('#custom-parser-example').trigger('sort');
}());

JavaScript API

To set a table as sortable, you must pass a jQuery object for the table into the AJS.tablessortable.setTableSortable function.

 
AJS.tablessortable.setTableSortable(AJS.$("#delayedSortedTable"));

Assigning a table as sortable multiple times can result in undefined behavior. For example, if a sortable table is present on page load and then you assign it as sortable via the AJS.tablessortable.setTableSortable function, it is unlikely to work as expected.