table-selector

Selector options for tables.

Description

The DataTables tables() and table() methods provide the ability to select the full set, or a subset, of the tables that are held in an API instance's context. The context of an API instance is the DataTables that the instance will act upon when an operation is performed using the methods available (for example, a page can be changed for multiple tables with a single call). For more information about how the API operates, please refer to the API manual.

Most API calls will operate on all tables in the API's context automatically, but the tables() and table() methods can be used to select a subset of those tables. What are selected and how the selector actually operates is controlled by this table-selector data type.

Options

The table 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 tables
• integer - Table index selector
• string - jQuery selector
• node - table element selector
• jQuery - jQuery object of table nodes
• array - Array containing any combination of the above options

No selector

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

Get the data from all tables in the current context:

var tables = new DataTable('.dataTable');
var allData = tables.tables().rows().data();

// note that the above is the same as:
// tables.rows().data(); as `rows()` operates on
// all tables in the current context!

integer

If an integer is given for the table selector, then the table with that index in the context is selected.

Get the nodes of the first table in the current context:

var tables = new DataTable('.dataTable');
var data = tables.table( 0 ).data();

string

When the selector is given as a string, it is treated as a jQuery selector that operates on the table elements themselves. 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.

Select tables by class name:

var tables = new DataTable('.dataTable');
tables
    .tables('.cell-selector')
    .page( 'next' )
    .draw( false );

Select table by ID:

var tables = new DataTable('.dataTable');
var table = tables.table('#example');

Select two tables by ID:

var tables = new DataTable('.dataTable');
tables.tables('#clients, #owners');

node

tables DOM elements can be given as a table selector to select a table in the DataTabels API from that DOM element. This can be useful for getting data from a row, or performing other row based operations, when you have only the DOM node for reference, for example in an event handler.

Get the data for the table that was clicked upon:

var tables = new DataTable('.dataTable');

$('.dataTable tbody').on( 'click', 'tr', function () {
    var tableData = tables.table( this.parentNode.parentNode );
    // ... do something with `tableData`
} );

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 table selector, with any nodes which are selected by jQuery and match those available in the API instance's context.

Get the data for the table that was clicked upon:

var tables = new DataTable('.dataTable');

$('.dataTable tbody').on( 'click', 'tr', function () {
    var tableData = tables.table( $(this).parents('table') );
  // ... do something with `tableData`
} );

array

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

Get the data for two tables, based on id:

var tables = new DataTable('.dataTable');
var data = tables.tables( ['#table-1', '#table-3'] ).data();

Mix table-selector types - id and class selector

var tables = new DataTable('.dataTable');
var data = table.tables( ['#table-1', '.important'] ).data();