10 JQGrid Tips learned from my experience

For the past few days I have been working with JQGrid, one of the most powerful JQuery plug-in.  To give an outline, JQGrid helps us to create a grid with ease. The power of JQGrid comes from the fact that almost all the needs for a grid are addressed using simple tunable options. JQGrid can be downloaded fromhttp://www.trirand.com/blog/?page_id=6.  JQGrid has a good documentation available at http://www.secondpersonplural.ca/jqgriddocs/index.htm. Also most of the JQGrid options are demonstrated well in http://www.trirand.com/jqgrid35/jqgrid.html. In spite of these well written documents, there are times I spent digging JQGrid source code for some customization needs. I also strongly feel that most of my co-workers might need the same at some point of time, so thought of blogging (documenting) for further reference.

All the code used in this article can be downloaded from here.

Our very first table looks as below

TIP 1: Changing JQGrid width and height

As depicted in the picture, the table doesn’t show up with paging information. Due to the smaller width, the 2^nd column header and value are also not fully visible.  To solve this, we need to set the width of the table, thereby columns. This can be achieved as shown below

1. During grid creation, use the property width with value in pixel as

1

width:700

OR

2. After grid creation, use setGridWidth(width, shrink) API as

1	$([tableid]).setGridWidth(700,true);

Similarly, height of the table can also be set using height :<value is pixel> and setGridHeight(height) API.  The default height is 150px. I am still searching for a way to set width/height of JQGrid in percentage (%). Comment, if you already know it.

TIP 2: Grid without unnecessary scroll area

If you are sure that the grid is not going to take more than N values and those N values can be fit in a single page, then there is no need for a scroll bar. In this case the space allotted for scrollbar is immaterial. I would rather prefer to remove this space. This can be achieved by setting the value of scrollOffset to zero as follows,

1


scrollOffset:0






By default the value of scrolloffset will be 18px

TIP 3:  Error due to missing locale file

You have included all the needed JS files like, JQuery, jqgrid (single file as minimized js/jquery.jqGrid.min.js) but still hitting with an error “$.jgrid is undefined” and grid is not rendered. This might be due to missing locale file. To solve this include appropriate locale, as




1


<script src="jqgridsrc/src/i18n/grid.locale-en.js" type="text/javascript" charset="utf-8"></script>






TIP 4: Callback function

We came across a requirement where we need to associate a hover event only to the first cell of a grid. To do the same, we need to get the first cell (td) and associate hover function on it and then implementing the functionality needed. Let’s assume that these functionalities (writing selector to get the first cell and writing .hover(…) function) is available in a function named doWhenHover(). The point here is when to call this function? THINK !! THINK !! THINK !!

If you told that it should be after the function that creates the table, in our example createMyTable(), then you are wrong.  Since the grid is not guaranteed to be completely formed at the end of createMyTable() function. So, JQGrid provides a callback function, loadComplete to which a function can be associated during grid creation like,




1

2

3

4

5

6

7

8

9

10

11


loadComplete: doWhenGridFullyLoaded



….



//grid creation completed



function doWhenGridFullyLoaded(){



//do the operation here



}






TIP 5: Using pagers only for buttons (or icons)

JQGrid documentation provides a tip at http://www.secondpersonplural.ca/jqgriddocs/index.htm under jqGrid > User Modules > Tips, Tricks and Hacks using which pager can be removed.  Here is yet another way to do the same. If you want to have pager only to add buttons and don’t like to display page numbers and other stuffs then we could remove those items as shown below,




1

2

3

4

5

6

7


$(‘#

<pagername>_center’).remove();



$(‘#

<pagername>_right’).remove();



Example: $('#mysimpletablepager_right').remove();






TIP 6: Hiding unwanted buttons in navigation bar

When navGrid(…) API is called to add a icon, say refresh  as




1

2


$(‘#

<tableid>’).navGrid('#mysimpletablepager',{refresh:true});






the following icons will be added in addition to the refresh icon

edit, add, del, refresh, search

To hide any of these icons associate those icons to a value of false. Say for example to hide edit, add icons and show other icons we can use the following fragment of code




1

2


$(‘#

<tableid>’).navGrid('#mysimpletablepager',{edit:false,add:false});






Also, by default view icon will be hidden, this can be made visible by associating true to it as view:true

Tip 7: Hiding the inline search by default

In addition to the popup search in JQGrid there is also an additional option of having inline search. In this case, a search textbox will be added to top of each column. Refer JQGrid documentation for the procedure to add inline search. But, when we add inline search functionality the search textbox will be shown by default and it occupies the first row below the header.  Though it can be argued that, showing search textbox by default makes the functionality explicit to user, I like it to be the other way i.e. when the grid is loaded the search textbox has to be hidden. User can make explicit request to show the search textbox. To do the same call mygrid[0].toggleToolbar() (the same code that is called when inline search icon is clicked) at the end of grid creation code as follows,




1

2

3

4

5

6

7

8

9

10

11

12

13

14


var myGrid = $(‘#mysimpletable’).jqGrid({



     url:<value>,



    ….//.other options



   })



.navButtonAdd("<

<pagerid>>",{caption:"",title:"Toggle Search Toolbar", buttonicon :'ui-icon-search', onClickButton:function(){ mygrid[0].toggleToolbar() } }); //icon to add the search bar with search textbox



mygrid.filterToolbar(); //adds the search toolbar



mygrid[0].toggleToolbar();//hide the toolbar by default






TIP 8: Having your own icons for navigation bar buttons

We are not always fulfilled with the available JQGrid/JQuery-UI images. So we might need to put our own image/icon for some of the buttons. This could be achieved by writing our own CSS and associating it with the navigator grid button by specifying it as a value to buttonicon as shown below




1

2

3

4

5

6

7

8

9


.ui-icon.myicon {



    width: 16px;



    height: 16px;



    background-image:url(edit.png);



}









1


mygrid.navButtonAdd("#mysimpletablepager",{caption:"",title:"Toggle Search Toolbar", buttonicon:'myicon', onClickButton:function(){ mygrid[0].toggleToolbar() } });






TIP 9: Removing title bar close button

I don’t find a real use of the tile bar close button. It would be much useful if the adjacent components occupy the space whenever user shrinks the grid, something like IGoogle portlets. Though JQGrid does it, it largely depends on the enclosing component. So I prefer to remove of button thereby hiding the functionality from user. As other removal this can also be easily achieved using remove() API as shown below




1


$('.ui-jqgrid-titlebar-close','#gview_mysimpletable').remove();






Note: Title bar won’t appear if the caption is an empty string.

TIP 10: Adding toolbar

JQGrid also provides an option to add toolbar to the table. This can be achieved using toolbar option, toolbar:[true,”both”] during grid creation. First parameter specifies whether the grid needs to be added or not. The second parameter is to tell about the location of the toolbar. Second parameter can take three values namely, top, bottom and both.

Stay tuned to know about the procedure for adding buttons to toolbar.

Version of

JQGrid – 3.5 beta

JQuery – 1.3.2

JQuery UI Theme – Dark Hive

Feel free to share your experience with JQGrid and also if you have cleaner way to solve some of the items discussed above, as comments.