View Source

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[{zone-template-instance:ZFPROP:Proposal Zone Template}
{composition-setup}

{zone-data:component-name}
Zend_Paginator
{zone-data}

{zone-data:proposer-list}
[Jurriƫn Stutterheim|mailto:j.stutterheim@hccnet.nl]
[~mratzloff]
{zone-data}

{zone-data:liaison}
[~ralph]
{zone-data}

{zone-data:revision}
1.0 - April 3, 2008: Initial proposal
1.1 - May 10, 2008: Merging with [Matthew's proposal|http://framework.zend.com/wiki/display/ZFPROP/Zend_Paginator+-+Matthew+Ratzloff]
2.0 - June 10, 2008 Major rewrite complete
2.1 - June 24, 2008: Update to match the latest SVN copy
2.2 - July 4, 2008: Update the proposal to reflect new naming
{zone-data}

{zone-data:overview}
Zend_Paginator provides a generic way to paginate through various collections of data, display the results, and render pagination controls.
{zone-data}

{zone-data:references}
* [Zym_Paginate|http://www.zym-project.com/] - Data pagination through adapters
* [Matthew's proposal|http://framework.zend.com/wiki/display/ZFPROP/Zend_Paginator+-+Matthew+Ratzloff] - Pagination controls as view partials
* [Yahoo! Design Pattern Library|http://developer.yahoo.com/ypatterns/parent.php?pattern=pagination] - View partial ideas
* [Pager (PEAR)|http://pear.php.net/package/Pager] - Sliding and Jumping scrolling concept
{zone-data}

{zone-data:requirements}
* This component *will* be able to paginate arrays, database queries, and iterators.
* This component *will* fetch only those results from the database that need to be displayed.
* This component *will* be compatible with Zend_View_Helper_Partial.
* This component *will* provide its own view helper, built on the view partial functionality.
* This component *will* provide an abstract adapter class to allow for custom adapters.
* This component *will* provide a scrolling style interface to allow for custom scrolling styles.
* This component *will* provide a factory class to make pagination even easier.
{zone-data}

{zone-data:dependencies}
* Zend_Exception
* Zend_View_Helper_Partial

And optionally the following:

* Zend_Controller_Router_Interface
* Zend_View_Interface
* Zend_Controller_Action_Helper_ViewRenderer
{zone-data}

{zone-data:operation}
Each collection type has its own adapter which implements Zend_Paginator_Adapter_Interface. It provides a generic interface to provide all necessary methods needed to work with paginated collections.

The data that needs to be paginated is provided in the constructor. The amount of items per page and of course the current page can be set through the corresponding methods. Each specific pagination class returns a different collection result for a page, but each of those can be manipulated in the same way.

It is worth noting that the DbSelect paginator only fetches the required rows. It does this by adding a LIMIT to the query. In order to make this work, it clones the provided SELECT query and replaces the columns with count statement. Example:
{code}
// Original query
SELECT foo FROM bar WHERE baz=bat

// Cloned and modified count query
SELECT COUNT(*) AS zend_paginator_row_count FROM bar WHERE baz=bat
{code}
The result of this query is one row containing one column called "zend_paginator_row_count". This is used internally to provide the record count. Optionally you can provide the adapter with a custom select query by using the setCountSelect() method.

This component will be compatible with Zend_View_Helper_Partial for maximum flexibility in choosing how to render pagination controls. It will also provide its own view helper built on top of the view partial functionality.
{zone-data}

{zone-data:milestones}
* Milestone 1: *\[DONE\]* Write initial proposal
* Milestone 2: *\[DONE\]* Review by community
* Milestone 3: *\[DONE\]* Review by Zend
* Milestone 4: *\[DONE\]* Component incubated
* Milestone 5: *\[DONE\]* Write unit tests
* Milestone 6: *\[DONE\]* Write documentation
* Milestone 7: *\[DONE\]* Component cored
{zone-data}

{zone-data:class-list}
{zone-data}

{zone-data:use-cases}
|| UC-01: Paginate an array ||

{code}
$sampleData = array();
foreach (range(1, 500) as $number) {
$sampleData[] = $number;
}
$paginator = Zend_Paginator::factory($sampleData);
$paginator->setRouteName('results')
->setCurrentPageNumber($this->_getParam('page'));
$this->view->pages = $paginator;
{code}

|| UC-02: Paginate a database query ||

{code}
$db = new Zend_Db_Adapter_Pdo_Sqlite(array(
'dbname' => 'example.sqlite'
));
$sampleData = $db->select()->from('example');
$paginator = Zend_Paginator::factory($sampleData);
$paginator->setRouteName('results')
->setScrollingStyle('Jumping')
->setItemCountPerPage(15)
->setPageRange(5)
->setCurrentPageNumber($this->_getParam('page'));
$this->view->pages = $paginator;
{code}
Optionally you can provide your own select query to fetch the item count.
{code}
$paginator->setRowCount($customSelectQuery);
{code}

|| UC-03: Paginate an iterator ||

{code}
$sampleData = array();
foreach (range(1, 500) as $number) {
$sampleData[] = $number;
}
$sampleData = new ArrayIterator($sampleData);

$partial = '_partials/search_pagination_control.phtml';
Zend_View_Helper_PaginationControl::setDefaultViewPartial($partial);

Zend_Paginator::setConfig(Zend_Registry::get('configuration'), 'pagination');

$paginator = Zend_Paginator::factory($sampleData);
$paginator->setCurrentPageNumber($this->_getParam('page'));
$this->view->pages = $paginator;
{code}

|| UC-04: Rendering view script ||

{code}
<?php if (count($this->paginator)): ?>
<ul>
<?php foreach ($this->paginator as $item): ?>
<li><?= (is_array($item)) ? $item['number'] : $item; ?></li>
<?php endforeach; ?>
</ul>
<?php endif; ?>

<?= $this->paginationControl($this->pages, $this->scrollingStyle); /* Or even shorter: <?= $this->pages ?> */ ?>
{code}

|| UC-05: Search pagination control ||

http://www.builtfromsource.com/svn/Zend_Paginator/trunk/demos/Zend/Paginator/application/views/scripts/_partials/search_pagination_control.phtml

|| UC-06: Item pagination control ||

http://www.builtfromsource.com/svn/Zend_Paginator/trunk/demos/Zend/Paginator/application/views/scripts/_partials/item_pagination_control.phtml

|| UC-07: Dropdown pagination control ||

http://www.builtfromsource.com/svn/Zend_Paginator/trunk/demos/Zend/Paginator/application/views/scripts/_partials/dropdown_pagination_control.phtml

{zone-data}

{zone-data:skeletons}
Please see [http://framework.zend.com/svn/framework/standard/library/Zend/] for the latest code.
{zone-data}

{zone-template-instance}]]></ac:plain-text-body></ac:macro>

<p><ac:image ac:width="84"><ri:url ri:value="http://www.rotaryclubofsantamonica.org/Images/2001-2002/Past%20Events/Schwarzenegger.jpg" /></ac:image> <em>Come with me if you want to paginate.</em></p>