<< home

visiEdit library

A library, based on Prototype version 1.6, provides interactive spreadsheet-like editing capability to HTML tables.

Main features:

Try using it on the example table below:

label1label2label3label4label5
     
     
     
     
     
     
     
     
     
     
     
     

download it

Current version of the software is 1.2.5.

visiedit.js

use it in your web application

visiEdit is remarkably easy to use on a reasonably formatted HTML TABLE. You just need to assign the table a unique id and create a TableEditing object.

Link the JavaScript library into your HTML file:

<script type="text/JavaScript" src="prototype.js"></script>
<script type="text/JavaScript" src="visiedit.js"></script>

Then place this declaration inside a script tag, which must be executed when the page has loaded:

new visiEdit.TableEditing('yourTableId');

for example, inside a dom:loaded event handler:

document.observe('dom:loaded', function() {
  new visiEdit.TableEditing('yourTableId');
});

This instruction will provide basic editability to the table, like the example below:

label1label2label3label4label5
     
     

To start editing a cell, double click on it. To finish editing, click on another cell.

keyboard event management

In order to catch keyboard events, you need to instantiate a KeyboardBroker object, which will be shared by every visiEdit object in the page, and pass it as the second parameter to TableEditing constructor:

var kb = new visiEdit.KeyboardBroker();
new visiEdit.KeyboardBroker('yourTableId', kb);

Here there is a table which can capture keyboard events:

label1label2label3label4label5
     
     

You can navigate the table using TAB, SHIFT+TAB, RETURN and the arrow keys, and leave the focus by pressing ESC.

By pressing any character key while selecting a cell, will start to edit that cell. Pressing RETURN or TAB while editing a cell will commit the data and respectively navigate to the next row or cell.

clipboard management

You can copy/paste within the table or from/to an external application, like a spreadsheet.

This feature is only available on MS IE 6+ and Firefox (and other Gecko powered browsers, although it has not been yet tested on them).

In order to add this functionality, another object must be instantiated and passed to the TableEditing constructor:

var kb = new visiEdit.KeyboardBroker();
sc = new visiEdit.SystemClipboard();
new visiEdit.KeyboardBroker('yourTableId', kb, sc);

Experiment below with the use of the system clipboard:

label1label2label3label4label5
     
     

styling

visiEdit objects don't make any assumption on visual styling of table elements. What these object do, in order to change the appearance of the HTML elements, is adding and removing classes to them.

Default classes are pretty straight-forward, for example selected cells are applied class _selected_, and so on. But they can easily customized, for example to reuse existing classes that appear in other parts of your application.

Custom classes must be declarated in a map, passed to the TableEditing constructor as the fourth parameter:

var kb = new visiEdit.KeyboardBroker();
sc = new visiEdit.SystemClipboard();
new visiEdit.KeyboardBroker('yourTableId', kb, sc, {
  selectionClass: 'yourSelectedClassName',
  activeClass: 'yourActiveClassName', ..});

Here are provided the available properties, with the element to which they are applied. All are optional within the map.

activeClass
TABLE tag when it gains focus
selectionClass
TD cells which are part of the selection
editingClass
TEXTAREA element which is created for editing a cell
contextMenuClass
DIV container of a contextual menu
contextMenuSelectedClass
TABLE TD cells of the contextual menu, when the mouse hovers on them

integrating

visiEdit can cooperate with other JavaScript code by means of some hooks, that can be linked to user callback functions, which will be invoked when specific events occur

Any callback function must be specified in a map, that is passed as the fifth parameters to the TableEditing constructor:

var kb = new visiEdit.KeyboardBroker();
sc = new visiEdit.SystemClipboard();
new visiEdit.KeyboardBroker('yourTableId', kb, sc, {...}, {
  cellEditCallback: function(cell, initString),
  cellChangeCallback: function(cell, true|false), ...});

The most useful callbacks are these:

cellSelectCallback(startCell, endCell)
invoked for each new selection.
cellEditCallback(cell, initString)
to override standard editing. The second parameters contain initial value to be put in the editing field, if any. If standard editing should be skipped, return true.
cellChangeCallback(cell, true|false)
invoked each time a cell is edited. It is passed the new value, it can change it and pass it back. The second parameter indicates if the cell is meant to be changed or it must be left unchanged. It must return the string value to be put into the cell.

contextual menu

Optionally, if a list is passed as the last parameter, a contextual menu can be shown when right-click occur on the table.

Standard action labels can be personalized, by adding a field label to the relevant item. For example:

var kb = new visiEdit.KeyboardBroker();
sc = new visiEdit.SystemClipboard();
new visiEdit.KeyboardBroker('yourTableId', kb, sc, {...}, {...}, [
  { name: 'copy', label: 'Copy' },
  { name: 'paste' }]);

In the example above, a contextual menu with Copy and paste items will be shown when the user right-clicks. Selecting an item will trigger the corresponding action. Available items are:

copy
copy selection contents to clipboard
paste
paste clipboard contents to selection
cut
delete selection contents and copy it to clipboard
delete
delete selection contents

license

As other JavaScript libraries, visiEdit is freely distributable under the terms of an MIT-style license.

feedback

I'am happy to hear any feedback, bug report, suggestion, or just know what you think about it. Drop me a line at this email address: luigi <dot> sgro <at> Gmail.

<< home