<?xml version="1.0" encoding="UTF-8" ?>
<dt-type group="dt">
	<name>selector-modifier</name>
	<summary>Options for how the row, column and cell selector should operate on rows.</summary>

	<description>
	<![CDATA[

When working with the selectors in `dt-api rows()`, `dt-api columns()` and `dt-api cells()` (and their singular counterparts) you will want to know, and be able to control, basic aspects of how DataTables treats the rows, such as the order they are processed in, and what set of rows the selector should act upon. This `dt-type selector-modifier` type provides exactly that ability and can optionally be used in any of the functions that uses a selector.

### Server-side processing

Special note on server-side processing: When using DataTables in server-side processing mode (`dt-init serverSide`) the `dt-type selector-modifier` has very little effect on the rows selected since all processing (ordering, search etc) is performed at the server. Therefore, the only rows that exist on the client-side are those shown in the table at any one time, and the selector can only select those rows which are on the current page.


### Options

Fundamentally `dt-type selector-modifier` is an object with three built-in properties that can be used, and this can be extended by extensions such as [Select](/extensions/select). These properties, including their default values are:

```js
{
	// DataTables core
    order:  'current',  // 'current', 'applied', 'index',  'original'
    page:   'all',      // 'all',     'current'
    search: 'none',     // 'none',    'applied', 'removed'

    // Extension - KeyTable (v2.1+) - cells only
    focused: undefined, // true, false, undefined

    // Extension - Select (v1.0+)
    selected: undefined // true, false, undefined
}
```

## Built-in options

### order

The `order` modifier provides the ability to control which order the rows are processed in. This can have an effect on the return from chained functions - for example `dt-api column().data()` can return the data for the column in the order that the table currently shows the data, or in the original data order.

* `dt-string current` (default) - Process the rows in the order currently applied to the table.
* `dt-string index` - Process the rows in their data index order (the order the data was originally read into the table).
* `dt-string applied` - Alias of `current`.
* `dt-string original` - Alias of `index` for backwards compatibility.

###### Get the data from a column in the applied order:

Note that since the `dt-type selector-modifier` is optional, and `dt-string applied` is the default value for the column, the example below is the same as: `table.column( 3 ).data();` - it just sets the `order` parameter explicitly.

```js
var table = $('#myTable').DataTable();
table.column( 3, {order:'current'} ).data();
```

###### Get the data from a column in data index order:

```js
var table = $('#myTable').DataTable();
table.column( 3, {order:'index'} ).data();
```


### page

The `page` modifier allows you to control if the selector should consider all data in the table, regardless of paging, or if only the rows in the currently displayed page should be used.

* `dt-string all` (default) - Use the rows from all pages
* `dt-string current` - Use the rows from only the currently displayed page.

**Important**: Setting `page` to be `dt-string current` implicitly sets `order=current` and `search=applied`. The `dt-string current` option doesn't make sense otherwise! These implied `order` and `search` values cannot be overridden by explicitly setting them.

###### Get the data for the rows on the current page only:

```js
var table = $('#myTable').DataTable();
table.rows( {page:'current'} ).data();
```


### search

The `search` modifier provides the ability to govern which rows are used by the selector using the search options that are applied to the table.

* `dt-string none` (default) - Do not take searching into account (i.e. all rows are used)
* `dt-string applied` - Use only rows which match the current search applied to the table
* `dt-string removed` - Use only rows that have been removed from the table by the search applied.

Note that for backwards compatibility, the `search` term can also be provided as the property `filter`. If both are provided, the `search` term is used in preference.

###### Get the `dt-tag tr` elements for rows which match the search term applied to the table, in index order:

```js
var table = $('#myTable').DataTable();
table.rows( {order:'index', search:'applied'} ).nodes();
```

###### Get removes which have been removed from the search:

```js
var table = $('#myTable').DataTable();
table.rows( {search:'removed'} ).nodes();
```



## Extensions

The following options describe behaviour that can be added to DataTables core through the use of its [extensions](/extensions). These extensions provide tight integration with the DataTables API and these options can be working with the extensions feel a natural part of DataTables.


### focused (cells only)

< This option requires the [KeyTable extension](/extensions/keytable) to be loaded in order to be able to operate (v2.1 or newer).

[KeyTable](/extensions/keytable) provides the ability to focus on a particular cell in the DataTable, and as such it can often be useful to know which cell is focused, and equally which cells do not have focus.

Please note that this option can only be used in conjunction with the `dt-api cells()` and `dt-api cell()` methods. Using it with the row or column selectors will have no effect.

This option takes a boolean value, although it can also be `undefined`, which it is by default:

* `-type undefined` (default) - No selection modification is performed
* `true` - Only the focused cell will be selected
* `false` - Only cells which _do not_ have focus will be selected.

###### Get the data for the focused cell:

```js
var table = $('#myTable').DataTable();
table.cell( {focused:true} ).data();
```


### selected

< This option requires the [Select extension](/extensions/select) to be loaded in order to be able to operate.

The [Select extension](/extensions/select) for DataTables provides the ability to select items in the table (rows, columns and cells), and so it is important to be able to retrieve the items that the user has selected so you can perform some action on them.

This option takes a boolean value, although it can also be `undefined`, which it is by default:

* `-type undefined` (default) - No selection modification is performed
* `true` - Only items that have been selected are retrieved
* `false` - Only items that have _not_ been selected are retrieved.

###### Get the data for the selected rows:

```js
var table = $('#myTable').DataTable();
table.rows( {selected:true} ).data();
```

Additional information about this property can be found in the [Select manual](/extensions/select/integration).


	]]>
	</description>
</dt-type>
