Gridx in XPages – Using djConfig to Make the Code Available

The last post covered some of the benefits of using Gridx, but before we can create a Gridx grid in XPages, we have to make the code available to the application. In this post, I’ll show how to use djConfig to make the code available to the NSF. This is not only the key to allowing Gridx to work, but the concept will allow other Dojo libraries to be included as well.

Update – A Simpler Method

The code below works as shown, but a simpler method for making the Gridx code available to the application is described here.

Gridx Series

Gridx in XPages — Entire Series

Dojo Version Required

Gridx uses AMD-style module loading, so it seems to need Dojo 1.7 or higher. The documentation says that it works best with 1.8.0 or higher. Notes 9 ships with Dojo 1.8.1, so that is what I will be using for my testing and development.


Including Gridx in an application is different than including a module (as with the first step in using Dojo EnhancedGrid) because the modules for EnhancedGrid are already part of the standard Dojo installation, so the files are already on the server and just need to be included on the page to be available.

As with third-party JavaScript libraries, you can easily add the code to an NSF.

First, download gridx and extract it.

Rename the folder above core, modules, etc to just gridx (without the version number).
Gridx 2 - Directory Structure

Then, open your NSF if the Package Explorer view and drag the gridx folder into WebContent
Gridx 2 - WebContent Folder

Making the Code Available

The next step is making the code available to use within the application.

Dojo would generally look for the code in a sibling directory to dojo, so it would expect to find it in this directory structure:

  • dojo
  • dijit
  • dojox
  • gridx

This is the point where I was stuck the last time I tried this.

You can set up your own dojo installation on yoru server and reference it. While it works, it creates a bigger administrative burden to maintain it and update it and it leaves you operating with a different version than was intended with your current version of XPages. You could also go the route of OSGi plugin, but, at this point, I want to add the library to the application and use it like I do with any other JavaScript library.

djConfig modulePaths

The key to making it work like any other library lies in djConfig — the Dojo configuration object. There’s an attribute named modulePaths that can include a list of additional places (outside of the standard directory structure) to look for code.

Once this is configured, we can reference the Gridx code as thought it exists in the default Dojo structure.

Here’s an example from the Dojo documentation:

modulePaths: {'foo': '../../bar'}

Setting modulePaths in XPages

In XPages, you can set a djConfig property as an XPage or Custom Control property. Select the xp:view tag and go to the Properties view. Select All Properties > Data > Properties and click the + button to add a property.

The property name is xsp.client.script.dojo.djConfig

The property value should be something like this: modulePaths: {'gridx': '/myDB.nsf/gridx'}

But it doesn’t work. You get a "SyntaxError: invalid property id" error in the browser console.

Gridx 2 - ModulePaths Error

The issue is that the value is escaped incorrectly by XPages, so it doesn’t allow it to work.

Fortunately, Sven Hasselbach posted a workaroud for this type of problem. You can use the beforePageLoad event to write out a client-side JavaScript variable with the modulePath setting (like an XAgent) so that it can be referenced by the djConfig property.

// 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:
var exCon = facesContext.getExternalContext();
var response = exCon.getResponse();
var writer = response.getWriter();
writer.write("var modPaths = {'gridx':'" + gridxPath + "'}");

The lines 2-4 build a relative URL up to the .nsf. It then appends /gridx, because that’s where the directory is accessible starting with the WebContent folder.

Lines 9-14 write out a script tag with a client-side JavaScript variable named modPaths.

Now we can reference that modPaths variable in our djConfig property, because the code above runs before the page is loaded:

  <xp:parameter name="xsp.client.script.dojo.djConfig"

Here’s what the property (and related source code) looks like:

Gridx 2 - djConfig Property

Up Next

Now, the gridx code is available to our application. In the next post, I’ll show how to get a simple gridx grid loading.


6 responses to “Gridx in XPages – Using djConfig to Make the Code Available”

  1. Manuel Ruiz says :

    very interesting, I wioll follow your work, thanks

  2. Csaba Kiss says :

    There’s an extra curly brace at the end line 14 in the code.
    Thanks for the tutorial.

    • Brad Balassaitis says :

      Thanks for pointing that out. (It’s part of the javascript block in the beforePageLoad event, but it’s definitely confusing in this context and would throw it off if pasted into the event handler.)

Trackbacks / Pingbacks

  1. Gridx in XPages – 5: Modularizing Common Resources | Xcellerant - November 11, 2014

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: