order()
Get / set the ordering applied to the table.
Description
This method provides information and control over the ordering that has been applied to the DataTables in the API's context.
The column ordering input parameter format is defined by DataTables.Order
which can accept column index objects, column name objects or tuples to define the order to apply. An array of those options can also be used to define multi-column ordering.
The return format used is a 2D array:
[
[ colIdx_1, orderingDirection_1 ],
[ colIdx_2, orderingDirection_2 ],
...,
[ colIdx_n, orderingDirection_n ]
]
where colIdx_x
is the column data index of the column whose data is used to perform the ordering, and orderingDirection_n
is the direction of the ordering (desc
(descending) or asc
(ascending)) - note that these must be lower-case. The column index is zero based - i.e. the first column in the table is index 0
, the second index 1
etc.
Using this format, DataTables can achieve single column ordering (i.e. just use one entry in the top level array), or multi-column ordering to the nth column (multiple entries in the array).
Please be aware that this method sets the ordering to apply to the table - it does not actually perform the order. In order to have the order performed, use the draw()
method, which can be called simply as a chained method of the order()
method's returned object - for example table.order([0, 'desc']).draw();
.
Types
function order()
- Description:
Get the current ordering of the table. If there is more than one table in the API's context, the ordering of the first table will be returned. Use
table()
if you require the ordering of a different table in the API's context.- Returns:
Array of arrays (tuples) containing information about the currently applied sort in the format
[columnIndex, direction]
. See below andDataTable.Order
's Return Types for more information.
function order( order [, ...] )
- Description:
Set the ordering to apply to the table using 1D ordering arrays. Note this doesn't actually perform the order, but rather queues it up - use
draw()
to perform the ordering.- Parameters:
Name Type Optional 1 order
No An array (tuple) or object to describe the ordering to apply.
2 ...
Yes - default: Additional arrays / objects in the same format as the first parameter, allowing multi-column sorting. As many or as few additional arrays can be added as additional parameters, as your requirements demand.
- Returns:
DataTables API instance
function order( order )
- Description:
Set the ordering to apply to the table using a 2D ordering array. Note this doesn't actually perform the order, but rather queues it up - use
draw()
to perform the ordering.- Parameters:
Name Type Optional 1 order
No An array in the same format as the 1D options for this method above, but with multiple entries in the top level array, allowing multi-column sorting to be defined.
- Returns:
DataTables API instance
Examples
Get the current ordering of the table:
var table = new DataTable('#example');
var order = table.order();
alert('Column ' + order[0][0] + ' is the ordering column');
Set the ordering using a tuple:
var table = new DataTable('#example');
// Sort by column index 1 and then re-draw
table.order([1, 'asc']).draw();
Set the ordering using an index based object:
var table = new DataTable('#example');
// Sort by column index 1 and then re-draw
table
.order({
idx: 1,
dir: 'asc'
})
.draw();
Set the ordering using multiple tuples to achieve multi-column sorting:
var table = new DataTable('#example');
// Sort by column indexes 1 and 2 and redraw
table.order([1, 'asc'], [2, 'asc']).draw();
Multi-column ordering using column names:
var table = new DataTable('#myTable', {
columns: [
{ name: 'first_name' },
{ name: 'last_name' },
{ name: 'position' },
{ name: 'city' }
]
});
table
.order([
{ name: 'first_name', dir: 'asc' },
{ name: 'last_name', dir: 'asc' }
])
.draw();
Related
The following options are directly related and may also be useful in your application development.