Pagination

As shown in the other datastore sections, the fetch method of the Read API can query across and return sets of items in a variety of ways. However, there is generally only so much space on a display to list all the data returned. Certainly, an application could implement its own custom display logic for just displaying subsets of the data, but that would be inefficient because the application would have had to load all the data in the first place. And, if the data set is huge, it could severely increase the memory usage of the browser. Therefore, dojo.data provides a mechanism by which the store itself can do the paging for you. When you use the paging options of fetch, all that is returned in the callbacks for fetch is the page of data you wanted, no more. This allows the application to deal with data in small chunks, the parts currently visible to you.

The paging mechanism is used by specifying a start parameter in the fetch arguments. The start parameter says where, in the full list of items, to start returning items. The index 0 is the first item in the collection. The second argument you specify is the count argument. This option tells dojo.data how many items, starting at start, to return in a request. If start isn't specified, it is assumed to be 0. If count isn't specified, it is assumed to return all the items starting at start until it reaches the end of the collection. With this mechanism, you can implement simple paging easily.

To demonstrate the paging function, we'll assume an ItemFileReadStore with the following datasource:

{   
    identifier: 'name', 
    items: [
        { name: 'Adobo', aisle: 'Mexican' },
        { name: 'Balsamic vinegar', aisle: 'Condiments' },
        { name: 'Basil', aisle: 'Spices' },
        { name: 'Bay leaf', aisle: 'Spices' },
        { name: 'Beef Bouillon Granules', aisle: 'Soup' },
        ...
        { name: 'Vinegar', aisle: 'Condiments' },
        { name: 'White cooking wine', aisle: 'Condiments' },
        { name: 'Worcestershire Sauce', aisle: 'Condiments' }
        { name: 'pepper', aisle: 'Spices' }
    ]
}

The following code snippet would allow for paging over the items, 10 at a time:

var store = new dojo.data.ItemFileReadStore({url: "pantryStore.json" });

    var pageSize = 10;
    var request = null;
    var outOfItems = false;

    //Define a function that will be connected to a 'next' button
    var onNext = function(){
       if(!outOfItems){
           request.start += pageSize;
           store.fetch(request);
       }
    };
    //Connect this function to the onClick event of the 'next' button
    //Done through dojo.connect() generally.

    //Define a function will be connected to a 'previous' button.
    var onPrevious = function(){
       if (request.start > 0){
          request.start -= pageSize;
          store.fetch(request);
       }
    }
    //Connect this function to the onClick event of the 'previous' button
    //Done through dojo.connect() generally.

    //Define how we handle the items when we get it
    var itemsLoaded = function(items, request){
       if (items.length < pageSize){
          //We have found all the items and are at the end of our set.  
          outOfItems = true;
       }else{
          outOfItems = false;
       }
       //Display the items in a table through the use of store.getValue() on the items and attributes desired.
       ...
    }

    //Do the initial request.  Without a query, it should just select all items.  The start and count limit the number returned.
    request = store.fetch({onComplete: itemsLoaded, start: 0, count: pageSize});

Note: The previous sample shows how the fetch() function returns a request object. According to the dojo.data specification, the request object contains the query parameters passed in plus an abort() function appended to it. In general, the abort function is intended for cases in which a request might take too much time to process or, in using the streaming callback of fetch(), a way to stop the streaming.

The request object also serves another purpose for datastores. It is a location where the store can cache hidden information about the request in process, such as a cache entry key for boosting performance through specifying exactly what internal cache might be in use for this particular query. Therefore, datastores can avoid calls to the server if possible. And, in the paging case, it becomes important to reuse the request object returned from fetch(). Also note that not all stores will append cache information to the request, but some might. Therefore, when in doubt, reuse the request object when paging.