Introduction

KeyTable is a Javascript library which provides keyboard navigation and event binding for any HTML table. With KeyTable Excel style table navigation can be employed to provide features such as editing of a table without requiring a mouse. As a further bonus, KeyTable integrates seamlessly with DataTables.

Let's jump straight into an example: the table below is editable through keyboard navigation. Simply navigate to the cell you wish to edit and hit return. This initialises the excellent jEditable plug-in for jQuery - make your edit and then hit return again to save.

I've put together a couple of other demos:

• Basic event listening
• Editing with a large table
• Integration with an HTML form
• Integration with DataTables

Usage

Using KeyTable on a plain HTML is as simple as creating a new object:

var keys = new KeyTable();

By default, KeyTable will attach itself to the first table it finds in the DOM with the class 'KeyTable' and apply basic navigation controls. There are a number of initialisation parameters that you can pass into the constructor to provide a bit more control over the default behaviour:

• "focus" - which element in the table is to be focused on initially. This can either be a TD node element, or a set of coordinates (for example [0, 5]).
• "table" - TABLE node which KeyTable should attach to.
• "focusClass" - the class to be used for the focused cell (default "focus").
• "initScroll" - scroll the viewport automatically to the first cell (default "true").
• "form" - is the table part of a form or not. If so then it will handle tabbing for you (default "false").
• "dataTable" - $().datatable() object, for use with DataTables (required DataTables 1.5 - note that it will not work with 1.5's server-side processing component).
• "tabIndex" - the tab index to give to the hidden input field if using KeyTable as a form element.

Events

Once KeyTable has been initialised you will most likely wish to add event listeners to the cell in the table. This is done thought the methods presented by the 'event' object of KeyTable. The following events are supported:

• "focus" - when the cell received focus
• "blur" - when the cell looses focus
• "action" - when the cell receives a 'return' key event
• "esc" - when the cell receives an 'escape' key event

Adding events

Each of these events is applied by calling event.{event_name}() (where event_name is of course one of the events from above). This function accepts either two or three inputs:

• 1. TD node to receive the event listener
• 2. Event listener function
• or
• 1. Cell X coordinate (can be set to null)
• 2. Cell Y coordinate (can be set to null)
• 3. Event listener function

/* Example event listener */
keys.event.focus( 1, 3, function() {
	/* processing on cell 1,3 ... */
} );

/* this is exactly the same as */
keys.event.focus( $('#example tbody tr:eq(3) td:eq(1)')[0], function() {
	/* processing on cell 1,3 ... */
} );

As noted in the above arguments list, when passing in coordinates to attach an event listener to a cell, you can pass null for either (or both) the x and y coordinates. This generalises the event target to occur on the given x or y coordinate, regardless of the other point. For example this allows you to target whole rows or columns, rather than just individual cells.

/* Event listener for a row */
keys.event.focus( null, 0, function() {
	/* handler for focus events in first row ... */
} );

/* Event listener for a column */
keys.event.focus( 3, null, function() {
	/* handler for focus events in forth column ... */
} );

/* Event listener for all cells */
keys.event.focus( null, null, function() {
	/* handler for focus events on all cells ... */
} );

Event handler parameters

There are three parameters which are passed into the event handler, which can then be used by your handler function to perform whatever actions are necessary:

• 1. node: The TD cell which is the target of the current event
• 2. integer: The cell's x coordinate in the table
• 3. integer: The cell's y coordinate in the table

There is no return parameter expected from the event handler.

Removing events

Events listeners can be removed through the 'event.remove.{event_name}' object. This function call expects the same inputs as the methods to add events, but in this case the event listener function is optional. If it is left off then all events of that type are removed from that cell.

API functions

It can be useful to get information from KeyTable about the currently focused cell. There are three different API functions to give you various pieces of information:

• fnGetCurrentPosition() - returns and array [x,y] of the cell's position
• fnGetCurrentData() - returns the 'innerHTML' of the current cell
• fnGetCurrentTD() - returns the TD node of the current cell

/* API example */
$(document).ready( function () {
	var keys = new KeyTable( {
		"table": document.getElementById('example')
	} );
	
	var coords = keys.fnGetCurrentPosition();
	alert( "Initially focused cell is: "+coords[0]+", "+coords[1] );
} );

Requirements and support

KeyTable has been tested and works great on:

• IE6+
• Firefox 3+
• Safari 3+ (Safari 4 is required for correct tabbing with a "form" table)
• Opera 9.6 (Opera 10a has a rendering bug - bug filed)

I expect that plenty of other browser will work just fine as well. There is one little hiccup in the key event handling. It would appear that there is very little consistency between browsers on however to handle repeat events on 'special' keys such as arrow keys. However, KeyTable does detection to overcome this issue.

KeyTable expects the target table to be well defined and to have a tbody tag. It will not work with out this! It also utilises jQuery's selector and event methods in order to provide easy cross platform implementation. However, since my usage of jQuery is limited to just these two components it would be relatively trivial to port KeyTable to any other library you like.

Download

KeyTable is open source software (GPL v2 or BSD 3 point style) and the source can be downloaded from the link below:

• KeyTable 1.1

If you are interested in a library for event handling on all elements, rather than KeyTable which specialises in table navigation, check out QFocuser by Daniel Steigerwald.

If you do apply KeyTable to any interesting use case, please let me know about it - it's always good to hear how the software on this site is being used!