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:

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.

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.

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:

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.