sencha-logoBetween the Ext JS forums and Stack Overflow, there are LOTS of questions that get asked about grids, and for obvious reasons: the data grid is one of Ext JS’s most powerful data-driven components.

With new developers especially, I see a common question asked quite a bit about a pretty standard bit of functionality: the “paged” data set. In this post, I’m not going to necessarily go into all the nuances of *how* to configure a paged grid in Ext JS (there are plenty of docs for that). Rather, I want to focus on *what* paging in an Ext JS grid is, and how it relates to the server.

What It Isn’t

The most important rule to understand when dealing with paging data from a remote data set is that Ext JS grids–regardless of how powerful they are–are STUPID. By this, I don’t mean that they are poorly built, or that they lack features, don’t work, or anything like that. Rather, I simply mean that when it comes to the data you are asking them to display, they are completely ignorant. When you configure an Ext JS data grid to display (and page) remote data, you will be lost if you think that your grid has any concept about what your data is and whether or not it is “correct.”

I say this because a common problem that I see people running into is that they think that their grid is somehow “aware” of the data that it is facilitating pagination for. This couldn’t be further from the truth. Your Ext JS grid has literally NO IDEA about your data. Among other things, your grid does NOT know the following:

  • How many records you have
  • What “page 1″ of your data set should look like
  • What “page 2″ of your data set should look like

But because of the misconception that the grid is “doing” the paging, you’ll come across questions/problems like:

  • “I clicked on next page, but the data doesn’t change”
  • “I have thousands of records, but my grid says I only have 3 pages”

Obviously, such a misconception leads to frustration, as not properly understanding the grid’s relationship to the remote data leads to fruitless problem solving attempts.

What It Is

Now that we understand how Ext JS grids are ignorant when it comes to your remote data, the way is cleared to understand exactly what the relationship of the data grid is to this data, and how we can leverage that to create a robust paged grid.

totalProperty

Since the grid is inherently ignorant about remote data, it is the responsibility of the developer to tell the grid about the data set that the grid is being asked to handle. This is ultimately accomplished via the reader configuration of the grid’s bound store. The most important part of this is the totalProperty configuration (default=”total”). When you return the initial data set for the paged grid, you can pass a key in the JSON response that includes a value which represents the total size of the data set. When this response is consumed, the grid’s store will remember the total and use this in conjunction with the store’s pageSize configuration to calculate how many “pages” of data it can expect to facilitate.

limitParam, pageParam, and startParam

While totalProperty deals with the *response* from the server, limitParam, pageParam and startParam occur on the *request* side of the equation. By default, EVERY request that your grid’s store makes to the server will include 3 paging-related parameters:

  • limit
  • page
  • start

These can be configured on your store’s proxy to be something different, if you like.

You can think of these parameters as an instruction list for the server. In other words, your grid’s store is simply asking for a dataset that is X number of records (limit) and begins at Y index (start). And depending on your database, you could potentially use Z to retrieve a particular “page” of data (page).

Now that we know the two sides of the equation in which the grid’s store is interested (request and response), we can imagine how the “paging” works. Think of it in this workflow:

  • First Request: Don’t know the size of the data, so request data set with limit 25 (default), start 0 (default) and page (1)
  • Receive Request: total = 125 and 25 rows of data.
  • Post First Request: Our store knows that there are 125 total records, and that we are on the first “page”. Therefore, we know that there are 5 total pages
  • Next Request: Since we’re on the first page, request data with limit 25, start 25, page 2
  • And so on

The Handshake

We’ve now seen how this process works. But as slick as it is, we must avoid the temptation of falling back into wrong thinking about what the grid is doing and what it knows.

For example, let’s say that our server returns the correct “total” of records, but does not change the underlying data set that is returned on subsequent requests, but instead sends the same data for each page. From the perspective of the grid, as long as the request is successful, it will believe that everything is happening as expected, and will continue to “page” the data, even though it is precisely the same from request to request. It does not know that there is a problem, and we’ll spin our wheels trying to debug why the grid is behaving as it is, when all along the issue is with the server-side code.

For precisely this reason, it is crucial to understand that the grid store’s request to the server is simply a handshake. Since the grid and its store have no idea about what data to expect from the server, ANY data that is returned is assumed to be correct. The grid’s store can only make requests, trusting that what it asks for is returned. If there is a failure on the part of the server to return the correct data set, the handshake is broken, even though the grid is oblivious to it.

The bottom-line, then, is this: The drop-dead only thing your Ext JS grid can do to page data is to ask nicely for it. If the server does not respond, or responds with the wrong data, your grid is hamstrung to do anything about it, simply because it will have no clue that it wasn’t given the right data. It might seem that the grid is too trusting…but since it operates in a different universe than the server-side code which interacts with the data, this is all the grid can do. Poor thing :)

Some Debugging Suggestions

For the vast majority of people I’ve seen who have had this issue, the solution to their problems would have been more clear if they had used the correct debugging tools.

JavaScript

If you are having issues with a paged grid, the very first place you should start debugging the issue is via Chrome’s Developer Tools or Firebug in Firefox. Both of these tools will allow you to see the remote requests and responses that are made during the course of pagination. By inspecting the responses from the server to ensure that you’re receiving the correct data, you can quickly eliminate a lot of issues.

BTW, if you aren’t using one of these constantly during your Ext JS development process, you should start today. Good JS debugging tools are crucial to developing your app, and will save you a ton of time.

SQL

Next, enable some manner of logging in your server-side code to capture the SQL queries that are executed as a result of the Ext JS grid’s AJAX request. If you’re having issues with incorrect data sets being returned, try running the logged SQL string in your database. If you’re missing paging-related parameters, check your server-side code to ensure that the parameters passed from Ext JS are getting applied as expected.