jqGrid Learnings

I have been using jqGrid for a few projects that was done using PHP. For anyone who does not know what jqGrid is, its a fully featured library that allows you to display and manipulate your data in tabular form. Saves you tons of time writing pure tables to handle and manipulate your data. It has two variants where one is the commercialized version (jqSuite) and the free version is maintained here. The API is very much verbose with a plethora of methods for almost anything you would ever want to do in a grid. This post will be aimed at use cases to which i used jqGrid and what changes i needed to do in order to get it working.

• Custom search on a button click

By default jqGrid sends a data search GET request on page load. It also has a refresh button in the bottom part. What i wanted was to send a GET request with the search parameters on a button click. To achieve this i first built the URL with the parameters as follows;

var length = jsPatientSearchCtrl.length;
var searchURL= "server.php?";
for(var i=0;i<length;i++){

 if($('#'+jsPatientSearchCtrl[i].id).val()!=''){

   searchURL+="&";
  
   searchURL+=jsPatientSearchCtrl[i].desc+"="+$('#'+jsPatientSearchCtrl[i].id).val();
   
 }
}

Here i am iterating through the JSON array i have defined to hold the data objects within my given page. After creating the URL with the parameters you have to tell jqGrid to reload the data as follows;

jQuery("#list2").jqGrid('setGridParam',{url:searchURL}).trigger("reloadGrid")

This will send another GET request to the server to reload the Grid with new data according to our changed search criteria when the user clicks on the search button.

• Editing grid data using a form submission

By default jQGrid provides the ability to edit the fields within our Grid by opening a dialog where by you can change the details for a given record and submit it. To do this, first you have to enable the edit option in your grid. You do this as follows;

jQuery("#list2").jqGrid('navGrid',
'#pager2',
{edit:true,add:false,del:true,search:false}
); 

Here i have enabled the edit option by setting the value to true and have disabled the add and search functionality as this was not required in my scenario. After that you need to define which columns you want to edit. You do this within your colModel parameter which you give when constructing your jqGrid. I present what i have used;

colModel:[ 
  {name:'Ref',index:'id', width:55,sortable:false,editable:false,editoptions:{readonly:true,size:10}},
  {name:'Identity',index:'patient_identity', width:90,sortable:false,editable:true,editoptions:{size:10}}, 
  {name:'Reference',index:'patient_identity', width:90,sortable:false,editable:true,editoptions:{size:10}}, 
  {name:'Date',index:'date', width:90,sortable:false,editable:true, editoptions:{size:10}}, 
  {name:'Time',index:'time', width:50,sortable:false,editable:true, editoptions:{rows:"1",cols:"10"}}, 
  {name:'Name',index:'patient_name', width:130,sortable:false,editable:true,edittype:"textarea", editoptions:{rows:"1",cols:"20"}}, 
  {name:'Referred',index:'referred_by', width:100,sortable:false,editable:true,edittype:"textarea", editoptions:{rows:"1",cols:"20"}}, 
  {name:'Blood',index:'blood_collected_at', width:120, align:"right",sortable:false,editable:true,edittype:"textarea", editoptions:{rows:"1",cols:"20"}}]

Important things to note here is that certain fields we have set editable:false which signifies that these values will not be able to be changed by the user when editing. To enable editing on a particular column we define it as editable:true. Optionally you can define a size. You do this using the editoptions attribute. For example as per the above code snippet, we have used editoptions:{size:10}  to give a size of 10 to that particular text field.

If you want to define a text area, this can also be achieved. Again revisiting the above code, we have done this using editiontype:"textarea",editoptions:{rows:"1",cols"20"}. There are many other types you can define such as check boxes etc. More info on the supported types in the edit option can be found here.

• Close the Add/Edit dialogs upon submit

By default the Add/Edit dialogs do not close after submitting the values. You have to press the close button yourself. It was required for me to close the dialog on submit. This was achieved as follows;

jQuery("#list2").jqGrid('navGrid',
'#pager2',
{edit:true,add:true,del:true,search:false}
,{width:500,closeAfterEdit: true},{width:500,closeAfterAdd:true}); 

As you can see within the code snippet, i have set the attribute closeAfterAdd  and closeAfterEdit  as true. This will close the Add/Edit dialog when the user clicks on the submit button.

Another thing to note here is that when you enable editing and adding, you need to specify to which URL the POST parameters on submit should be sent to. You do this as follows;

jQuery("#list2").jqGrid({
editurl: "editperson.php"
  });

Note that the data for add, edit and delete are sent to the same URL, so you need to identify the operation uniquely. jqGrid by default sets a parameter for us to distinguish this when sending the POST request to the URL we prodive in the editurl attribute. With PHP this is how we handle it;

 if(isset($_POST["oper"])){
 $operation = $_POST["oper"];
 
 switch($operation){
 case "del":
 break;
 
 case "add":
 break;
 
 case "edit":
 break;
 }
}

As you can see jqGrid by default sets a parameter named oper which defines which operation the data that is sent belongs to. So we can handle our logic according to whether its an add/edit or delete.

That is about it on use cases i have come across when using jqGrid. Some of the problems i faced were solved after some Google searching and putting together information gathered from various sources. Hence the purpose of this post was to put it altogether and provide a one-stop point for most of the common scenarios you might use jqGrid for.

Thank you for reading. Have a great day ahead.