Gridx in XPages – 32: Editable Cell Widgets

In the last couple of posts in this series, I showed how to edit data inline and save the changes. But you’re not limited to plain text fields. In this post, I’ll show how to make cells editable with additional input widgets.

Gridx Series

Gridx in XPages — Entire Series

Adding Input Widgets

There are generally 3 steps to the process:

1. Include the CellWidget module
2. Include your chosen input widget module (if necessary)
3. Set the column properties to include and configure the widget

To add any kind of widget for inline data input, you need to first required the CellWidget module and add it to the grid.

To do so, include "gridx/modules/CellWidget" in the require statement (or at the page level) and then also include it in the grid’s modules list.

The next two steps will be specific to the widget that you choose. Below are examples of using a combo box, date picker, and number spinner.

Combo Box

The dijit.form.ComboBox module is automatically included within XPages, so you do not need to require it.

In this example, I’ve added it to the state column. Here’s the updated column definition:

{ id: 'state', field: 'state', name: 'State', width: '80px', 
  editable: true, 
  editor: 'dijit.form.ComboBox',
  editorArgs:{
    props:'store: stateStore'
  } 
},

• The editable property tells the grid that the column is editable
• The editor property tells the grid what widget to use when editing
• The editorArgs property is an object that includes properties required to configure the editor

The ComboBox requires a memory store with the list of choices, so that needed to be set up earlier in the code.

It uses the same MemoryStore module that’s already included for the grid to use. Each option must have a name and unique id.

Note: Do not declare the memory store object as a var. This causes the grid to not be able to find it.

stateStore = new MemoryStore({
  data: [
    {name:"FL", id:"FL"},
    {name:"GA", id:"GA"},
    {name:"IL", id:"IL"},
    {name:"NJ", id:"NJ"},
    {name:"PA", id:"PA"}
  ]
});

Now, when a cell in the State column is put into edit mode, there is a combobox with a list of choices to choose from.

Date Picker

If you want to let the user change a date value, it is very handy to include a date picker.

Here are the properties that I added to the date column in order to enable a date picker in my example:

  editable: 'true',
  editor: 'dijit.form.DateTextBox',
  editorArgs: {
    fromEditor: storeDate
  }

I didn’t have to require the dijit.form.DateTextBox module because it’s available already within XPages.

Since it’s a date field, I needed to add a fromEditor function to parse the data before it’s stored. (See this post on formatting date columns for more information on date parsing.)

This function will return a date string that works with the formatting code already on the column:

function storeDate(storeData, gridHandle) {
  if (typeof storeData == 'object') {		
    return storeData.toLocaleDateString();
  } else {
    return '';
  }
}

Number Spinner

For the last example, I added a NumberSpinner to a cell. This module is not automatically available in XPages, so it needs to be included.

One of the ways to do that is at the page level with a Dojo Module Resource:

<xp:this.resources>
  <xp:dojoModule name="dijit.form.NumberSpinner"></xp:dojoModule>
</xp:this.resources>

Now that the module is available to the page, it can be used for cell input.

In this example, I have a Rating column that has a number spinner that allows values from 1 to 5.

{ id: 'rating', field: 'Rating', name: 'Rating', dataType: 'number', width: '75px', 
  editable: true, 
  editor: 'dijit.form.NumberSpinner',
  editorArgs:{
    props: 'smallDelta: 1, constraints: {min:1, max:5, places:0}'
  } 
} 

There are many more options; hopefully, these examples make it much easier to implement any others that you need.