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.
Ordering information is stored by DataTables in a 2D array format:
[
[ 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).
For convenience, this method allows multi-column ordering to be performed by passing in either multiple 1D ordering arrays or a 2D ordering array. When retrieving the ordering information from the table, a 2D ordering array is always returned.
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 containing information about the currently applied sort. This 2D array is the same format as the array used for setting the order to apply to the table (see below).
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 in the format
[ columnIndex, "asc|desc" ]
(e.g.[ 1, "desc" ]
to order by the second column descending).2 ...
Yes - default: Additional arrays 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 array format of 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 = $('#example').DataTable();
var order = table.order();
alert( 'Column '+order[0][0]+' is the ordering column' );
Set the ordering using a 1D array:
var table = $('#example').DataTable();
// Sort by column 1 and then re-draw
table
.order( [ 1, 'asc' ] )
.draw();
Set the ordering using multiple 1D arrays to achieve multi-column sorting:
var table = $('#example').DataTable();
// Sort by columns 1 and 2 and redraw
table
.order( [ 1, 'asc' ], [ 2, 'asc' ] )
.draw();
Use a 2D array to achieve multi-column sorting (matching the example above in functionality):
var table = $('#example').DataTable();
// Sort by columns 1 and 2 and redraw
table
.order( [[ 1, 'asc' ], [ 2, 'asc' ]] )
.draw();
Related
The following options are directly related and may also be useful in your application development.