order()

Since: DataTables 1.10

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

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`	`array`	No
	An array in the format `[ columnIndex, "asc\|desc" ]` (e.g. `[ 1, "desc" ]` to order by the second column descending).
2	`...`	`array`	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

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:

Returns:

DataTables.Api

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();

The following options are directly related and may also be useful in your application development.

Options

	Name	Type	Optional
1	`order`	`array`	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.