Gridx in XPages – 12: Adding Event Handlers and Opening a Document

In the last post, I showed how to use the Gridx API to get information about rows, columns, and cells. In this post, I’ll show how to attach an event handler and use that information to open a document by double-clicking on a grid row.

Gridx Series

Gridx in XPages — Entire Series

Available Event Handlers

Gridx provides a number of events for several regions and 4 different ways to add event handlers.

Events

• Click
• DblClick
• ContextMenu
• MouseOver
• MouseOut
• MouseDown
• MouseUp
• KeyDown
• KeyUp
• KeyPress

Regions

• Row
• Cell
• Header
• HeaderCell
• RowHeaderHeader
• RowHeaderCell

The general naming convention is “on” + region + event. In our example, we want to trap the row double click event, so we would listen for onRowDblClick.

Attaching an Event Handler

You can attach an event handler using dojo.on(), grid.on(), dojo.connect(), or grid.connect()

Note that there’s a slight difference in naming based on whether you use on() or connect() — if you use on(), then you can omit “on” from the event name (rowDblClick rather than onRowDblClick)

The documentation suggests that you use grid.on() or grid.connect() because they will be cleaned up as the grid is destroyed, so there’s less chance for a memory leak.

Event Object

When an event handler is triggered, it provides an object with a number of useful properties for determining the location of the click so you can take appropriate action. The properties of the object vary based on the context, but some of the common properties are the rowId, rowIndex, columnId, columnIndex, and cellNode (DOM node of the current cell).

To access the object, include a parameter in your event handling function (the name is up to you) and use that to access the properties.

Opening a Document on Row Double Click

To open a document based on a row double click, we’ll use the row ID to get a handle to the related item in the data store, as shown in the last post.

grid.connect(grid, "onRowDblClick", function(eventInfo) {
  var unid = grid.row(eventInfo.rowId).item()['@unid'];
  location.href = "MyPageName.xsp?action=openDocument&documentId=" + unid;
}); 

Line 1 adds the event listener to the row double-click event.

Line 2 uses the event object to get the row ID and then uses that to retrieve the item from the data store and get the ‘@unid’ attribute.

Line 3 builds the new url to open an XPage and include the document UNID in the URL.

Note: Compiler throws an error on the location.href line related to &documentId. Needed to move the code from a tag on the page into an xp:outputScript tag.

This is better anyway, because the code within tags often gets reformatted and broken when other areas of the page are updated.