# Spry Paged View Data Set

The Spry Paged View Data Set, (or Spry Pager) is a data abstraction mechanism that provides paging mechanisms for a standard data set. This document describes how the Spry Pager works with data and how to implement paging on your data set.

### Spry Pager Overview

The Pager works by reading a data set and extracting information out of it in order to generate a separate batch of information about paging. For example, Bind a paged data set to a XML data set with 120 rows of data. In the paged data set, tell Spry you want 20 rows of data per page. Now Spry knows that you have 6 pages of data. It knows where each of those pages starts and ends and can easily jump from one to another. It also knows that row 32 is in the 2nd page and can go straight to it.

A key concept to understand is that for the paged data set, using the above example, the 20 rows currently showing for that page IS the whole data set. The number of rows (ds_rowCount) in that data set is 20. When you jump to another page, that new set of 20 rows IS the entire data set. The rowCount is still 20. Only the XML data set has the full 120 rows, but the pager knows how to get them.

The paged data set knows how to do things like 'go to next page' or 'go to previous page'. That information is built in to the data set.

To see the pager in action, see the sample.

As noted below, there are many options and assumptions that need to be made.

### Creating a Paged View Data Set

Since the paged data set only looks at data and doesn't actually gather data, we have to have a data set that contains data. The paged data set is based off this first data set. To create a paged data set, create a standard Spry data set, XML, JSON or whatever you need.

For example, create a data set called 'ds1':

    <script language="JavaScript" type="text/javascript" src="includes/xpath.js"></script>
    <script language="JavaScript" type="text/javascript" src="includes/SpryData.js"></script>
    <script language="JavaScript" type="text/javascript">
        var ds1 = new Spry.Data.XMLDataSet("myXML.xml","xpath");

    </script>

This is a standard data set with, for argument's sake, 120 rows of data.

Before the paged data set can be created, the pager javascript file needs to be attached.

From that data set, create a paged view data set. This is the actual data to be paged.

    <script language="JavaScript" type="text/javascript" src="includes/xpath.js"></script>
    <script language="JavaScript" type="text/javascript" src="includes/SpryData.js"></script>
    <script language="JavaScript" type="text/javascript" src="includes/SpryPagedView.js"></script>
    <script language="JavaScript" type="text/javascript">
        var ds1 = new Spry.Data.XMLDataSet("myXML.xml","xpath");
        var pv1 = new Spry.Data.PagedView( ds1 ,{ pageSize: 20 });

    </script>

In the example above, we created a data set called 'pv1'. The value of the first parameter is 'ds1', which is the name of the first data set we created. As an option in the constructor, we specified the page size as 20 rows per page. Spry uses 10 rows as a default, if the pageSize option isn't set.

So now, a simple Spry construct:

    <div spry:region="pv1" spry:repeatchildren="pv1">
    {data}
    </div>

would output 10 pieces of data, in this case, from the first 20 rows of the master XML data set.

Options

Options on the constructor allow you to fine tune the behavior of the data set. The options available are:

Option Name | Default | Description
--- | --- | ---
pageSize | 10 | The max number of items in a page.
forceFullPages | false | If there is more than one page of data, force the last page of data to contain a full set of data. Note that this could cause some items to appear on both the last and next to last pages.
useZeroBasedIndexes | false | If true the caller will pass page indexes to the various paging functions that are between zero and n-1, where n is the total number of rows in the data set. The default is false, so page numbers are between 1 and n.

Defaults are used if the option does not appear in the constructor.

'forceFullPage' is used if layout is more important than the data. If a data set has 36 rows and a page size of 10, the last page will show only rows 30-36, leading to a shorter output. If this option is set to 'true', then 10 rows will be shown, 27-36, which may duplicate rows 27-29 from the previous page.

Spry generally uses a zero based counting system. Since there is generally no such thing as "Page 0", we made the Paged Data Set use a 1 based counting system. This would simplify using data references for paging. If you prefer the standard zero based counting system, set the 'useZeroBasedIndexes' to 'true'. Remember that Javascript is case sensitive.

    var pv1 = new Spry.Data.PagedView(ds1,{ pageSize:20, forceFullPages:true, useZeroBasedIndexes:true});

### Paging Behaviors

One of the main ideas of the pager is to allow you to page through your data set. Seems obvious. To enable the paging, behaviors are used.

For example, to make buttons that page, it would look like:

    <input type="button" value="First" onclick="pvCities.firstPage();" />
    <input type="button" value="Prev" onclick="pvCities.previousPage();" />
    <input type="button" value="Next" onclick="pvCities.nextPage();" />
    <input type="button" value="Last" onclick="pvCities.lastPage();" />

Give the onclick handler the data set name "pv1" and use the nextPage(); behavior. On click, the paged data will update the paged view data set to show the next 20 rows in the master data set.

Here is the set of built-in behaviors for the Paged View Data Set.

Method Name | Description
--- | ---
getPageCount() | Returns the number of pages that are necessary to accommodate all of the data. This count is based on the page size and number of rows of data in the data set.
getCurrentPage() | Returns the page number/index for the data that is returned by a call to getData(). By default, the number returned by this method will be between 1 and the page count number. If the use useZeroBasedIndexes constructor option was set to true, this method will return a number between zero and pageCount minus one.
goToPage(pageIndex) | Filter the data so that only rows associated with the specified page index are available via getData().
goToPageContainingRowID(rowID) | Filter the data so that only rows on the same page as the row with the specified rowID are available.
goToPageContainingRowNumber(rowNumber) | Filter the data so that only rows on the same page as the row with the specified row number are available.
goToPageContainingItemNumber(itemNumber) | Filter the data so that only rows on the same page as the row with the specified item number are available.
firstPage() | Filter the data set so that only rows in the first page are available.
lastPage() | Filter the data set so that only rows in the last page are available.
previousPage() | Filter the data set so that only rows in the previous page are available.
nextPage() | Filter the data set so that only rows in the next page are available.
getPageForRowID(rowID) | Returns the index of the page that contains the row with the given ds_RowID.
getPageForRowNumber(rowNumber) | Returns the index of the page that contains the specified row number.
getPageForItemNumber(itemNumber) | Returns the index of the page that contains the specified item number.
setPageSize(pageSize) | Sets the maximum number of rows that can appear on any page. If zero, turns off paging.

