wiki:pager - jqGrid Wiki

Pager
Discussion

If your grid has only a few rows of data, then all the records will be viewable at the same time and you won't have to worry about navigating through pages of data.

But more likely, you will be dealing with large sets of data, and you'll want to display a small number of available records at a time. For this functionality, you will need the Navigation Bar.

Pager is currently disabled for TreeGrid

Definition

The Navigation Bar, also known as the pager, is enabled by placing a <div> right after the <table> definition in your HTML. Note that it is a <div>, not a <table>. Then, you identify the <div> to your grid by placing the name of the div in the grid setting called “pager”.

First, the HTML definition. We'll name it “gridpager” :

...
<body>
...
   <table id="list"></table> 
   <div id="gridpager"></div> 
...
</body>
 
Next, we'll identify "gridpager" to your grid:

Java Script code

jQuery("#grid_id").jqGrid({
...
   pager : '#gridpager',
...
});

It is not needed to set class to a pager. It is not needed to set any class to a table element.

The definition of the pager in the grid can be done this way:pager : '#gridpager', pager : 'gridpager' or pager : jQuery('#gridpager'). All the three methods are valid, but I recommend to use the first or second one, since the jQuery variant causes problems when we try to use Exporting and Importing modules.

The definition in jqGrid options array tell that the pager should be a part of the grid and the width of the pager will equal of the width of the grid. In this case, the pager will be placed below the body of the gird. Note that in this case the pager element can have arbitrary position in the document and it will be placed instead above the grid body.

If you want to have custom pager you can use your own definition and not to set the pager options in the grid.

The pager when defined uses variables from language file. The English variant of these properties look like this (file grid.locale-en.js):

$.jgrid = {
	defaults : {
		recordtext: "View {0} - {1} of {2}",
	        emptyrecords: "No records to view",
		loadtext: "Loading...",
		pgtext : "Page {0} of {1}"
	},
...
}

You can change these properties different ways depending on the needs.

1. If you want globally to change these - i.e these changes will take effect in all created grids - you can do:

jQuery.extend(jQuery.jgrid.defaults,{emptyrecords: "Nothing to display",...});

You can save this code in file and load it after the jqGrid needed files are loaded.

2. If you want to change this only for a particular grid you can do:

jQuery("#grid_id").jqGrid({
...
   pager : '#gridpager',
   emptyrecords: "Nothing to display",
...
});

Normally, the pager placed so it appears at the bottom of the grid. A duplicate pager can also be enabled to appear at the top of the grid.

Normally when we create the pager we divide this element on three equal parts - left, center and right part. When you try to place additional information in the pager the pager try to fit the size. In case if you plan to place a lot of elements you should accordingly set the appropriate width of the grid.

By default the paging elements are placed at a center and the record information at right position of the pager. You can change these positions using the options pagerpos and recordpos - see below.

Currently the icons that represent the pager buttons for navigating through the records are hard coded and we use the jQuery UI theming icons for this purpose.

Properties

The properties that are connected with the pager element are listed below:

Property	Type	Description	Default	Can be changed?
lastpage	integer	Readonly property. Determines the total number of pages returned from the request.	0	No
pager	mixed	Defines that we want to use a pager bar to navigate through the records. This must be a valid html element; in our example we gave the div the id of “pager”, but any name is acceptable. Note that the Navigation layer (the “pager” div) can be positioned anywhere you want, determined by your html; in our example we specified that the pager will appear after the Table Body layer. The valid calls can be (using our example) 'pager', '#pager', jQuery('#pager'). I recommend to use the second one.	empty string. Currently only one pagebar is possible.	No
pagerpos	string	Determines the position of the pager in the grid. By default, when the pager element is created it's divided into 3 parts (one part for pager, one part for navigator buttons and one part for record information)	center	No
pgbuttons	boolean	Determines if the Pager buttons should be shown if pager is available. Also valid only if pager is set correctly. The buttons are placed in the pager bar.	true	No
pginput	boolean	Determines if the input box, where the user can change the number of requested page, should be available. The input box appear in the pager bar.	true	No
pgtext	string	Show information about current page status. The first value is the current loaded page. The second value is the total number of pages	See lang file	Yes
reccount	integer	Readonly property. Determines the exact number of rows in the grid. Do not confuse this with records parameter. Although in most cases they are equal there is a case where this is not true. For example you define rowNum parameter 15, but you return from server records parameter = 20, then the records parameter will be 20, the reccount parameter will be 15, and in the grid you will have 15 records.	0	No
recordpos	string	Determines the position of the record information in the pager. Can be left, center, right	right	No
records	integer	Readonly property. Determines the number of returned records in grid from the request	none	No
recordtext	string	Represent information that can be shown in the pager. This option is valid only if viewrecords option is set to true. This text appear only if the total number of records is greater than zero. In order to show or hide some information the items in {} mean the following: {0} - the start position of the records depending on page number and number of requested records; {1} - the end position; {2} - total records returned from the data	see lang file	Yes
rowList	array[]	An array to construct a select box element in the pager in which we can change the number of the visible rows. When changed during the execution, this parameter replaces the rowNum parameter that is passed to the url. If the array is empty the element does not appear in the pager. Typical you can set this like [10,20,30]. If the rowNum parameter is set to 30 then the selected value in the select box is 30.	empty array - []	No
rowNum	integer	Sets how many records we want to view in the grid. This parameter is passed to the url for use by the server routine retrieving the data	20	Yes
viewrecords	boolean	Defines whether we want to display the number of total records from the query in the pager bar.	false	No

All the properties that can be changed in the pager after creating the jqGrid object require reloading the grid. This is done via the trigger(“reloadGrid). Here is a example which change the number of requested rows to 10.

<script>
...
jQuery("#grid_id").setGridParam({rowNum:10}).trigger("reloadGrid");
...
</script>

Events

One event of the grid relates to the Pager:

Event	Parameters	Description
onPaging	pgButton	This event fires after click on [page button] and before populating the data. Also works when the user enters a new page number in the page input box (and presses [Enter]) and when the number of requested records is changed via the select box. To this event we pass only one parameter pgButton (string) which can be - first,last,prev,next in case of button click, records in case when a number of requested rows is changed and user when the user change the number of the requested page. If the string stop is returned from the function then the paging will be stopped.

Discussion

Jason Johnson, 2011/08/31 03:04

The API I'm using to get the data to display in the grid is generic and doesn't pass back a “page” property. As a result, when the grid renders, the page displays “0” until I change the number of records per page (using the drop down. How can I resolve this so it shows the right page number and enables the forward/back page buttons after the grid is loaded?

Tsahi, 2013/02/19 16:06

well, you should return the page property. this is the schema jqGrid expects.

nicholas, 2011/11/10 19:23

I'm having the same problem as Jason. Any ideas?

Norm Cousineau, 2012/06/07 18:57, 2012/06/07 19:02

Me too. I'm using datatype: “local”, and only after I click 'reload grid' does the scroll bar hide, and rowNum:4 takes affect. When using dataype: “json” it works fine on load. (I use local because I want the search to be on local data.)

Update: My workaround is to do this $('#myGrid').trigger(“reloadGrid”);

that's after I do this: $('#myGrid').addRowData(“id”,data);

Brian, 2012/07/30 19:35, 2012/07/31 11:17

Hi there, is there any way to completely disable or hide the pager? I am doing paging in another way, another place on the page and so there is a div at the bottom of the jqGrid that is wasted space. Thanks!

Diosney Sarmiento Herrera, 2014/02/05 13:58

Yes, just remove the <div id=“gridpager”></div> section and you won't see it anymore.

You could leave a comment if you were logged in.