<?xml version="1.0" encoding="UTF-8" ?>
<dt-type group="dt">
	<name>cell-selector</name>
	<summary>Selector options for cells.</summary>

	<description>
<![CDATA[

The DataTables `dt-api cells()` and `dt-api cell()` methods provide the ability to select individual cells from the table. What cells are selected and how the selector actually operates is controlled by this `dt-type cell-selector` data type.

### Options

The cell selector can be given in a number of different forms, to make it easy to apply to your data and use case:

* No selector - Select all cells
* `dt-type string` - jQuery selector
* `dt-type node` - This may be one of the following:
  * `-tag td` / `-tag th` cell
  * Any element which has both a `data-dt-row` and `data-dt-column` attribute assigned to it, or a parent (<span class="since">Since: 1.10.11</span>). This can be used by extensions such as FixedColumns and Responsive to allow easy column selection.
* `dt-type function` - Function selector (<span class="since">Since: 1.10.3</span>)
* `dt-type jQuery` - jQuery object of cell nodes
* `dt-type object` - DataTables cell indexes (`row` and `column` properties)
* `dt-type array` - Array containing any combination of the above options


## No selector

If no selector is given (more specifically `dt-type undefined`), then all cells are selected.

###### Get the nodes for all cells in the table:

```js
var table = $('#example').DataTable();
var cells = table.cells().nodes();
```


## string

When the selector is given as a string, it is treated as a [jQuery selector](http://api.jquery.com/category/selectors/) that operates on the `dt-tag td` and `dt-tag th` elements in the table's `dt-tag tbody`. For full information about the options available for jQuery selectors, please refer to the [jQuery selector documentation](http://api.jquery.com/category/selectors/).

Note that just like jQuery selector, is it possible to supply multiple selectors using comma separated notation (i.e. just separate by a comma) when the selector is provided as a string.

###### Get data from a single cell by id:

```js
var table = $('#example').DataTable();
var data = table.cell('#cell-2-42').data();
```

###### Select cells by class name:

```js
var table = $('#example').DataTable();
var cells = table.cells('.priority');
```

###### Select cells by two class name selectors:

```js
var table = $('#example').DataTable();
var cells = table.cells('.important, .intermediate');
```


## node

`dt-tag td` and `dt-tag th` DOM elements can be given as a cell selector to select a cell in the DataTabels API from that DOM element. This can be useful for getting data from a cell directly, or performing other cell based operations, when you have only the DOM node for reference, for example in an event handler.

###### Get the data for a cell that was clicked upon:

```js
var table = $('#example').DataTable();

$('#example tbody').on( 'click', 'td', function () {
  var cellData = table.cell( this ).data();
  // ... do something with `cellData`
} );
```


## Function

< # Version requirement
<
< Using a function as a cell selector requires DataTables 1.10.3 or newer.

For complete control over which cells are selected, it is possible to provide a function with logic you've defined to perform the selection. That logic can be as simple or as complex as you wish, performing the selection by simply returning `true` if the cell should be included in the selected results and `false` if not.

That can be particularly useful for finding cells based on the data they contain, or based on properties of the cell node.

The function receives three parameters:

1. Cell index - see `dt-api cell().index()`
2. Cell data - see `dt-api cell().data()`. Note that this is the original data for the cell, not the rendered data if you are using `dt-init columns.render`
3. Cell node - see `dt-api cell().node()`. Note that this may be `null` if you are using `dt-init deferRender`.

The function is called once for every cell that can be selected, based on the `dt-type selector-modifier` options, which also defines the order of the cells for the called function.

###### Get the nodes for all cells that contain `1`:

```js
var table = $('#example').DataTable();

var ones = table
	.cells( function ( idx, data, node ) {
		return data == 1 ?
			true : false;
	} )
	.nodes();

// Add a class to the cells
ones.to$().addClass('highlight');
```


## jQuery

Very similar to the above `node` type (since a jQuery object is an _array-like_ list of DOM nodes), a jQuery instance can be given as a cell selector, with any nodes which are selected by jQuery and match those available in the table's `dt-tag tbody` selected.

###### Get data from cells in a jQuery instance:

```js
var cells = $('td.immediate');
var table = $('#example').DataTable();

var cellData = table.cells( cells ).data();


## Object

Similar to the `dt-type row-selector` and `dt-type column-selector`, `dt-type cell-selector` can also use indexes to select individual cells, but in this case an object is used which has `row` and `column` properties, each of which is set to the row and column index, respectively, for the cell to be selected.

Although not particularly useful as a primary selector method, this can be very useful for selecting individual cells based on a `dt-api cells()` call - see the example below.

###### Loop over all cells, adding a class if the data for the cell is greater than a given value.

```js
table.cells().every( function () {
	if ( this.data() > 10 ) {
		$(this.node()).addClass( 'important' );
	}
} );
```


## array

Any combination of the above options can be given as selector together, providing a method to select multiple cells, or to mix selector types, by simply providing the selector options you want in an array.

###### Get the data for two cells, based on id:

```js
var table = $('#example').DataTable();
var data = table.cells( ['#cell-1-42', '#cell-1-91'] ).data();
```

###### Mix `cell-selector` types - id and class selector

```js
var table = $('#example').DataTable();
var data = table.cells( ['#cell-1-42', '.important'] ).data();
```

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