Dojo Data Grid – Part 30: The onStyleRow Event

In this post, I’ll dig into the onStyleRow event of the XPages Dojo Data Grid in order to show how it can be used to modify the display of grid rows. This will lay the foundation for the next few posts.

Dojo Data Grid Series

Dojo Grids in XPages — All Blog Posts

The onStyleRow Event

The onStyleRow event runs on each row in the grid as it is rendered. The event handler automatically receives one argument that has a number of properties that can be used to conditionally customize the display of the row.

By default, the grid will provide alternate row coloring and different styles when you select or hover over a row. This image shows all three of those styles in effect.

However, as soon as you add any code into the event handler, you lose the hover, selected, and alternate row styles. (In this case, I added a single comment to the event handler and it was still enough to cause other styles to be dropped.)

onStyleRow Argument Properties

The onStyleRow event automatically receives an object with information about the current row. It’s not a named argument, so we refer to it by arguments[0]. The properties of the row object are as follows:

• index (row index)
• node (DOM node)
• odd (boolean — whether the row is an odd-numbered row)
• selected (boolean — whether the row is currently selected)
• over (boolean — whether the row is currently hovered over)
• customStyles (used to add style information to the row)
• customClasses (used to add classes to the row)

The index property is the 0-based number of the row in the grid.

odd, selected, and over are boolean properties that are handy for changing styles for alternate rows and whether the row is selected or hovered over.

The customStyles property is used to add custom style information to the row. The customClasses property is used to add additional classes to the grid row.

The node provides a handle to the DOM node of the grid row.

Here’s an example of what it returns:

</pre>
<table class="dojoxGridRowTable" role="presentation" border="0" cellspacing="0" cellpadding="0">
<tbody>
<tr>
<td class="dojoxGridCell " style="width: 6em;" tabindex="-1" role="gridcell" colspan="1">...</td>
<td class="dojoxGridCell " style="width: 6em;" tabindex="-1" role="gridcell" colspan="1">...</td>
<td class="dojoxGridCell " style="width: 6em;" tabindex="-1" role="gridcell" colspan="1">...</td>
<td class="dojoxGridCell " style="width: 6em;" tabindex="-1" role="gridcell" colspan="1">...</td>
<td class="dojoxGridCell " style="width: 6em;" tabindex="-1" role="gridcell" colspan="1">...</td>
<td class="dojoxGridCell " style="width: 6em;" tabindex="-1" role="gridcell" colspan="1">...</td>
</tr>
</tbody>
</table>
<pre>

There are two interesting things to note. First of all, each row in the grid is actually its own table. Secondly, each cell in the row is initially populated with ‘…’. It then fills in the data from the REST service on a second pass.

This is important to understand — the onStyleRow event will generally run more than once on each row. Essentially, whatever settings are applied in the last pass are the ones that stick.

In my testing, it appears to run between 1 and 3 times on each row. It seems to most commonly run twice — once when it sets up the row and pre-populates every cell with ‘…’ and then a second time when it actually fills in the data. (I tested this by reviewing the full contents of the row node.)

It seems to run 3 times on the first chunk of rows displayed when the grid is first loaded. It only runs once one when the data has already been loaded or if the row is read-protected and thus cannot display any data.

Adding event code

I enter code for the onStyleRow event via the All Properties tab and not directly in the event view. Take a look at this post to see why this works differently.

Up Next

Now that we’ve explored what happens in the event and what’s available to it, the next couple of posts will show how to use the event to provide additional row styling.