API Integration

The primary interface that KeyTable provides is the simple cell focusing options for the end user, but equally important is the interface that it presents to you, the developers working with it! KeyTable provides methods for focusing on cells, obtaining the focused cell and events as the cell focus changes.

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

Focused cell retrieval

KeyTable augments the selector-modifier option with a focused option that can be used to tell the cell selector API methods if you want to get the focused cell, the unfocused cells or not to consider the cell focus when selected cells.

DataTables has two cell selection methods:

• cells() to obtain multiple cells
• cell() to obtain a single cell.

Since only a single cell can have focus in a KeyTable controlled table, the cell() method is the primary method used with KeyTable.

The selector-modifier is passed into the method and will effect the items that the cell selector will choose from. Consider for example the following:

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

table.cell( { focused: true } ).data();

The above code will get the data from the cell that currently has focus. If no cell has focus undefined is returned.

If we wish to get the cells which do not have focus we could use:

table.cells( { focused: false } ).data();

This method of using a selector modifier to allow cell selection means that all of the cell methods are available for easy use with the focused cell - e.g. cell().node() and cell().invalidate() among others.

Focus selection

As well as being able to retrieve the focused cell using the DataTables API, it is also possible to set focus and blur existing focus using the API. This is done using the the following methods:

• cell().focus() - Gain focus
• cell.blur() - Blur focus

For example, to focus on a cell with a specific ID we might use:

table.cell( '#row9-column12' ).focus();

Events

The final piece of the puzzle is to to know when cells are focused. This is done using events that are emitted by KeyTable - specifically the key-focus, key-blur and key events. These can be listened for using the standard DataTables event model.

Consider for example the following simple case where the key-focus and key-blur events are used to simply show the data for the focused cell in a separate element on the page:

var output = $('#output');
var table = $('#myTable').DataTable( {
    keys: true
} );

table
    .on( 'key-focus', function () {
        var data = table.cell( { focused: true } ).data();
        output.html( data );
    } )
    .on( 'key-blur', function () {
        output.html( 'No cell has focus' );
    } );