Setting Up a Base JqGrid Parameters Class
Our team has been using JqGrid on a few projects now and I am really impressed with the ease of use and functionality it provides. Out of the box it gives us immediate benefits in the form of paging, sorting, and basic transformation of tables. ASP.NET MVC makes it easy to send and receive data from the grid without writing much code at all. In this post we will look at a basic class to handle the parameters passed from JqGrid in regards to current page, records per page, sort column, and sort order.
If you have worked with JqGrid before you will no doubt be familiar with the default parameters passed to any ajax request: "page", "rows", "sidx", "sord". As mentioned above, these parameters correspond to current page, records per page, sort column, and sort order respectively. The grid passes these parameters with every user interaction so that the server can respond with updated data. For example, if a user clicks a sortable column or changes the number of rows per page then the grid will make an ajax request sending in the updated parameter values.
With MVC model binding it is relatively easy to receive these values as four string parameters on our action method. The DefaultModelBinder will locate them and match them by name to the parameter names in our method. So we could end up with an action method signature similar to this:
public ActionResult GetJqGridData(string page, string rows, string sidx, string sord)
This is a good starting point and does highlight how well the DefaultModelBinder abstracts away request variables. We do not need to specify if these parameters are contained within the url structure, the query string, or the posted form. However, with a little configuration we can make this signature look much cleaner.
Let’s start by creating a class to model the data we receive from the grid. We’ll call the class JqGridArgs and provide public properties for each of the four data parameters. Here is what this class could look like:
public class JqGridArgs
{
public string Page { get; set; }
public string PageSize { get; set; }
public string SortColumn { get; set; }
public GridSortOrder SortOrder { get; set; }
}
There are a few things to notice in the above class example. Our property names do not exactly match the default JqGrid names. Our first three properties are declared as strings, but the SortOrder property is declared as a custom Enum. This is not a requirement, but simply provides some additional type safety. The enum, which is not shown, only declares two members with names of Asc and Desc representing ascending and descending respectively.
Our goal at this point is to replace our cluttered method signature above with a cleaner version that accepts our new JqGridArgs class as a single parameter. Luckily we are not very far off from making this happen.
As it stands now, our main problem is that we have a mismatch between the arguments the grid sends (page, rows, sidx, sord) and the property names in our new class (Page, PageSize, SortColumn, SortOrder). The DefaultModelBinder will be able to map Page correctly, but the other three will fail. One option would be to create our own custom model binder to handle this scenario. MVC provides the extensibility to do this, but luckily JqGrid makes it even easier.
The setup call to JqGrid provides numerous options, one of which allows you to specify the parameter names for the ajax requests. In our example, we simply need to tell the grid to use our parameter names instead of the default names. This allows us to rely on the DefaultModelBinder in MVC to handle all of the mappings for us. Here is a snippet of what this setup looks like:
$('#myGrid').jqGrid({prmNames:{rows:'pageSize', sort:'sortColumn', order:'sortOrder'}})
Now we can update our original method signature to contain one nicely defined object instead of four disjointed strings:
public ActionResult GetJqGridData(JqGridArgs gridArgs)
This implementation definitely isn't ground breaking, but it does provide a nice foundation. The class we created can serve as a base class for all of our grids. If necessary we can even inherit this class and append additional properties to match custom data being sent from the grid -- in the postData array for example. Check out the documentation for JqGrid and please feel free to let us know your tips for this great plugin!
