Working with Events

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	Description
dgrid-refresh-complete	Emitted after grid has rendered (and after calling grid.refresh)
dgrid-error	Emitted by various modules when an error occurs
dgrid-cellfocusin dgrid-cellfocusout	Emitted by the Keyboard mixin when keyboard navigation occurs
dgrid-sort	Emitted when a column is sorted
dgrid-columnresize	Emitted by the ColumnResizer module
dgrid-columnreorder	Emitted by the ColumnReorder module
dgrid-columnstatechange	Emitted by the ColumnHider module
dgrid-datachange	Emitted by the editor module when an editor field loses focus after being changed
dgrid-editor-show	Emitted by the editor module before placing a shared editor
dgrid-editor-hide	Emitted by the editor module before removing an editOn editor