jqGrid RESTful URL formatter

jQuery seems to have become ubiquitous these days and if you want a scrolling, paging, dynamic grid then jqGrid is an excellent plugin. I’ve been using it in my project with a RESTful JSON web service to return the grid content and I needed a way to format the ID column into a URL. First I had a look at the documentation to see what jqGrid has out of the box.

There is a formatter called ‘link’ or ‘showLink’ but it didn’t quite work as I wanted as it forces you to use a URL of the form site.com/page?id=1. My application is using RESTful URL’s so I wanted something more like site.com/page/1. This left me with a couple of options.

  1. Format the URL on the server and return it from the JSON web service
  2. Create a custom formatter

For me 1 was out of the question because this was a formatting issue that belonged in the view layer. My JSON is being returned as a POJO from a spring controller. The conversion to JSON is handled automatically by Jackson. So you can see I didn’t really want this URL formatting going on in the controller, or worse the model layers.

This is the custom formatter I created for this purpose.

jQuery.extend($.fn.fmatter , {
RESTfulLink : function(cellvalue, options, rowdata)
{
var opts = options.colModel.formatoptions.url;
if(typeof opts == 'string')
{
return '<a href="'+opts + cellvalue+'">'+cellvalue+'</a>';
}else{
return cellvalue;
}
}
});

The first line allows us to create a formatter by extending jqGrid. It is also possible to create a formatter as a standalone function but I can’t see any reason why you would need to do this. The rest is standard JavaScript defining a formatter called RESTfulLink. The parameters are the standard parameters required for a formatter function. This can all be found on the jqGrid wiki.

The interesting part that isn’t mentioned in the documentation, or anywhere else I could find, is how to access a formatter option. This might make more sense once we’ve seen how you use this formatter.

<script>
  jQuery("#grid_id").jqGrid({
  ...
     colModel: [
      ...
     {name:'id', index:'id', width:60, align:"center", editable: true, formatter:'RESTfulLink', formatoptions:{url:'site.com/page/'}},
      ... ]
   ... });

We select the formatter in the same way as any of the standard ones. Note that if we’d done this is a standalone function instead of extending jqGrid then the quotes would have been dropped. E.G. formatter:RESTfulLink. The data we need to create the link has been passed in using the formatoptions object. I’ve created a custom parameter called url but since JavaScript is dynamically typed you could pass in whatever you want.

If you look back at the custom formatter you should see the url parameter being used to construct the URL by appending the contents of the ID column to whatever the URL is. I couldn’t find this documented anywhere so I ended up debugging my function and inspecting the parameters passed in. Otherwise there’s no way I would have guessed it would be options.colModel.formatoptions.url!

So that’s my first proper post, I hope it makes sense. Please leave a comment if you liked it or to suggest an improvement.

Thanks

Ben