API integration

Select presents an interface to the end user to allow item selection by clicking on table elements. This is all the end user really needs to know about the software, but it is only half the story! You, the programmer, need to know when items have been selected and you need to able to retrieve those items to process that selection!

This is done through the DataTables API which Select augments to make these manipulations possible.

Selected items retrieval

DataTables has three primary methods for obtaining items from a DataTable (and three matching singular items):

• rows() and row() to select rows
• columns() and column() to select columns
• cells() and cell() to select cells

Each of these methods has their own options that can be used to select specific items, but they all provide the option to pass in a selector-modifier option. This option is used to tell the API how to order and filter the items that can be selected from. Select augments this by adding a selected option to the selector-modifier object. When true it will return the selected items, when false it will return the items which are not selected. If undefined it will not perform any actions.

Consider for example the following:

var table = $('#myTable').DataTable();

table.rows( { selected: true } ).data();

This will retrieve the data (using rows().data()) for any rows that are selected. We can extend that with the other selector-modifier options if required:

table
    .rows( {
        selected: true,
        page: 'current'
    } )
    .nodes();

In this case the row nodes (rows().nodes()) are returned for the selected items on the current page.

This can of course be combined with a regular row selector:

table.rows( '.important', { selected: true } ).data();

will get the data for any rows which are selected and have the class important.

Similarly we can perform similar actions with the other table selection API methods - for example:

table.cells( { selected: true } ).data();

to get the cells that are selected if using the cell selection options.

While working with the API and selected rows it is worth noting that the any() and count() helper methods can be useful to know if and how many items are selected.

Item selection

As well as being able to retrieve the selected items using the DataTables API, it is also possible to select and deselect items using the API. This is done using the the following plural functions and their singular counterparts:

• rows().select() / rows().deselect()
• columns().select() / columns().deselect()
• cells().select() / cells().deselect()

For example, to select all rows with the class important use:

table.rows( '.important' ).select();

This can also be used to implement your own item selection interface if you prefer instead of using the options made available by Select. For example consider the following:

$('#myTable').on( 'click', 'tbody tr', function () {
    if ( table.row( this, { selected: true } ).any() ) {
        table.row( this ).deselect();
    }
    else {
        table.row( this ).select();
    }
} );

This code will toggle the selection of rows in the table. Line by line:

• Line 1 - Attach a delegated event listener to the rows in the table
• Line 2 - Check if the row is selected
• Line 3 - If it is selected, deselect it
• Line 6 - If not selected, select it

Events

The final piece of the puzzle is to to know when items are selected. This is done using events that are emitted by Select - specifically the select and deselect events. These can be listened for using the standard DataTables event model.

When using Select it is also quite natural to use the Buttons extension for DataTables - allowing the user to select items and then click a button to trigger an action on those items.

Select provides the selected and selectedSingle buttons for use with Buttons, which can be used to easily provide your own actions when items are selected. These buttons are automatically deactivated when there are no items selected (in the case of selectedSingle when there is more than one item selected as well) and activated when items are selected.

Consider for example the following which uses the selected button to simply tell you how many rows are selected:

$('#myTable').DataTable( {
    select: true,
    buttons: [
        {
            extend: 'selected',
            action: function ( e, dt, node, config ) {
                var rows = dt.rows( { selected: true } ).count();

                alert( 'There are '+rows+'(s) selected in the table' );
            }
        }
    ]
} );