Quick start – creating your first grid

(For more resources related to this topic, see here.)

So, let's do that right now for this example. Create a copy of the entire jqGrid folder named quickstart; easy as pie.

Let's begin by creating the simplest grid possible; open up the index.html file from the newly created quickstart folder, and modify the body section to look like the following code:

<table id="quickstart_grid"></table>
var dataArray = [
{name: 'Bob', phone: '232-532-6268'},
{name: 'Jeff', phone: '365-267-8325'}
datatype: 'local',
data: dataArray,
colModel: [
{name: 'name', label: 'Name'},
{name: 'phone', label: 'Phone Number'}

The first element in the body tags is a standard table element; this is what will be converted into our grid, and it's literally all the HTML needed to make one.

The first four lines are just defining some data. I didn't want to get into AJAX or opening other files, so I decided to just create a simple JavaScript array with two entries. The next line is where the magic happens; this single command is being used to create and populate a grid using the information provided.

We select the table element with jQuery, and call the jqGrid function, passing it all the properties needed to make a grid. The first two options set the data along with its type, in our case the data is the array we made and the type is local, which is in contrast to some of the other datatypes which use AJAX to retrieve remote data.

After that we set the columns, this is done with the colModel property. Now, there are a lot of options for the colModel property, which we will get to later on, numerous settings for customizing and manipulating the data in the table. But for this simple example, we are just specifying the name and label properties, which tell jqGrid the column's label for the header and the value's key from the data array.

Now, open index.html in your browser and you should see something like the following screenshot:

Not particularly pretty, but you can see that with just a few short lines, we have created a grid and populated it with data that can be sorted.

But we can do better; first off, we are only using two of the four standard layers we talked about: the header layer and the body layer. Let's add a caption layer to provide little context, and let's adjust the size of the grid to fit our data.

So, modify the call to jqGrid with the following:

datatype: 'local',
data: dataArray,
colModel: [
{name: 'name', label: 'Name'},
{name: 'phone', label: 'Phone Number'}
height: 'auto',
caption: 'Users Grid',

And refresh your browser; your grid should now look like the following screenshot:

That's looking much better. Now, you may be wondering, we only set the height property to auto, so how come the width seems to have snapped to the content? This is due to the fact that the right margin we saw earlier is actually a column for the scroll bar. By default jqGrid sets your grid's height to 150 pixels, this means, regardless of whether you have only one row, or a thousand rows, the height will remain the same, so that there is a gap to hold the scroll bar in an event when you have more rows than that would fit in the given space. When we set the height to auto, it will stretch the grid vertically to contain all the items, making the scroll bar irrelevant and therefore it knows not to place it.

Now this is a pretty good quick start example, but to finish things off, let's take a look at the navigation layer, just so we can say we did.

For this next part, although we are going to need more data, I can't really show pagination with just two entries, luckily there is a site http://www.json-generator.com/ created by Vazha Omanashvili for doing exactly this.

The way it works is, you specify the format and number of rows you want, and it generates it with random data. We are going to keep the format we have been using, of name and phone number, so in the box on the left, enter the following code:

name: '{{firstName}} {{lastName}}',
phone: '{{phone}}'

Here we're saying we would like 50 rows with a name field containing both firstname and lastname, and we would also like a phone number. This site is not really in the scope of this book, but if you would like to know about other fields, you can click on the help button at the top.

Click on Generate to produce a result object, and then just click on the copy to clipboard button. With that done, open your index.html file and replace the array for dataArray with what you copied. Your code should now look like the following code:

var dataArray = {
"id": 1,
"jsonrpc": "2.0",
"total": 50,
"result": [ /* the 50 rows */ ]

As you can see, the actual rows are under a property named result, so we will need to change the data key in the call to jqGrid from dataArray to dataArray.result. Refreshing the page now you will see the first 20 rows being displayed (that is the default limit). But how can we get to the rest? Well, jqGrid provides a special navigation layer named "pager", which contains a pagination control. To display it, we will need to create an HTML element for it. So, right underneath the table element add a div like:

<table id="grid"></table>
<div id="pager"></div>

Then, we just need to add a key to the jqGrid method for the pager and row limit:

caption: 'Users Grid',
height: 'auto',
rowNum: 10,
pager: '#pager'

And that's all there to it, you can adjust the rowNum property to display more or less entries at once, and the pages will be automatically calculated for you.


In this article we learned how to create a simple Grid and customize it. We used different properties and functions for the same. We also used different layers to customize the jqGrid.

Resources for Article :

Further resources on this subject:

You've been reading an excerpt of:

Instant jqGrid

Explore Title