CHG: Changed private variable name (chunkLength to _chunkLength) in Jumping.php and Sliding.php

CHG: Added documentation for Doctrine_Pager and Doctrine_Pager_Range* classes
TODO: Finish pagination documentation

lib/Doctrine/Pager/Range/Jumping.php

@@ -36,9 +36,9 @@ Doctrine::autoload('Doctrine_Pager_Range');
 class Doctrine_Pager_Range_Jumping extends Doctrine_Pager_Range
 {
     /**
-     * @var int $chunkLength     Chunk length to be returned
+     * @var int $_chunkLength     Chunk length to be returned
      */
-    private $chunkLength;
+    private $_chunkLength;
 
 
     /**
@@ -67,7 +67,7 @@ class Doctrine_Pager_Range_Jumping extends Doctrine_Pager_Range
      */
     public function getChunkLength()
     {
-        return $this->chunkLength;
+        return $this->_chunkLength;
     }
 
 
@@ -81,7 +81,7 @@ class Doctrine_Pager_Range_Jumping extends Doctrine_Pager_Range
      */
     protected function _setChunkLength($chunkLength)
     {
-        $this->chunkLength = $chunkLength;
+        $this->_chunkLength = $chunkLength;
     }
 
 

lib/Doctrine/Pager/Range/Sliding.php

@@ -36,9 +36,9 @@ Doctrine::autoload('Doctrine_Pager_Range');
 class Doctrine_Pager_Range_Sliding extends Doctrine_Pager_Range
 {
     /**
-     * @var int $chunkLength     Chunk length to be returned
+     * @var int $_chunkLength     Chunk length to be returned
      */
-    private $chunkLength;
+    private $_chunkLength;
 
 
     /**
@@ -67,7 +67,7 @@ class Doctrine_Pager_Range_Sliding extends Doctrine_Pager_Range
      */
     public function getChunkLength()
     {
-        return $this->chunkLength;
+        return $this->_chunkLength;
     }
 
 
@@ -81,7 +81,7 @@ class Doctrine_Pager_Range_Sliding extends Doctrine_Pager_Range
      */
     protected function _setChunkLength($chunkLength)
     {
-        $this->chunkLength = $chunkLength;
+        $this->_chunkLength = $chunkLength;
     }
 
 

manual/docs/en.txt

@@ -3,6 +3,7 @@
 + Basic schema mapping
 + Relations
 + Working with objects
++ Pagination
 + Component overview
 + Hierarchical data
 + Configuration

manual/docs/en/pagination.txt

@@ -0,0 +1,5 @@
+++ Introduction
+++ Working with pager
+++ Controlling range styles
+++ Advanced layouts with pager
+++ Customizing pager layout

manual/docs/en/pagination/advanced-layouts-with-pager.txt

@@ -0,0 +1,34 @@
+TBD
+
+Basic pager layout usage:
+
+<code type="php">
+// Creating pager layout
+$pager_layout = new Doctrine_Pager_Layout(
+    new Doctrine_Pager(
+        Doctrine_Query::create()
+            ->from( 'User u' )
+            ->leftJoin( 'u.Group g' )
+            ->orderby( 'u.username ASC' ),
+        $currentPage,
+        $resultsPerPage
+    ),
+    new Doctrine_Pager_Range_Sliding(array(
+        'chunk' => 5
+    )),
+    'http://wwww.domain.com/app/User/list/page,{%page}'
+);
+
+// Assigning templates for page links creation
+$pager_layout->setTemplate('[<a href="{%url}">{%page}</a>]');
+$pager_layout->setSelectedTemplate('[{%page}]');
+
+// Retireving Doctrine_Pager instance
+$pager = $pager_layout->getPager();
+
+// Fetching users
+$users = $pager->execute();
+
+// Displaying page links
+echo $pager_layout->display();
+</code>

manual/docs/en/pagination/controlling-range-styles.txt

@@ -0,0 +1,78 @@
+There are some cases where simple paginations are not enough. One example situation is when you want to write page links listings.
+To enable a more powerful control over pager, there is a small subset of pager package that allows you to create ranges.
+
+Currently, Doctrine implements two types (or styles) of ranges: Sliding ({{Doctrine_Pager_Range_Sliding}}) and Jumping ({{Doctrine_Pager_Range_Jumping}}).
+
++++ Sliding
+
+Sliding page range style, the page range moves smoothly with the current page. The current page is always in the middle, except in the first and last pages of the range.
+Check out how does it work with a chunk length of 5 items:
+
+<code>
+Listing 1 2 3 4 5 6 7 8 9 10 11 12 13 14
+Page 1: o-------|
+Page 2: |-o-----|
+Page 3: |---o---|
+Page 4:   |---o---|
+Page 5:     |---o---|
+Page 6:       |---o---|
+Page 7:         |---o---|
+Page 8:           |---o---|
+</code>
+
++++ Jumping
+
+In Jumping page range style, the range of page links is always one of a fixed set of "frames": 1-5, 6-10, 11-15, and so on.
+
+<code>
+Listing 1 2 3 4 5 6 7 8 9 10 11 12 13 14
+Page 1: o-------|
+Page 2: |-o-----|
+Page 3: |---o---|
+Page 4: |-----o-|
+Page 5: |-------o
+Page 6:           o---------|
+Page 7:           |-o-------|
+Page 8:           |---o-----|
+</code>
+
+
+Now that we know how the different of styles of pager range works, it's time to learn how to use them:
+
+<code type="php">
+$pager_range = new Doctrine_Pager_Range_Sliding(
+    array(
+        'chunk' => 5 // Chunk length
+    ),
+    $pager // Doctrine_Pager object we learned how to create in previous topic
+);
+</code>
+
+What is the advantage to use this object, instead of the {{Doctrine_Pager}}? Just one; it allows you to retrieve ranges around the current page.
+Look at the example:
+
+<code type="php">
+// Retrieves the range around the current page
+// In our example, we are using sliding style and we are at page 1
+$pages = $pager_range->rangeAroundPage();
+
+// Outputs: [1][2][3][4][5]
+echo '['. implode('][', $pages) .']';
+</code>
+
+If you build your {{Doctrine_Pager}} inside the range object, the API gives you enough power to retrieve information related to {{Doctrine_Pager_Range}} subclass instance:
+
+<code type="php">
+// Return the Pager associated to this Pager_Range
+$pager_range->getPager();
+
+// Defines a new Doctrine_Pager (automatically call _initialize protected method)
+$pager_range->setPager($pager);
+
+// Return the options assigned to the current Pager_Range
+$pager_range->getOptions();
+
+// Return the range around the current page (obtained from Doctrine_Pager
+// associated to the $pager_range instance)
+$pager_range->rangeAroundPage();
+</code>

manual/docs/en/pagination/customizing-pager-layout.txt

@@ -0,0 +1 @@
+TBD

manual/docs/en/pagination/introduction.txt

@@ -0,0 +1,4 @@
+In real world applications, display content from database tables is a commom task. Also, imagine that this content is a search result containing thousands of items. Undoubtely, it will be a huge listing, memory expensive and hard for users to find the right item. That is where some organization of this content display is needed and pagination comes in rescue.
+
+Doctrine implements a highly flexible pager package, allowing you to not only split listing in pages, but also enabling you to control the layout of page links. 
+In this chapter, we'll learn how to create pager objects, control pager styles and at the end, overview the pager layout object - a powerful page links displayer of Doctrine.

manual/docs/en/pagination/working-with-pager.txt

@@ -0,0 +1,69 @@
+Paginating queries is as simple as effectively do the queries itself. {{Doctrine_Pager}} is the responsible to process queries and paginate them. Check out this small piece of code:
+
+<code type="php">
+// Defining initial variables
+$currentPage = 1;
+$resultsPerPage = 50;
+
+// Creating pager object
+$pager = new Doctrine_Pager(
+    Doctrine_Query::create()
+        ->from( 'User u' )
+        ->leftJoin( 'u.Group g' )
+        ->orderby( 'u.username ASC' ),
+    $currentPage, // Current page of request
+    $resultsPerPage // (Optional) Number of results per page. Default is 25
+);
+</code>
+
+Until this place, the source you have is the same as the old {{Doctrine_Query}} object. The only difference is that now you have 2 new arguments. Your old query object plus these 2 arguments are now encapsulated by the {{Doctrine_Pager}} object.
+At this stage, {{Doctrine_Pager}} already sent a dummy query to database to collect useful information to allow you to access them before even execute the real query. Let's say for example you want to know how many matches were found:
+
+<code type="php">
+echo 'Total of items found: ' . $pager->getNumResults();
+</code>
+
+There are a couple of other interesting information that can be retrieved from pager before you execute the query. The API usage is listed at the end of this topic.
+
+To run the query, the process is similar to the current existent {{Doctrine_Query}} execute call. It even allow arguments the way you usually do it. Here is the PHP complete syntax, including the syntax of optional parameters:
+
+<code type="php">
+$pager->execute([$args = array() [, $fetchType = Doctrine::FETCH_RECORD]]);
+</code>
+
+If you need access the other functionalities that {{Doctrine_Pager}} provides, you can access them through the API:
+
+<code type="php">
+// Return the total number of itens found on query search
+$pager->getNumResults();
+
+// Return the first page (always 1)
+$pager->getFirstPage();
+
+// Return the total number of pages
+$pager->getLastPage();
+
+// Return the current page
+$pager->getPage();
+
+// Defines a new current page (automatically adjust offsets and values)
+$pager->setPage($page);
+
+// Return the next page
+$pager->getNextPage();
+
+// Return the previous page
+$pager->getPreviousPage();
+
+// Return true if it's necessary to paginate or false if not
+$pager->haveToPaginate();
+
+// Return the maximum number of records per page
+$pager->getMaxPerPage();
+
+// Defined a new maximum number of records per page (automatically adjust offset and values)
+$pager->setMaxPerPage($maxPerPage);
+
+// Return the Doctrine_Query object
+$pager->getQuery();
+</code>