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.

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

Array of arrays (tuples) containing information about the currently applied sort in the format [columnIndex, direction]. See below and DataTable.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`	`DataTables.Order`	No
	An array (tuple) or object to describe the ordering to apply.
2	`...`	`DataTables.Order`	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

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`	`DataTables.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

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

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

Options