RetailCRM-Mirror/doctrine2
1
0
Fork 0
mirror of synced 2024-12-13 14:56:01 +03:00
Code Issues Projects Releases Wiki Activity

Updated pagination chapter in manual (0.10 and trunk). Merged r3870 in trunk

Browse Source
This commit is contained in:
guilhermeblanco 2008-02-21 04:33:03 +00:00
parent 85e26cfd7b
commit 1ab785ac44
8 changed files with 129 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
lib/Doctrine/Pager/Layout.php
View File

@ -194,7 +194,7 @@ class Doctrine_Pager_Layout
/**
* getTemplate
*
* Returns the Template to be applied for inactive pages
* Returns the Template to be applied for inactive pages
*
* @return string Template to be applied for inactive pages
*/

27
lib/Doctrine/Pager/Range.php
View File

@ -34,9 +34,9 @@
abstract class Doctrine_Pager_Range
{
/**
* @var array $options Custom Doctrine_Pager_Range implementation options
* @var array $_options Custom Doctrine_Pager_Range implementation options
*/
protected $options;
protected $_options;
/**
* @var Doctrine_Pager $pager Doctrine_Pager object related to the pager range
@ -104,7 +104,26 @@ abstract class Doctrine_Pager_Range
*/
public function getOptions()
{
return $this->options;
return $this->_options;
}
/**
* getOption
*
* Returns the custom Doctrine_Pager_Range implementation offset option
*
* @return array Custom Doctrine_Pager_Range implementation options
*/
public function getOption($option)
{
if (isset($this->_options[$option])) {
return $this->_options[$option];
}
throw new Doctrine_Pager_Exception(
'Cannot access unexistent option \'' . $option . '\' in Doctrine_Pager_Range class'
);
}
@ -118,7 +137,7 @@ abstract class Doctrine_Pager_Range
*/
protected function _setOptions($options)
{
$this->options = $options;
$this->_options = $options;
}

4
lib/Doctrine/Pager/Range/Jumping.php
View File

@ -50,8 +50,8 @@ class Doctrine_Pager_Range_Jumping extends Doctrine_Pager_Range
*/
protected function _initialize()
{
if (isset($this->options['chunk'])) {
$this->_setChunkLength($this->options['chunk']);
if (isset($this->_options['chunk'])) {
$this->_setChunkLength($this->_options['chunk']);
} else {
throw new Doctrine_Pager_Exception('Missing parameter \'chunk\' that must be define in options.');
}

4
lib/Doctrine/Pager/Range/Sliding.php
View File

@ -50,8 +50,8 @@ class Doctrine_Pager_Range_Sliding extends Doctrine_Pager_Range
*/
protected function _initialize()
{
if (isset($this->options['chunk'])) {
$this->_setChunkLength($this->options['chunk']);
if (isset($this->_options['chunk'])) {
$this->_setChunkLength($this->_options['chunk']);
} else {
throw new Doctrine_Pager_Exception('Missing parameter \'chunk\' that must be defined in options.');
}

18
manual/docs/en/utilities/pagination/advanced-layouts-with-pager.txt
View File

@ -36,7 +36,7 @@ $pager_layout = new Doctrine_Pager_Layout(
new Doctrine_Pager_Range_Sliding(array(
'chunk' => 5
)),
'http://wwww.domain.com/app/User/list/page,{%page}'
'http://wwww.domain.com/app/User/list/page,{%page_number}'
);
// Assigning templates for page links creation
@ -47,7 +47,7 @@ $pager_layout->setSelectedTemplate('[{%page}]');
$pager = $pager_layout->getPager();
// Fetching users
$users = $pager->execute();
$users = $pager->execute(); // This is possible too!
// Displaying page links
// Displays: [1][2][3][4][5]
@ -75,7 +75,7 @@ $pager_layout = new Doctrine_Pager_Layout(
new Doctrine_Pager_Range_Sliding(array(
'chunk' => 5
)),
'http://wwww.domain.com/app/User/list/page,{%page}?search={%search}'
'http://wwww.domain.com/app/User/list/page,{%page_number}?search={%search}'
);
</code>
@ -87,11 +87,8 @@ We then assign the templates, just as defined before, without any change. And al
$pager_layout->setTemplate('[<a href="{%url}">{%page}</a>]');
$pager_layout->setSelectedTemplate('[{%page}]');
// Retrieving Doctrine_Pager instance
$pager = $pager_layout->getPager();
// Fetching users
$users = $pager->execute();
$users = $pager_layout->execute();
</code>
The method {{display()}} is the place where we define the custom mask we created. This method accepts 2 optional arguments: one array of optional masks and if the output should be returned instead of printed on screen.
@ -123,7 +120,14 @@ $pager_layout->getTemplate();
// Return the current page template associated to the Pager_Layout
$pager_layout->getSelectedTemplate();
// Defines the Separator template, applied between each page
$pager_layout->setSeparatorTemplate($separatorTemplate);
// Return the current page template associated to the Pager_Layout
$pager_layout->getSeparatorTemplate();
// Handy method to execute the query without need to retrieve the Pager instance
$pager_layout->execute($params = array(), $hydrationMode = Doctrine::FETCH_RECORD);
</code>
There are a couple of other methods that are available if you want to extend the {{Doctrine_Pager_Layout}} to create you custom layouter. We will see these methods in the next section.

3
manual/docs/en/utilities/pagination/controlling-range-styles.txt
View File

@ -72,6 +72,9 @@ $pager_range->setPager($pager);
// Return the options assigned to the current Pager_Range
$pager_range->getOptions();
// Returns the custom Doctrine_Pager_Range implementation offset option
$pager_range->getOption($option);
// Return the range around the current page (obtained from Doctrine_Pager
// associated to the $pager_range instance)
$pager_range->rangeAroundPage();

84
manual/docs/en/utilities/pagination/customizing-pager-layout.txt
View File

@ -1,64 +1,66 @@
TBD
{{Doctrine_Pager_Layout}} does a really good job, but sometimes it is not enough. Let's suppose a situation where you have to create a layout of pagination like this one:
Basic customization to generate this page links generation:
<< < 1 2 3 4 5 > >>
« ‹ 1 2 3 4 5 › »
Currently, it is impossible with raw {{Doctrine_Pager_Layout}}. But if you extend it and use the available methods, you can achieve it. The base Layout class provides you some methods that can be used to create your own implementation. They are:
<code type="php">
class PagerLayout extends Doctrine_Pager_Layout
// $this refers to an instance of Doctrine_Pager_Layout
// Defines a mask replacement. When parsing template, it converts replacement
// masks into new ones (or values), allowing to change masks behavior on the fly
$this->addMaskReplacement($oldMask, $newMask, $asValue = false);
// Remove a mask replacement
$this->removeMaskReplacement($oldMask);
// Remove all mask replacements
$this->cleanMaskReplacements();
// Parses the template and returns the string of a processed page
$this->processPage($options = array()); // Needs at least page_number offset in $options array
</code>
Now that you have a small tip of useful methods to be used when extending {{Doctrine_Pager_Layout}}, it's time to see our implemented class:
<code type="php">
class PagerLayoutWithArrows extends Doctrine_Pager_Layout
{
public function initialize()
{
}
public function display($options = array(), $return = false)
{
{
$pager = $this->getPager();
$str = '';
// First page
$options['page_number'] = $this->getPager()->getFirstPage();
$options['page'] = '&laquo;';
$options['url'] = $this->_parseUrl($options);
$str .= $this->_parseTemplate($options);
$this->addMaskReplacement('page', '&laquo;', true);
$options['page_number'] = $pager->getFirstPage();
$str .= $this->processPage($options);
// Previous page
$options['page_number'] = $this->getPager()->getPreviousPage();
$options['page'] = '&lsaquo;';
$options['url'] = $this->_parseUrl($options);
$str .= $this->_parseTemplate($options);
// Current chunk
// Removing page, page_mask and url
unset($options['page']);
unset($options['page_text']);
unset($options['url']);
$this->addMaskReplacement('page', '&lsaquo;', true);
$options['page_number'] = $pager->getPreviousPage();
$str .= $this->processPage($options);
// Pages listing
$this->removeMaskReplacement('page');
$str .= parent::display($options, true);
// Next page
$options['page_number'] = $this->getPager()->getNextPage();
$options['page'] = '&rsaquo;';
$options['url'] = $this->_parseUrl($options);
$str .= $this->_parseTemplate($options);
$this->addMaskReplacement('page', '&rsaquo;', true);
$options['page_number'] = $pager->getNextPage();
$str .= $this->processPage($options);
// Last page
$options['page_number'] = $this->getPager()->getLastPage();
$options['page'] = '&raquo;';
$options['url'] = $this->_parseUrl($options);
$str .= $this->_parseTemplate($options);
$this->addMaskReplacement('page', '&raquo;', true);
$options['page_number'] = $pager->getLastPage();
$str .= $this->processPage($options);
// Possible wish to return value instead of print it on screen
if ($return) {
return $str;
}
if ($return) {
return $str;
}
echo $str;
echo $str;
}
}
</code>

49
manual/docs/en/utilities/pagination/working-with-pager.txt
View File

@ -17,13 +17,13 @@ $pager = new Doctrine_Pager(
</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:
At this stage, {{Doctrine_Pager}} defines the basic data needed to control pagination. If you want to know that actual status of the pager, all you have to do is to check if it's already executed:
<code type="php">
echo 'Total of items found: ' . $pager->getNumResults();
$pager->getExecuted();
</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.
If you try to access any of the methods provided by Doctrine_Pager now, you'll experience {{Doctrine_Pager_Exception}} thrown, reporting you that Pager was not yet executed. When executed, {{Doctrine_Pager}} offer you powerful methods to retrieve information. 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:
@ -31,9 +31,33 @@ To run the query, the process is similar to the current existent {{Doctrine_Quer
$pager->execute([$args = array() [, $fetchType = Doctrine::FETCH_RECORD]]);
</code>
There are some special cases where the return records query differ of the counter query. To allow this situation, {{Doctrine_Pager}} has some methods that enable you to count and then to execute. The first thing you have to do is to define the count query:
<code type="php">
$pager->setCountQuery($query [, $params = null]);
// ...
$rs = $pager->execute();
</code>
The first param of {{setCountQuery}} can be either a valid {{Doctrine_Query}} object or a DQL string. The second argument you can define the optional parameters that may be sent in the counter query. If you do not define the params now, you're still able to define it later by calling the {{setCountQueryParams}}:
<code type="php">
$pager->setCountQueryParams([$params = array() [, $append = false]]);
</code>
This method accepts 2 parameters. The first one is the params to be sent in count query and the second parameter is if the {{$params}} should be appended to the list or if it should override the list of count query parameters. The default behavior is to override the list.
One last thing to mention about count query is, if you do not define any parameter for count query, it will still send the parameters you define in {{$pager->execute()}} call.
Count query is always enabled to be accessed. If you do not define it and call {{$pager->getCountQuery()}}, it will return the "fetcher" query to you.
If you need access the other functionalities that {{Doctrine_Pager}} provides, you can access them through the API:
<code type="php">
// Returns the check if Pager was already executed
$pager->getExecuted();
// Return the total number of itens found on query search
$pager->getNumResults();
@ -46,7 +70,7 @@ $pager->getLastPage();
// Return the current page
$pager->getPage();
// Defines a new current page (automatically adjust offsets and values)
// Defines a new current page (need to call execute again to adjust offsets and values)
$pager->setPage($page);
// Return the next page
@ -61,9 +85,24 @@ $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)
// Defined a new maximum number of records per page (need to call execute again to adjust offset and values)
$pager->setMaxPerPage($maxPerPage);
// Returns the number of itens in current page
$pager->getResultsInPage();
// Returns the Doctrine_Query object that is used to make the count results to pager
$pager->getCountQuery();
// Defines the counter query to be used by pager
$pager->setCountQuery($query, $params = null);
// Returns the params to be used by counter Doctrine_Query (return $defaultParams if no param is defined)
$pager->getCountQueryParams($defaultParams = array());
// Defines the params to be used by counter Doctrine_Query
$pager->setCountQueryParams($params = array(), $append = false);
// Return the Doctrine_Query object
$pager->getQuery();
</code>