column-selector

Selector options for columns.

Description

The DataTables columns() and column() (also optionally cells() and cell()) methods provide the ability to select columns from the table. Which columns are selected and how the selector actually operates is controlled by this column-selector data type.

Options

The column 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 columns
• integer - Column index selector
• {integer}:visIdx - Column visible index selector (e.g. 3:visIdx)
• {integer}:visible - Alias of {integer}:visIdx. Note that as of 2.1.4 it is possible to use a regular DOM selector in front of :visible to select visible columns that match the given selector. The prefixed number is a special case.
• {string}:name - Column name selector, from columns.name (e.g. salary:name)
• {string}:title - Column title selector - select based on the title text for the column (e.g. My\ Column:title)
• string - jQuery selector
• node - This may be one of the following:
  • th / td cell from the column headers
  • td / td cell from the table body (Since: 1.10.11)
  • Any element which has a 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 the column header nodes
• array - Array containing any combination of the above options

No selector

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

Get data for all columns in the table:

var table = new DataTable('#myTable');
var allData = table.columns().data();

integer

DataTables stores each column internally with a column index for fast look up of column information. When the selector is given as an integer, this value represents a column data index (columns().indexes() / column().index()).

Note that this is the column data index and not the visible index. The data index is fixed regardless of column visibility, while the visible index will change as the visibility of columns are changed (see below for a visible index selector).

Column data index 0 data:

var table = new DataTable('#myTable');
var data = table.column( 0 ).data();

{integer}:visible

The visible index of a column is the index when hidden columns are taken into account. This can be useful when working with event handlers and some columns are hidden, or can be hidden by the end user. This selector is simply a modification of the above integer type with the string :visible (or :visIdx) postfixed. For example: 3:visIdx.

Get the data for a column that was clicked on:

var table = new DataTable('#myTable', {
    columnDefs: [
        { visible: false, targets: 1 }
    ]
} );

$('#example tbody').on( 'click', 'td', function () {
    var columnData = table
        .column( $(this).index()+':visIdx' )
        .data();
} );

As of DataTables 2.1.4 this option has been extended to support a regular DOM selector in front of :visible to allow you to select only visible columns. You can also not include a selector to select only visible columns:

// Select columns that are visible and have a class of `important`
table.columns('.important:visible')

// Select all visible columns
table.columns(':visible')

{string}:name

DataTables provides the ability to assign a name to columns through the columns.name option, which can be very useful for giving columns a human readable representation. The :name selector provides the ability to selector columns based on the assigned name.

This selector is simply a string (the column name) with :name postfixed. For example salary:name.

Note that assigned column names need not be unique (although that you would normally wish them to be so). If a selector is given which matches multiple columns from the same name they will all be selected.

Get the data for a named column:

var table = new DataTable('#myTable', {
    columns: [
        { name: 'first-name' },
        { name: 'last-name' },
        { name: 'position' },
        { name: 'location' },
        { name: 'salary' }
    ]
} );

// Get salary column data
table.column( 'salary:name' ).data();

string

When the selector is given as a string, it is treated as a jQuery selector that operates on the th and td elements of the column headers in the table.

Each column has only one cell which is used as the column header - see orderCellsTop for information on how DataTables selected the cells to use for the column headers, if there is more than one possible cell for each column header in the table's thead element.

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 a single column by id:

var table = new DataTable('#myTable');
var column = table.column('#column-3');

Select columns by class name:

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

Select column by contents:

var table = new DataTable('#myTable');
var column = table.column(':contains(Salary)');

node

th and td DOM elements can be given as a column selector to select a column in the DataTabels API from that DOM element (as above, this selector applies to the cells which are used for the column headers, not necessarily all cells in the header if there are multiple rows).

This can be useful for getting data from a column, or performing other column based operations, when you have only the DOM node for reference, for example in an event handler.

Get the data for a column that was clicked upon:

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

$('#example thead').on( 'click', 'th', function () {
  var columnData = table.column( this ).data();
  // ... do something with `columnData`
} );

Function

For complete control over which columns 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 column should be included in the selected results and false if not.

The function receives three parameters:

1. Column index - see column().index()
2. Column data - see column().data(). Note that this is an array of data with one entry for each cell in the selected column. The data uses is the original data for the cells, not the rendered data if you are using columns.render
3. Column node - see column().header(). Note that this is not the cells in the table body. Use column().nodes() if you require that information.

The function is called once for every column that can be selected, based on the selector-modifier options, which also defines the order of the data passed in as the second argument for the called function.

Get the data for all columns that contain the string Active:

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

var active = table
    .columns( function ( idx, data, node ) {
        return $.inArray( 'Active', data ) !== -1 ?
            true : false;
    } )
    .data();

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

Please note that when working with a jQuery selected set of columns and hidden columns, jQuery itself will not select the column header cells which have been hidden (as DataTables removes them from the document when the column is hidden). To overcome this is problem, use the string option above which does not suffer from this issue and allows a jQuery selector to be used.

Get data from columns in a jQuery instance:

var columns = $('#example thead th.immediate');
var table = new DataTable('#myTable');

var columnData = table.columns( columns ).data();

array

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

Get the data for two columns, based on column index:

var table = new DataTable('#myTable');
var data = table.columns( [0, 1] ).data();

Mix column-selector types - index and class selector

var table = new DataTable('#myTable');
var data = table.columns( [0, '.important'] ).data();