When I hear about a new technology, I can’t wait to get my hands on it. Rather than just dabbling around a handful of examples, I tend to gravitate towards things for which I can see a real world application that provides added value and novelty. I recently had such an opportunity and spent a few days building a quite simplistic project management tool using jqGrid. I ran into more ‘gotchas’ and ‘what-have-yous’ than I’d care to remember this soon – most of which had nothing to do with jqGrid or jQuery – and everything to do with the framework I was using, CodeIgniter. As well, these issues did not have solutions commonly available due to the uniqueness of my environment – so I figured I’d share my experience in hopes of saving another poor soul a few hours of tromping through the plug-in bog.

1. Passing Data from Server to Client is Non-Trivial

Native jqGrid uses an encoded URL (GET method) to transport data, CodeIgniter uses POST. This means that you can’t enable CodeIgniter to handle jqGrid without breaking the rest of the CodeIgniter functionality, although uri queries are permitted. So all those cute little examples where the server-side code is simply

$conditions = $_GET[“conditions”];

or

jQuery(“jqGrid”).jqGrid(“setGridParam”,
{url:”+=&qid=”+ currRow.id”});

You can forget about. There is no easy solution to this predicament.

For simple form events, mainly covered by the navigation bar such as add, edit, delete – overriding the beforeSubmit event allows you to in effect circumvent the native posting method and make your own posting call such as:

beforeSubmit:function(postdata, formid){
   postdata[“foo”] = $(“#someFormField”).value;
   $.post(“someUrl.php”, postdata);
   return[true, message];
}

I ended up going with using uri segments to pass information back to the server on the more complex events, such as master-detail grid interactions, because the postdata object is available in the same format for every event type. To achieve this without exposing the data being transferred, and to keep the SEO Engineers quiet, uri routes should be established.

Note:

• the postdata for a Form Event is the data object of the selected row
• the postdata for a Grid Event is the pagination and grid id information

Keep this in mind when you are overriding event methods and manipulating the post data object prior to posting back to the server.

2. Leverage the Navigation Bar

There is a lot of time spent on firing off and handling row & cell events in the jqGrid documentation and I’m not sure why. For basic data manipulation the jqGrid already decorates the navigation bar with cleanly themed buttons that show forms for editing, adding, deleting, viewing, and even searching. All you need to do is set the properties to ‘true’ when creating the navigation bar (which only a couple examples fully implement) like this:

jQuery("#rowed2").jqGrid('navGrid',"#prowed2",
{edit:true,add:true,del:true});

• Note: to correctly post to the server, you’ll most likely have to override the beforeSubmit method for each of these options by replacing true or false with a {property₁:value₁,property₂:value₂} list.

It is much better esthetically and programmatically to leverage these built in features rather than adding clunky in-line buttons like the Row Editing -> Custom Edit example available on trirand.

3. Leave Out the Whitespace in the Column Model

I spent too many thought cycles on figuring out why my edit options were not being persisted to the database, only to realize that I was using a set in MySQL and that I had whitespaces between the semicolon and next edit option in my column model.

A quick fix confirmed that jqGrid parses the entirety of the string from the colon after the key value until the semi-colon ending the option value without discretion.

4. Column Model Options are Your Friend

The column model exposes a wealth of customization properties for each field of the jqGrid, two of which are the formatter and edittype properties. Both of these properties generally accept form input types and correctly modify the UI representation of the data to be concurrent. They essentially allow you to make a Boolean field look, feel, and interact via a checkbox.

Although you’ll probably learn it quickly, the formatter property controls the data format within the jqGrid, while the edittype property controls what the data column looks like when an edit, add, or view dialog is displayed.

5. It’s the Documentation, Stupid

The jqGrid documentation wiki is one of the most robust plug-in resources I’ve seen in a long time.

Use it.

I began working off the examples available on the jqGrid Demos page and didn’t realize the flexibility of the package. Sure the interactive examples are fun to play with, but it wasn’t until I really dug into the documentation to make it work in Code Igniter that I realized the customization available in the column model and navigation bar.

I have yet to find an intricate example implementing this technology and I really could not see building a test project to such an extent without hiking up my skirt and jumping into the deep end of the pool.

Various Other Helpful Code Bits

One of the most interesting, and I use that term loosely, things about the jqGrid documentation is that some functionality is described and demonstrated in the jqGrid Demos section of trirand’s site, and some is covered in the jqGrid wiki. It was only by cross-referencing both of these resources that I found all the information I needed.

Get data from currently selected row in the grid with id of list5

var id = jQuery("#list5").jqGrid('getGridParam','selrow');
if (id)
{
var selectedRowData = jQuery("#list5").jqGrid('getRowData',id);
}

To Make a Field Visible in jqGrid, but not Visible (editable) in Form, set the colModel option editable to false.

editable:false;

To Pass data without Viewing Field in jqGrid or edit Form, set the colModel editable option to false, and the hidden option to true. In this way you can inform the page of data about records without being required to expose it to the end user.

editable:false; hidden:true;

For general usage of the jqGrid, there is another useful resource I found here documenting another’s trials and tribulations with jqGrid.