Working with Events

Listening for events with dojo/on and grid.on

The dojo/on module, new to Dojo 1.7, provides a concise yet powerful API for registering listeners, especially for DOM events. Listening for events of interest on a dgrid component is very straightforward using dojo/on; furthermore, dgrid components possess an on method, which is equivalent to calling dojo/on passing the component's top-level DOM node as the target.

Using the event delegation features of dojo/on, it is possible to listen for all manner of events. For example, to listen for right-clicks on rows in the grid's body:

grid.on(".dgrid-row:contextmenu", function(evt){ /* ... */ });

Or, to listen to clicks on individual header cells:

grid.on(".dgrid-header .dgrid-cell:click", function(evt){ /* ... */ });

In summary, pretty much any combination desired can be achieved by using event delegation with selectors based on the dgrid-header, dgrid-row, and dgrid-cell CSS classes as appropriate.

Obtaining information about events

Commonly, the most important information about an event will be the row or cell in which it was triggered. With dgrid components, this information is retrievable by passing the event object itself to the instance's row or cell method. These methods are particularly powerful, in that they are capable of returning information about a row or cell, simply given a row/cell element or any child thereof, or an event which originated from such an element. These methods are also capable of looking up via a store item or ID; in the case of cell, a second argument indicating column ID would also be passed.

Expanding upon the examples above...

grid.on(".dgrid-row:contextmenu", function(evt){
    var row = grid.row(evt);
    // row.element == the element with the dgrid-row class
    // row.id == the identity of the item represented by the row
    // row.data == the item represented by the row
});

grid.on(".dgrid-header .dgrid-cell:click", function(evt){
    var cell = grid.cell(evt);
    // cell.element == the element with the dgrid-cell class
    // cell.column == the column definition object for the column the cell is within
    // cell.row == the same object obtained from grid.row(evt)
});

Custom events emitted by dgrid

Event name	Emitted by
dgrid-refresh-complete	OnDemand* and Pagination modules after grid has rendered (and after calling grid.refresh)
dgrid-error	OnDemand* and Pagination modules when an error occurs
dgrid-cellfocusin dgrid-cellfocusout	Keyboard module when keyboard navigation occurs
dgrid-sort	Grid module when a column is sorted
dgrid-columnresize	ColumnResizer module
dgrid-columnreorder	ColumnReorder module
dgrid-columnstatechange	ColumnHider module
dgrid-datachange	editor module when an editor field loses focus after being changed
dgrid-editor-show	editor module before placing a shared editor
dgrid-editor-hide	editor module before removing an editOn editor
dgrid-select	Selection module when one or more rows are selected
dgrid-deselect	Selection module when one or more rows are deselected