Grids in a SPA: Integrating JQGrid With Spring MVC and GSON

I was working on a single page application where I wanted to use the grid functionality in one part of the application which was using Spring MVC. It has been some time since I last used JQGrid and finding the information required to get me up and about was a bit of a challenge. On this post, I wanted to collate all the information and put it into a tutorial to follow so anyone who might be using the same functionality might find it helpful to set up JQGrid.

First of all, we will setup a sample web project on Eclipse and define the web.xml as follows:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" id="WebApp_ID" version="2.5">
  <display-name>JQGridExample</display-name>
  <welcome-file-list>
    <welcome-file>index.html</welcome-file>
    <welcome-file>index.htm</welcome-file>
    <welcome-file>index.jsp</welcome-file>
    <welcome-file>default.html</welcome-file>
    <welcome-file>default.htm</welcome-file>
    <welcome-file>default.jsp</welcome-file>
  </welcome-file-list>

  <servlet>
        <servlet-name>JQGridExample</servlet-name>
        <servlet-class>
            org.springframework.web.servlet.DispatcherServlet
        </servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>JQGridExample</servlet-name>
        <url-pattern>/</url-pattern>
    </servlet-mapping>

To wire up Spring MVC, I have registered the DispatcherServlet to be loaded on start-up. This is basically how you will register any Spring MVC application. Next up, we need to create the spring configuration to register the required components/elements of our spring MVC application.

In this instance, I have kept the spring context file name to the "servlet-name" given on my web.xml because by default when the spring container loads up, it will look for a file with the format <servletname>-servlet.xml

If you want to use any other name you want for your spring context configuration file, you can do so. You just need to register the context loader on your web.xml.

So let us see how our spring context configuration file looks like:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xmlns:context="http://www.springframework.org/schema/context"
 xmlns:mvc="http://www.springframework.org/schema/mvc"
 xsi:schemaLocation="http://www.springframework.org/schema/beans
 http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
 http://www.springframework.org/schema/mvc
 http://www.springframework.org/schema/mvc/spring-mvc-3.2.xsd
 http://www.springframework.org/schema/context
 http://www.springframework.org/schema/context/spring-context-3.0.xsd">

    <context:component-scan base-package="com.example.jqgrid.controller" />
     <bean id="multipartResolver" class="org.springframework.web.multipart.commons.CommonsMultipartResolver"/>
    <bean id="viewResolver" class="org.springframework.web.servlet.view.InternalResourceViewResolver">
    <property name="prefix" value="/WEB-INF/jsp/" />
    <property name="suffix" value=".jsp" />
    </bean>

    <mvc:resources mapping="/resources/**" location="/resources/"/>


    <mvc:annotation-driven/>

</beans>

We first register the package that contains all our controller classes. In this instance, it will be just one controller. With the component-scan element, it will scan all classes under the "controller" package.

Next up, we tell the Spring container how to resolve our JSP files. In this instance, the internal view resolver is being used and we provide the location of where our JSP files reside on the application.

The next interesting part of this configuration is the <mvc:resources> element. The reason to define this is to let the Spring container know about our static resources such as the javascript files, images, stylesheets. If we do not define them as resources, whenever you refer a javascript file for example in your application, spring MVC will try to match an existing controller by looking at the defined URL patterns. In this case, all my CSS, javascript, image files reside under the resources folder.

I then define the index.jsp which is the entry point into our application. Now I do not want to do anything on this page and I simply re-direct it to a different page which is resolved via spring-mvc. Our index.jsp file is as follows:

<script type="text/javascript">
 window.location.replace("jqGridExample");
</script>

I am simply re-directing the URL to jqGridExample. Now to understand how this is resolved from spring-mvc, we will need look at our controller class. Our controller class is as follows:

package com.example.jqgrid.controller;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;

import com.example.jqgrid.common.util.JsonUtil;
import com.example.jqgrid.dto.JQGridDTO;
import com.example.jqgrid.dto.SuperHeroDTO;
import com.example.jqgrid.handler.JQGridHandler;

/**
 * This class acts as the controller for JQGrid related functionality.
 * 
 * @author Dinuka Arseculeratne
 * 
 */
@Controller
public class JQGridController {

 /**
  * This method will display the page used to display the grid.
  * 
  * @param req
  * @param res
  * @return
  */
 @RequestMapping(method = { RequestMethod.POST, RequestMethod.GET }, path = "/jqGridExample")
 public String jqGrid(HttpServletRequest req, HttpServletResponse res) {
  String forward = "jqgrid/jqGridData";

  return forward;
 }

 /**
  * This method will handle fetching data required for the JQGrid.
  * 
  * @param req
  * @param res
  * @return
  */
 @RequestMapping(method = { RequestMethod.POST, RequestMethod.GET }, path = "/loadData")
 public String loadData(HttpServletRequest req, HttpServletResponse res) {
  String forward = "common/formData";

  JQGridDTO<SuperHeroDTO> gridData = new JQGridHandler().loadSuperHeroes(req);
  req.setAttribute("formData", JsonUtil.toJsonObj(gridData));
  return forward;
 }

}