See the Paged View sample for examples of these behaviors.

### Paged View Data References

Because it is a data set, the paged data set uses data references as any normal data set. It also can use the standard data set references like {ds_RowID}. Because the PagedView extracts its data from the data set it depends on, the {ds_RowID} value for each row in the PagedView is identical to the ds_RowID of the corresponding row in the data set it depends on.

The unique nature of the paged data set offers a set of paging specific data references that can be used in spry:regions.

Data Reference | Description
--- | ---
{ds_PageNumber} | The current page index. By default this will be a number between 1 and ds_PageCount. If the useZeroBasedIndexes constructor option was set to true, this will be a number between 1 and ds_PageCount minus one.
{ds_PageSize} | The maximum number of items that can be in a page.
{ds_PageCount} | The total number of pages required to display all of the data.
{ds_PageItemRowNumber} | The unfiltered row index for the current row being processed.
{ds_PageItemNumber} | The unfiltered item number for the current row being processed. This is the unfiltered row index of the row plus one.
{ds_PageFirstItemNumber} | The item number for the first row displayed in the current page.
{ds_PageLastItemNumber} | The item number for the last row displayed in the current page.
{ds_PageItemCount} | The total number of items in the current page.
{ds_PageTotalItemCount} | The total number of items in all pages.
{ds_UnfilteredRowCount} | The total number of rows in the data set.
{ds_CurrentRowID} | For the PagedView, this is *always* the ID of the first row in the current page.
{ds_RowID} | The row id for the row being processed.
{ds_CurrentRowNumber} | For the PagedView, this is *always* zero, which is the index of the first row in the current page.
{ds_RowNumber} | This is the row index, of the row being processed, in the current page.

This easily allows for common patterns like:

    <div spry:detailregion="pv1">
    This is Page {ds_PageNumber} of {ds_PageCount}.
    </div>

### Paged View Info

Paged View Info is a further abstraction of the paging data. It is used to enable common paging patterns. It is best described by example. The Paged View Info structure enables:

> Go to Page: 1 2 3 4 5 6 7 8 9 10

to be created with:

    <p spry:region="pvInfo" spry:repeatchildren="pvInfo">
       <a spry:if="{ds_CurrentRowNumber} != {ds_RowNumber}" href="#" onclick="pvCities.goToPage('{ds_PageNumber}')">{ds_PageNumber}</a>
       <span spry:if="{ds_CurrentRowNumber} == {ds_RowNumber}" class="currentPage">{ds_PageNumber}</span>
    </p>

or

> 1-20 21-40 41-60 61-80 81-100 101-120

is done with:

    <p spry:region="pvInfo" spry:repeatchildren="pvInfo">
     <a spry:if="{ds_CurrentRowNumber} != {ds_RowNumber}" href="#" onclick="pvCities.goToPage('{ds_PageNumber}')">{ds_PageFirstItemNumber}-{ds_PageLastItemNumber}</a>
     <span spry:if="{ds_CurrentRowNumber} == {ds_RowNumber}" class="currentPage">{ds_PageFirstItemNumber}-{ds_PageLastItemNumber}</span></p>

This is done by creating a special data set that contains these paging data references. It is enabled by creating a variable and populating it with the results of a function:

    <script language="JavaScript" type="text/javascript" src="includes/xpath.js"></script>
    <script language="JavaScript" type="text/javascript" src="includes/SpryData.js"></script>
    <script language="JavaScript" type="text/javascript" src="includes/SpryPagedView.js"></script>
    <script language="JavaScript" type="text/javascript">
        var ds1 = new Spry.Data.XMLDataSet("myXML.xml","xpath");
        var pv1 = new Spry.Data.PagedView( ds1 ,{ pageSize: 20 });
        var pvInfo = pv1.getPagingInfo();

    </script>

where 'pv1' is the name of the paged data set.

This creates a separate data set called pvInfo. This data set has a set of data references that know about the paged data set 'pv1'. We can loop over these data references to create these common patterns.

The data references it creates are:

name | description
--- | ---
{ds_PageNumber} | The number of the page of a data.
{ds_PageSize} | The number of rows of data per page.
{ds_PageCount} | The total number of pages in the data set.
{ds_PageFirstItemNumber} | The item number that is the first row of data for that page. If pages have 10 rows per page, item 11 is the first item number of page 2 and 21 is the first item number of page 3.
{ds_PageLastItemNumber} | The item number that is the last row of data for that page. If pages have 10 rows per page, item 20 is the last item number of page 2 and 30 is the first item number of page 3.
{ds_PageItemCount} | The actual number of rows of data on the current page. This will generally be same as {ds_pageSize} except for instance when the last page of the data has less than a full page of data.
{ds_PageTotalItemCount} | This is the sum of all the rows in all the pages.

Since this is still a data set, it contains all the normal built-in data references, like {ds_RowID} and {ds_currentRowNumber}, plus it has the references listed above.

Copyright © 2007. Adobe Systems Incorporated. All rights reserved.