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.


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


  • 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.


10 responses to “Gridx in XPages – 12: Adding Event Handlers and Opening a Document”

  1. dregos says :

    Hi! Is it possible to add a xsp eventhandler somehow? Because I open documents with dialogbox and url is not a good solution for me without having to put to much code on before page load.

    • Brad Balassaitis says :

      I think the best way to approach that would be to call a JSON RPC method to set the UNID in a scope variable (or wherever else you want to store it) and then, in the RPC callback, use client-side JavaScript to open the dialog box (XSP.openDialog)

  2. Kraeven says :

    The opening of a document is not working for me, can you display the complete source of the Xpages please? I must have done something wrong…

    • Brad Balassaitis says :

      I can’t paste any code into a comment without it being messed up. If you want to give me an e-mail address, I could send it to you.

      Aside from that, I’d troubleshoot the code by verifying the grid object variable name (line 1), adding an alert or console.log statement to check whether it is able to find the unid (line 2), verifying the proper page name (line 3).

      Hope this helps.

  3. Graeme Gilbertson says :

    Hi Brad – thanks for this series of blogs – very useful. Thanks also for your session with Paul at Connect 16, again very useful and something I am now taking forward.

    On this subject though – can you email me with the source for this as I cannot get the documents to open up. I know I am being dense but would appreciate a help-up on this.



  4. Graeme Gilbertson says :

    Got it working – just needed the change as shown…

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

  5. Graeme Gilbertson says :

    should be an ‘&’ before documentId

  6. Graeme Gilbertson says :

    argh!!! It is not showing the amp; after the &

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: