Tutorial: Sorting

Sorting

How the sorting works

If you want to sort data in your datasource array, you can simply invoke an Array.prototype.sort() function and call the render() function to refresh the table. You don't need any plugin for this. However, this operation alters the structure of the datasource, and in many cases you want to leave the datasource intact, while displaying its content in a specified order. Here's where column sorting plugin comes in handy.

Column sorting plugin works as a proxy between the datasource and the Handsontable rendering module. It can map indices of displayed rows (called visual indices) to the indices of corresponding rows in datasource (called physical indices) and vice versa. This way you can alter the order of rows which are being presented to user, without changing the datasource internal structure.

This simple mechanism gives you a lot of flexibility, but it also introduces a few pitfalls if the developer is not full aware of the way plugin works.

Sorting indicator

To enable a sorting indicator (an arrow down icon), you need to add a sortIndicator setting:

sortIndicator: true

Note, that you can enable this option for either the entire table (when setting it in the main config object) or for certain columns only (when using it in the columns array). The following example has this feature enabled.

How to enable the plugin

The property which is responsible for enabling and configuring the column sorting is called columnSorting (pretty unexpected, huh :P). The value of this property can be either a Boolean or an Object.

If the columnSorting is of type Boolean, then true means the plugin is enabled and false means the plugin is disabled. The important thing to remember is that enabling the plugin using true does not sort the table content right away. The table has to be sorted either by a user or programmatically.

If the columnSorting is an Object, then it means that the plugin is enabled and configured according to the properties passed in the configObject. The configObject can be used to set the initial sorting parameters, which are:

  • column : Number - this index of column, by which you want to sorter the table.
  • sortOrder : String - defines the order of sorting ('asc' for ascending, 'desc' for descending and 'none' for the original). This arguments is optional. If it's not specified, the default order is ascending.
  • sortEmptyCells : Boolean - defines if the empty cells should be taking part in the sorting process. If set to true, they'll be considered as a valid empty string (or the lowest value). If set to false, they'll be moved to the end of the table. This arguments is optional. If it's not specified, it defaults to false.

As all settings, columnSorting can be altered during the lifetime of a table, using updateSettings() method.

Examples:

// enables the plugin, but does not sort the table
var hot = new Handsontable(document.getElementById('example'), {
  columnSorting: true
});

// enables the plugin and sort the table by the values from the first column in ascending order
var hot = new Handsontable(document.getElementById('example'), {
  columnSorting: {
    column: 0
  }
});

// enables the plugin and sort the table by the values from the first column in descending order
var hot = new Handsontable(document.getElementById('example'), {
  columnSorting: {
    column: 0
    sortOrder: 'desc'
  }
});

// disable plugin
hot.updateSettings({
  columnSorting: false
});

How to determine if sorting has been performed

To check whether sorting has been performed for a particular Handsontable instance, use the plugin'sisSorted method.

hot.getPlugin('columnSorting').isSorted() ? doSomething() : doSomethingElse();

How to sort a table

There are 3 ways you can sort a table:

  • using columnSorting property
  • by clicking on the table header
  • invoking the plugin's sort() method

The first possibility has been discussed in How to enable the plugin section.

The second option is probably the most popular one. If the plugin is enabled, clicking on column header causes table to be sorted by the corresponding values in ascending order. As usual, if you click the header again, the order will switch to descending.

The last recommended way of sorting the table is using the plugin's sort() method. The method accepts 2 arguments: column and order.

  • column : Number - argument is the index of column, by which you want to sorter the table. This argument is required.
  • order : String - defines the order of sorting ('asc' for ascending, 'desc' for descending and 'none' for the original). This arguments is optional. If it's not specified, the default order is ascending.

Example:

// will sort table using values from the first column in descending order
hot.getPlugin('columnSorting').sort(0, 'desc')

Help us improve this page