So if we look at the first method, you can see we simply return a text called "jqgrid/jqGridData". Now to understand what this does, we need to go back and look at our spring context configuration file. In that, we specified that all our JSP files reside in the "WEB-INF/jsp" folder and the suffix is ".jsp". So in this instance, the path we return from this method tells the spring container that the JSP to be returned is in fact in "WEB-INF/jsp/jqgrid/jqGridData.jsp". Note that we did not need to specify the suffix as ".jsp" because we already configured that on our spring context configuration.

We will come back to the second method after we look at our page where we have defined the JQGrid. The jqGridData.jsp is as follows:

<!DOCTYPE html>
<html>
 <head>
  <title>JQGrid Example</title>


    <link href="resources/css/jquery-ui.css" rel="stylesheet">
    <link href="resources/css/jquery-ui.theme.css" rel="stylesheet">
    <link href="resources/css/jquery-ui.structure.min.css" rel="stylesheet">
    <link rel="stylesheet" href="resources/css/ui.jqgrid.css">

 </head>

<body>

<div>

   <table id="list">
                <tr>
                        <td />
                </tr>
        </table>
        <div id="pager"></div>
        <div style="margin-top:10px;">
        <input type="button" id="showSelected" value="Show Selected"/>
        </div>


</div>

  <script src="resources/js/jquery-1.11.1.min.js"></script>
  <script src="resources/js/jquery-ui.min.js"></script>
  <script src="resources/js/i18n/grid.locale-en.js"></script>
  <script src="resources/js/jquery.jqGrid.min.js"></script>


<script type="text/javascript">

 $(document).ready(function(){
  $("#list").jqGrid({
                url : "loadData",
                datatype : "json",
                mtype : 'POST',
                colNames : [ 'Name','Alias','Super Power'],
                colModel : [ {
                        name : 'name',
                        index : 'name',
                        width : 150
                }, {
                        name : 'alias',
                        index : 'alias',
                        width : 150,
                        editable : false
                }, {
                        name : 'power',
                        index : 'power',
                        width : 550,
                        editable : false
                }],
                pager : '#pager',
                rowNum : 10,
                height: 'auto',
                rowList : [ 10 ],
                sortname : 'invid',
                sortorder : 'desc',
                viewrecords : true,
                gridview : true,
                multiselect: true,
            multiboxonly: false,
                caption : 'Super Heroes',
                jsonReader : {
                        repeatitems : false,
                }
        });
        jQuery("#list").jqGrid('navGrid', '#pager', {
                edit : false,
                add : false,
                del : false,
                search : false
        });


        $('#showSelected').on('click',function(){

         var selRowArr = jQuery("#list").getGridParam('selarrrow');
         var selectedAppIds = [];
         for(var i=0;i<selRowArr.length;i++){
          var celValue =  $('#list').jqGrid('getCell', selRowArr[i], 'alias');
          selectedAppIds.push(celValue);
         }
         alert(selectedAppIds);
         $('#list').trigger( 'reloadGrid' );


        });

 });
</script>

</body>
</html>

First of all, we need to define the element on which the JQGrid will be loaded. In this instance, that is the HTML table element with the id of  "list". And since we want the pagination ability, we define our pagination section below the grid. In this instance, the pagination section is defined with the div with the id of "pager".

We then look at the javascript code as the bottom. Here we load the JQGrid by calling the method jqGrid() passing in the required attributes. I will not be explaining all the attributes defined here as there are many more which I have not used in this instance. The most relevant attributes for this tutorial will be explained. So first off, the URL. This is defined as "loadData". We need to go back our controller class to understand how this is mapped.

On the controller, we have defined the second method as "loadData" which fetches the data required for the grid. Now the interesting part is, JQGrid expects the data sent across in a particular format. To adhere to this format, I have defined a class to hold this structure which is defined as JQGridDTO. Let us see how that class looks like:

package com.example.jqgrid.dto;

import java.io.Serializable;
import java.util.List;

/**
 * This class acts as common template for all pages that use the JQGrid.
 * 
 * @author Dinuka Arseculeratne
 * 
 * @param <T>
 */
public class JQGridDTO < T extends Serializable > {

    private int page;

    private String total;

    private String records;

    private List<T> rows;

    public int getPage() {
        return page;
    }

    public void setPage(int page) {
        this.page = page;
    }

    public String getTotal() {
        return total;
    }

    public void setTotal(String total) {
        this.total = total;
    }

    public String getRecords() {
        return records;
    }

    public void setRecords(String records) {
        this.records = records;
    }

    public List<T> getRows() {
        return rows;
    }

    public void setRows(List<T> rows) {
        this.rows = rows;
    }

}

This is the structure of the data required by JQGrid. I have kept the rows data structure generic in order to be able to use this same class to pass different types of data to the grid as required. It can be any type of object as long as it implements the Serializable interface.

So I am a big time superheroes fan, and hence, in this instance, I will be displaying some information on some of the superheroes. I have included superheroes from both the DC and Marvel universe to keep everyone happy.

So let us look at our data object and the handler class which will load our data:

package com.example.jqgrid.dto;

import java.io.Serializable;

