Gridx in XPages – 26: Column and Row Locking

Another handy feature of Gridx is the ability to lock one or more columns or rows in place while you scroll through the grid. It’s similar to the Freeze Panes feature of Excel, although you can only lock one or the other at a time. In this post, I’ll show how to implement column and row locking.

Gridx Series

Gridx in XPages — Entire Series

Column Locking

When you lock one or more columns, they remain in place on the left side of the grid, while the rest of the columns can scroll horizontally.

In this screen shot,the first two columns are locked, so I can see the person’s name as I scroll through the rest of the columns. The horizontal scroll bar does not appear beneath the locked columns.

As with most Gridx features, column locking is very simple to implement.

1. Include the ColumnLock module in your require statement (gridx/modules/ColumnLock)
2. Add it to the grid’s modules list
3. Add a property to the grid to define how many columns to lock by default:

grid = new Grid(
{
  id: "my_gridX",
  cacheClass: Cache,
  store: store,
  structure: columns,
  vScrollerBuffSize:10,
  columnLockCount: 2,
  modules: [
    Resizer,
    VirtualVScroller,
    ColumnLock,
    colSelect,
    colMove,
    colDnD
  ]
});

You can also programmatically change the number of locked columns or clear all column locking.

This statement will lock the first 3 columns in the grid:

grid.columnLock.lock(3)

This statement will clear column locking (Note: There’s an article in the documentation that lists this method name incorrectly):

grid.columnLock.unlock();

If you have column drag and drop in place, you can even rearrange columns and then lock them based on the new arrangement, which gives you a lot of flexibility.

Row Locking

Row locking works pretty similarly, just not nearly as well.

In this example, I’ve set it up to lock the first two rows while the rest of the rows scroll.

The implementation is almost identical to column locking:

1. Include the ColumnLock module in your require statement (gridx/modules/RowLock)
2. Add it to the grid’s modules list
3. Add the rowLockCount property to the grid to define how many columns to lock by default

There are similar methods to programmatically lock and unlock rows.

grid.rowLock.lock(3);
grid.rowLock.unlock();

Caveat – Row locking only works propertly when virtual scrolling is not used. When virtual scrolling is used, it ends up leaving blank space at the top of the grid when the locked rows go out of scope as the data scrolls.

Column and Row Locking Together

I tried implementing Column and Row locking together, but it does not work. The grid can’t even load without a JavaScript error saying that a script needs to be stopped. (I tested in current Firefox, Chrome, and IE).

Ultimately, column locking works well, but it seems to me that it’s better to leave the row locking alone.