Use Spry to Page Forward and Backward Through Records - A Simple Tutorial
In mid-December, Adobe released Spry 1.4 (see: http://labs.adobe.com/technologies/spry/). Spry is Adobe's ajax framework, enabling developers to build web pages with dynamic regions. Shortly before Christmas, the Spry developers posted a SpryPagedView JavaScript class and a sample of how to use the class. The SpryPagedView class provides the capability to page forward and backward through a Spry DataSet.
The Adobe sample using the SpryPagedView class is available here: http://labs.adobe.com/technologies/spry/samples/data_region/SpryPagedViewSample.html. Adobe's excellent sample include additional Spry features (filtering, master-detail data sets). I wanted to create my own sample and tutorial that just focused on using the SpryPagedView class to page through a DataSet. You can view my sample here: /spry/pagedDataSet/testpaging.cfm.
You must include the Spry JavaScript classes in your head section:
script type="text/javascript" src="xpath.js"></script>
script type="text/javascript" src="SpryData.js"></script>
script type="text/javascript" src="SpryPagedView.js"></script>
The three JavaScript classes above are the ones you need to create a DataSet and page through the records in the DataSet.
Next you need to create a DataSet (for more information on how to create a Spry DataSet see the Spry section of my blog) and a paged-enabled view of that DataSet.
script type="text/javascript">
//create a basic Spry DataSet
var dsConsultants = new Spry.Data.XMLDataSet("ConsultantSearchService.cfc?method=getAllNamesXML", "dataset/row");
//create a page-enabled view of the Spry DataSet
var pvConsultants = new Spry.Data.PagedView(dsConsultants, { pageSize: 12 });
</script>
The PagedView constructor takes the DataSet name as the first argument and also has three optional arguments. One of the optional arguments is how many records do you want displayed per page. In this example, I set the pageSize value to 12. For a complete list of the optional arguments and all the functions available when using class SpryPagedView, see the Adobe sample at http://labs.adobe.com/technologies/spry/samples/data_region/SpryPagedViewSample.html
The next block of code sets up the buttons that the user can click on to page through the DataSet.
<!-- BEGIN PagedView Controls -->
<p style="text-align:center">
<input type="button" value="First Page" onclick="pvConsultants.firstPage();" />
<input type="button" value="Prev Page" onclick="pvConsultants.previousPage();" />
<input type="button" value="Next Page" onclick="pvConsultants.nextPage();" />
<input type="button" value="Last Page" onclick="pvConsultants.lastPage();" />
</p>
The click event for each button calls a specific SpryPagedView function. For example if the user clicks on the "Next Page" button, the SpryPagedView object I created and named pvConsultants will call the nextPage() function. This will cause the next 12 records to be displayed in the DataSet's region on the page.
The next block of code uses some of the data references that the DataSet makes available to let the user know which page of data he is on, and how many total pages of data there are. The spry:if checks that we actually have rows to display.
<!-- BEGIN PagedView Info Section -->
<div spry:region="pvConsultants">
<p spry:if="{ds_UnfilteredRowCount} > 0">Page {ds_PageNumber} of {ds_PageCount} - Consultants {ds_PageFirstItemNumber} - {ds_PageLastItemNumber} of {ds_UnfilteredRowCount}</p>
<p spry:if="{ds_UnfilteredRowCount} == 0">No matching data found!</p>
</div>
Lastly, you use a normal spry:region and spry:repeat to display the records in the DataSet. Note the value for the spry:region and spry:repeat attributes is the SpryPagedView DataSet, pvConsultants. When the user clicks on one of the buttons above, this is the Spry:Region that is updated with the records for that page of the DataSet.
<!-- BEGIN Paged Display Section -->
<!--Note the name of the PagedView then the name of the DataSet as the value for spry:region-->
<div class="docBlock" spry:region="pvConsultants">
<div spry:state="loading" id="notification2">Loading consultants, please wait ...</div>
<table cellpadding="5">
<tr>
<th onClick="dsConsultants.sort('FIRST_NAME','toggle');">First Name</th>
<th onClick="dsConsultants.sort('LAST_NAME','toggle');">Last Name</th>
<th onClick="dsConsultants.sort('CITY','toggle');">City</th>
<th onClick="dsConsultants.sort('EMAIL','toggle');">Email</th>
</tr>
<tr spry:repeat="pvConsultants">
<td>{FIRST_NAME}</td>
<td>{LAST_NAME}</td>
<td>{CITY}</td>
<td><a href="mailto:{EMAIL}">{EMAIL}</a></td>
</tr>
</table>
</div>
The Adobe sample demonstrates additonal capabilities of the SpryPagedView class and also shows you how to filter the records in a paged DataSet. I hope this brief tutorial on how to use the SpryPagedView class will make it easier for you to understand the more complex sample provided by Adobe. Adobe is doing a wonderful job with Spry, making it easy for developers to include ajax functionality. I look forward to an "official" release of the Spry framework, along with good documentation on how to use the many Spry classes and their functions.
thanks.