/**
 * 
 * @author Dinuka Arseculeratne
 *
 */
public class SuperHeroDTO implements Serializable {

 /**
  * 
  */
 private static final long serialVersionUID = 1420635747715993129L;

 private String name;
 private String alias;
 private String power;

 public SuperHeroDTO(String name, String alias, String power) {
  this.name = name;
  this.alias = alias;
  this.power = power;
 }

 public String getName() {
  return name;
 }

 public void setName(String name) {
  this.name = name;
 }

 public String getAlias() {
  return alias;
 }

 public void setAlias(String alias) {
  this.alias = alias;
 }

 public String getPower() {
  return power;
 }

 public void setPower(String power) {
  this.power = power;
 }

}

package com.example.jqgrid.handler;

import java.util.LinkedList;
import java.util.List;

import javax.servlet.http.HttpServletRequest;

import com.example.jqgrid.dto.JQGridDTO;
import com.example.jqgrid.dto.SuperHeroDTO;

/**
 * The handler class used to fetch the data required.
 * 
 * @author Dinuka Arseculeratne
 *
 */
public class JQGridHandler {

 /**
  * This method will fetch the super hero list. Of course i have mixed and
  * matched DC and Marvel in order to keep peace on the universe.
  * 
  * @return
  */
 public JQGridDTO<SuperHeroDTO> loadSuperHeroes(final HttpServletRequest req) {
  /**
   * The page and rows are sent from the JQGrid component with the Ajax
   * query.
   * 
   */
  int page = Integer.valueOf(req.getParameter("page")).intValue();
  int pageSize = Integer.valueOf(req.getParameter("rows")).intValue();

  /**
   * I am not using the star index and end index in this case, but in an
   * ideal situation, you will be passing the start and end index to your
   * pagination SQL query.
   * 
   */
  int startIndex = page == 1 ? 0 : (pageSize * (page - 1));
  int endIndex = page == 1 ? pageSize : pageSize * page;
  int total = -1;

  JQGridDTO<SuperHeroDTO> jqGridData = new JQGridDTO<SuperHeroDTO>();
  List<SuperHeroDTO> superHeroList = new LinkedList<SuperHeroDTO>();
  SuperHeroDTO flash = new SuperHeroDTO("Barry Allen", "Flash", "Super speed, Taping into the speed force");
  superHeroList.add(flash);

  SuperHeroDTO superMan = new SuperHeroDTO("Clark Kent", "Superman", "Flying, super speed");
  superHeroList.add(superMan);

  SuperHeroDTO batman = new SuperHeroDTO("Bruce Wayne", "Batman", "Cool toys, Intelligence");
  superHeroList.add(batman);

  SuperHeroDTO professorX = new SuperHeroDTO("Professor Xavier", "Professor X", "Mind control");
  superHeroList.add(professorX);

  /**
   * The total in the ideal situation would be the count of the records of
   * your SQL query from the table you want to fetch data from.
   * 
   */
  total = superHeroList.size();

  jqGridData.setPage(page);
  jqGridData.setTotal(String.valueOf(Math.ceil((double) total / pageSize)));
  jqGridData.setRecords(String.valueOf(total));
  jqGridData.setRows(superHeroList);
  return jqGridData;
 }
}

Typically you will be using a database to fetch your data. To maintain the brevity of this tutorial, I have just loaded up static data. On the code comments, I have mentioned how you would be passing the data when using an actual database.

In this instance, the JQGrid is set up to receive the data in JSON format. So to convert our superhero object to its JSON equivalent, I have used Google's GSONlibrary. I wrote a helper class to convert JSON objects to Java objects and Java objects to JSON objects which I have shared in one of my previous articles which you can find here.

I have not used the spring-mvc default functionality to send a JSON response. In this example what I do is set the JSON output in a request attribute and then forward the page to a common page where it just prints out that attribute and the response is sent back on the Ajax request made by the JQGrid component. This common page is defined as follows:

<%=request.getAttribute("formData")%>

Going back to our JSP file which defined the JQGrid, the next important attribute I want to focus on is the "colModel". This maps the data sent to your JSON output to the grid columns that are displayed. In this instance you can see the names mentioned here are the instance variable names defined on our superhero data object. The rest of the attributes are self-explanatory so I will not delve into the details on those attributes.

Another important use case I required was to be able to send the selected rows to the back-end. To do this, you can use the in-built JQGrid functions. The following code shows the code which retrieves the name of the superhero on all selected rows (in this case as the multi-select feature is enabled on the grid) and puts it into a Javascript array.

 $('#showSelected').on('click',function(){

         var selRowArr = jQuery("#list").getGridParam('selarrrow');
         var selectedAppIds = [];
         for(var i=0;i<selRowArr.length;i++){
          var celValue =  $('#list').jqGrid('getCell', selRowArr[i], 'alias');
          selectedAppIds.push(celValue);
         }
         alert(selectedAppIds);
         $('#list').trigger( 'reloadGrid' );   

        });

And that ends by a tutorial on how to setup JQGrid with Spring MVC and Gson. The working code is checked into my GIT repository and can be found here. You can clone the repository if required and run the application.