cell-selector

Selector options for cells.

Description

The DataTables cells() and 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 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
string - jQuery selector
node - This may be one of the following:
- td / th cell
- Any element which has both a data-dt-row and data-dt-column attribute assigned to it, or a parent (Since: 1.10.11). This can be used by extensions such as FixedColumns and Responsive to allow easy column selection.
function - Function selector (Since: 1.10.3)
jQuery - jQuery object of cell nodes
object - DataTables cell indexes (row and column properties)
array - Array containing any combination of the above options

No selector

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

Get the nodes for all cells in the table:

var table = new DataTable('#myTable');
var cells = table.cells().nodes();

string

When the selector is given as a string, it is treated as a jQuery selector that operates on the td and th elements in the table's tbody. For full information about the options available for jQuery selectors, please refer to the jQuery selector documentation.

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:

var table = new DataTable('#myTable');
var data = table.cell('#cell-2-42').data();

Select cells by class name:

var table = new DataTable('#myTable');
var cells = table.cells('.priority');

Select cells by two class name selectors:

var table = new DataTable('#myTable');
var cells = table.cells('.important, .intermediate');

node

td and 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:

var table = new DataTable('#myTable');

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

Function

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:

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

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

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

var table = new DataTable('#myTable');

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 tbody selected.

Get data from cells in a jQuery instance:

var cells = $('td.immediate');
var table = new DataTable('#myTable');

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:

var table = new DataTable('#myTable');
var data = table.cells( ['#cell-1-42', '#cell-1-91'] ).data();

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

var table = new DataTable('#myTable');
var data = table.cells( ['#cell-1-42', '.important'] ).data();