selector-modifier

Options for how the row, column and cell selector should operate on rows.

Description

When working with the selectors in rows(), columns() and 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 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 (serverSide) the 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 selector-modifier is an object with three built-in properties that can be used, and this can be extended by extensions such as Select. These properties, including their default values are:

{
    // DataTables core
    order:  'current',  // 'current', 'applied', 'index', 'original', number
    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 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.

current (default) - Process the rows in the order currently applied to the table.
index - Process the rows in their data index order (the order the data was originally read into the table).
applied - Alias of current.
original - Alias of index for backwards compatibility.
number - A column index whose sorting should be applied to the data (since 2.0). Please note that this option does not operate with the page: 'current' option.

Get the data from a column in the applied order:

Note that since the selector-modifier is optional, and 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.

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

Get the data from a column in data index order:

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

```

Get the data from a column in the order DataTables would sort it in:

var table = new DataTable('#myTable');
table.column( 3, {order:3} ).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.

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

Important: Setting page to be current implicitly sets order=current and search=applied. The 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:

var table = new DataTable('#myTable');
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.

none (default) - Do not take searching into account (i.e. all rows are used)
applied - Use only rows which match the current search applied to the table
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 `tr` elements for rows which match the search term applied to the table, in index order:

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

Get removes which have been removed from the search:

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

Extensions

The following options describe behaviour that can be added to DataTables core through the use of its 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)

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 cells() and 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:

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:

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

selected

The Select extension 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.