Gridx in XPages – Creating a Simple Grid

In the last post, I showed how to make Gridx available in an XPages application. In this post, I’ll show how to create your first Gridx grid in XPages.

Assuming you have already followed the steps in the last post, you are ready to create your first grid.

A Gridx grid requires the following:

• A data store
• A cache implementation
• Defining grid columns
• Defining the grid
• Placing and instantiating the grid

The example is a very simple one with hard-coded data. The goal here is to get a grid up and running so we can build upon it in future posts.

It starts with a script tag and code that uses Dojo AMD loading to include the required modules. In the code below, the Gridx/Grid module is loaded and given the name Grid; a dojo Memory store module is loaded and given the name Memory, and a synchronous cache module is loaded and given the name Sync. The dojo.domReady! module is also loaded — this causes the script to wait until the page is ready before executing.

<script> require([
  "gridx/Grid", "dojo/store/Memory",
  "gridx/core/model/cache/Sync", "dojo/domReady!"
  ], function(Grid, Memory, Cache) {

First, we need to set up the data store. This example uses a Memory store to hold hard-coded data.

var store = new Memory({
  data: [
    {id: 1, name: 'John', country: 'United States', things: 100},
    {id: 2, name: 'Bill', country: 'Lithuania', things: 57},
    {id: 3, name: 'Bob', country: 'China', things: 123},
    {id: 4, name: 'Jim', country: 'Germany', things: 154},
    {id: 5, name: 'Tom', country: 'Brazil', things: 78}
  ]
});

Next, we need to define the column structure for the grid. The field attribute maps to the name attribute of the data store. The name attribute of the column defines the column title to display. When a width is not defined, it appears that it will take up the remaining available width.

		
var columns = [
  {id: 'name', field: 'name', name: 'Name', width: '70px'},
  {id: 'country', field: 'country', name: 'Country'},
  {id: 'things', field: 'things', name: 'Things', width: '40px'}
];

Then, we need to define the grid object. The object takes the cache, data store, and column structure.

grid = new Grid({ 
  id: "my_gridX", 
  cacheClass: Cache, 
  store: store, 
  structure: columns 
}) 

Finally, we need to tell the grid where to be placed and then initialize it with the startup method.

		
//Put it into the DOM tree.
grid.placeAt('gridX_Here');
grid.startup();

The placeAt call needs the ID of an element where the grid should be generated.

This div tag on the page provides a place. IMPORTANT: The div must have a height defined, or it will end up at 0 and you won’t see anything. (This example defines it inline, but it’s better to use CSS.)

<div id="gridX_Here" style="height:300px; width:300px;">
</div>

CSS

The grid also requires a few stylesheets. This example uses the Claro theme. Those stylesheets can be loaded from the existing Dojo implementation on the server. The URLs use /.ibmxspres/dojoroot/, which tells the server to look in the root Dojo directory.

The third stylesheet is specific to Gridx and is loaded with a URL relative to the application’s WebContent directory.

<xp:this.resources>
  <!-- Claro Theme -->
  <xp:styleSheet href="/.ibmxspres/dojoroot/dijit/themes/claro/claro.css"></xp:styleSheet>
  <xp:styleSheet href="/.ibmxspres/dojoroot/dijit/themes/claro/document.css"></xp:styleSheet>
		
  <!-- -Main GridX Stylesheet  -->
  <xp:styleSheet href="gridx/resources/claro/Gridx.css"></xp:styleSheet>
</xp:this.resources>

Full Page Source

Putting this code together with the setup code from the last post, here is the full source of my sample page:

<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core">

  <xp:this.resources>
    <!-- Claro Theme -->
    <xp:styleSheet href="/.ibmxspres/dojoroot/dijit/themes/claro/claro.css"></xp:styleSheet>
    <xp:styleSheet href="/.ibmxspres/dojoroot/dijit/themes/claro/document.css"></xp:styleSheet>
		
    <!-- -Main GridX Stylesheet  -->
    <xp:styleSheet href="gridx/resources/claro/Gridx.css"></xp:styleSheet>
  </xp:this.resources>


  <xp:this.properties>
    <xp:parameter name="xsp.client.script.dojo.djConfig" value="modulePaths:modPaths"></xp:parameter>
  </xp:this.properties>

	<xp:this.beforePageLoad><![CDATA[#{javascript:// Get the relative URL up to the .nsf
var relativeUrl = context.getUrl().getPath();
var index = relativeUrl.indexOf('.nsf');
var gridxPath = relativeUrl.substring(0, index+4) + '/gridx';
	
// Write out a JS variable with the module path for djConfig
// This works around a problem of the property being improperly escaped.
// Solution by Sven Hasselbach: http://stackoverflow.com/questions/13720849/djconfig-in-xpages-escapes-values-making-the-setting-wrong
var exCon = facesContext.getExternalContext();
var response = exCon.getResponse();
var writer = response.getWriter();
writer.write("<script>\n");
writer.write("var modPaths = {'gridx':'" + gridxPath + "'}");
writer.write("\n</script>\n");}]]>
</xp:this.beforePageLoad>

  <script> require([
    "gridx/Grid", "dojo/store/Memory",
    "gridx/core/model/cache/Sync", "dojo/domReady!"
    ], function(Grid, Memory, Cache) {

    var store = new Memory({
      data: [
        {id: 1, name: 'John', country: 'United States', things: 100},
        {id: 2, name: 'Bill', country: 'Lithuania', things: 57},
        {id: 3, name: 'Bob', country: 'China', things: 123},
        {id: 4, name: 'Jim', country: 'Germany', things: 154},
        {id: 5, name: 'Tom', country: 'Brazil', things: 78}
      ]
    });
		
    var columns = [
      {id: 'name', field: 'name', name: 'Name', width: '70px'},
      {id: 'country', field: 'country', name: 'Country'},
      {id: 'things', field: 'things', name: 'Things', width: '40px'}
    ];

    grid = new Grid({ 
      id: "my_gridX", 
      cacheClass: Cache, 
      store: store, 
      structure: columns 
    }) 
		
    //Put it into the DOM tree.
    grid.placeAt('gridX_Here');
    grid.startup(); 
  });
  </script>

  <div id="gridX_Here" style="height:300px; width:300px;">
  </div>
</xp:view>

If you’ve include gridx in your WebContent folder as shown in the last post, you should be able to copy this source into an XPage and load a grid.

It doesn’t do anything yet, but we’ll add features soon.

Up Next

In the next post, we’ll look at loading live data from a Notes application via a REST service.