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.
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.
Installation
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).
Then, open your NSF if the Package Explorer view and drag the gridx folder into WebContent
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.
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: 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");
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:this.properties>
<xp:parameter name="xsp.client.script.dojo.djConfig"
value="modulePaths:modPaths">
</xp:parameter>
</xp:this.properties>
Here’s what the property (and related source code) looks like:
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.
