Gridx in XPages – 24: Adding Toolbars to the Grid

Gridx provides the ability to add a toolbar with buttons at the top and/or bottom of the grid. In this post, I’ll show how to implement it.

Gridx Series

Gridx in XPages — Entire Series

1. Include Required Modules

The Bar module is required for Gridx:
"gridx/modules/Bar",

(Note: There’s a ToolBar module defined, but it’s deprecated, so Bar is the one to use.)

A couple of dijit modules are also required for building the toolbar and adding buttons to it:
"dijit/Toolbar",
"dijit/form/Button",

2. Create An Event Handler

You’ll need to define an event handling function for each button in the toolbar. In this example, we’ll start with a simple logging statement just to see it work.

function myButtonHandler() {
  console.log('Clicked button');
}

3. Create the Toolbar

The next step is to create the Toolbar object and add a button to it.

var toolbar = new Toolbar({}, "toolbar");
var myButton = new Button({
  label:"Do Something",
  iconClass:"dijitIconFunction",
  onClick:myButtonHandler    
});
toolbar.addChild(myButton);
toolbar.startup();

Line 1 creates the Toolbar object.

Lines 2-6 create a Button.

Line 7 adds the button to the toolbar.

Line 8 generates the toolbar.

Dojo Icons

Dojo has a (limited) set of icons built in for use with buttons. In dijit buttons, they are defined by a class name (which uses CSS to get the proper section of an image sprite).

There are two set — common icons and editor icons. I have yet to find documentation with a simple list of images and their class names, but here are links to see the common icon sprite and editor icon sprite

Related CSS files define the area of each image. You can use a resource like this to see the class names in commonIcons.css or editorIcons.css.

4. Add the Toolbar to the grid

The last thing you need to do is add the toolbar to the grid object. This can be done via the barTop or barBottom properties. (Make sure that the Bar module is also in the grid’s modules list.)

In this example, it’s added to the top:

grid = new Grid(
{
  id: "my_gridX",
  cacheClass: Cache,
  store: store,
  structure: columns,
  vScrollerBuffSize:10,
  barTop: [
    toolbar
  ],
  modules: [
    Resizer,
    NestedSort,
    Filter,
    FilterBar,
    QuickFilter,
    VirtualVScroller,
    Bar
  ]
});

Note: If you try to add the same toolbar to the bottom and top, it seems to only appear at the bottom.

The structure of the barTop and barBottom is pretty flexible, so you can do much more than just add a single toolbar. Take a look at this article for information on how to add multiple items to a bar or even add multiple levels of bars.

Bar Content

Toolbars are not limited to buttons – you can use other dijits as well.

You can also pass through pure HTML like this:

barBottom: [
  { content: "<h1>HTML Stuff Here</h1>", style: "color: red;"}  
],