Changeset 3872

Show
Ignore:
Timestamp:
02/21/08 04:33:03 (17 months ago)
Author:
guilhermeblanco
Message:

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

Files:
12 modified

Legend:

Unmodified
Added
Removed

  • branches/0.10/manual/docs/en/utilities/pagination/advanced-layouts-with-pager.txt

    r3424 r3872  
    3737        'chunk' => 5 
    3838    )), 
    39     'http://wwww.domain.com/app/User/list/page,{%page}' 
     39    'http://wwww.domain.com/app/User/list/page,{%page_number}' 
    4040); 
    4141 
    … …  
    4848 
    4949// Fetching users 
    50 $users = $pager->execute(); 
     50$users = $pager->execute(); // This is possible too! 
    5151 
    5252// Displaying page links 
    … …  
    7676        'chunk' => 5 
    7777    )), 
    78     'http://wwww.domain.com/app/User/list/page,{%page}?search={%search}' 
     78    'http://wwww.domain.com/app/User/list/page,{%page_number}?search={%search}' 
    7979); 
    8080</code> 
    … …  
    8888$pager_layout->setSelectedTemplate('[{%page}]'); 
    8989 
    90 // Retrieving Doctrine_Pager instance 
    91 $pager = $pager_layout->getPager(); 
    92  
    9390// Fetching users 
    94 $users = $pager->execute(); 
     91$users = $pager_layout->execute(); 
    9592</code> 
    9693 
    … …  
    124121$pager_layout->getSelectedTemplate(); 
    125122 
     123// Defines the Separator template, applied between each page 
     124$pager_layout->setSeparatorTemplate($separatorTemplate); 
     125 
    126126// Return the current page template associated to the Pager_Layout 
    127127$pager_layout->getSeparatorTemplate(); 
     128 
     129// Handy method to execute the query without need to retrieve the Pager instance 
     130$pager_layout->execute($params = array(), $hydrationMode = Doctrine::FETCH_RECORD); 
    128131</code> 
    129132 
     133There 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. 

  • branches/0.10/manual/docs/en/utilities/pagination/controlling-range-styles.txt

    r3424 r3872  
    7373$pager_range->getOptions(); 
    7474 
     75// Returns the custom Doctrine_Pager_Range implementation offset option 
     76$pager_range->getOption($option); 
     77 
    7578// Return the range around the current page (obtained from Doctrine_Pager 
    7679// associated to the $pager_range instance) 

  • branches/0.10/manual/docs/en/utilities/pagination/customizing-pager-layout.txt

    r3424 r3872  
    1 TBD 
     1{{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: 
    22 
    3 Basic customization to generate this page links generation: 
     3<<  <  1 2 3 4 5  >  >> 
    44 
    5 � � 1 2 3 4 5 � � 
     5Currently, 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: 
    66 
    77<code type="php"> 
    8 class PagerLayout extends Doctrine_Pager_Layout 
     8// $this refers to an instance of Doctrine_Pager_Layout 
     9 
     10// Defines a mask replacement. When parsing template, it converts replacement 
     11// masks into new ones (or values), allowing to change masks behavior on the fly 
     12$this->addMaskReplacement($oldMask, $newMask, $asValue = false); 
     13 
     14// Remove a mask replacement 
     15$this->removeMaskReplacement($oldMask); 
     16 
     17// Remove all mask replacements 
     18$this->cleanMaskReplacements(); 
     19 
     20// Parses the template and returns the string of a processed page 
     21$this->processPage($options = array()); // Needs at least page_number offset in $options array 
     22</code> 
     23 
     24Now 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: 
     25 
     26<code type="php"> 
     27class PagerLayoutWithArrows extends Doctrine_Pager_Layout 
    928{ 
    10         public function initialize() 
     29        public function display($options = array(), $return = false) 
    1130        { 
    12         } 
    13  
    14  
    15         public function display($options = array(), $return = false) 
    16     { 
     31                $pager = $this->getPager(); 
    1732                $str = ''; 
    1833 
    1934                // First page 
    20         $options['page_number'] = $this->getPager()->getFirstPage(); 
    21         $options['page'] = '&laquo;'; 
    22         $options['url'] = $this->_parseUrl($options); 
    23  
    24                 $str .= $this->_parseTemplate($options); 
     35                $this->addMaskReplacement('page', '&laquo;', true); 
     36                $options['page_number'] = $pager->getFirstPage(); 
     37                $str .= $this->processPage($options); 
    2538 
    2639                // Previous page 
    27                 $options['page_number'] = $this->getPager()->getPreviousPage(); 
    28         $options['page'] = '&lsaquo;'; 
    29         $options['url'] = $this->_parseUrl($options); 
     40                $this->addMaskReplacement('page', '&lsaquo;', true); 
     41                $options['page_number'] = $pager->getPreviousPage(); 
     42                $str .= $this->processPage($options); 
    3043 
    31                 $str .= $this->_parseTemplate($options); 
    32  
    33                 // Current chunk 
    34  
    35                 // Removing page, page_mask and url 
    36                 unset($options['page']); 
    37                 unset($options['page_text']); 
    38                 unset($options['url']); 
    39  
     44                // Pages listing 
     45                $this->removeMaskReplacement('page'); 
    4046                $str .= parent::display($options, true); 
    4147 
    4248                // Next page 
    43                 $options['page_number'] = $this->getPager()->getNextPage(); 
    44         $options['page'] = '&rsaquo;'; 
    45         $options['url'] = $this->_parseUrl($options); 
    46  
    47                 $str .= $this->_parseTemplate($options); 
     49                $this->addMaskReplacement('page', '&rsaquo;', true); 
     50                $options['page_number'] = $pager->getNextPage(); 
     51                $str .= $this->processPage($options); 
    4852 
    4953                // Last page 
    50                 $options['page_number'] = $this->getPager()->getLastPage(); 
    51         $options['page'] = '&raquo;'; 
    52                 $options['url'] = $this->_parseUrl($options); 
    53  
    54                 $str .= $this->_parseTemplate($options); 
     54                $this->addMaskReplacement('page', '&raquo;', true); 
     55                $options['page_number'] = $pager->getLastPage(); 
     56                $str .= $this->processPage($options); 
    5557 
    5658                // Possible wish to return value instead of print it on screen 
    57         if ($return) { 
    58             return $str; 
    59         } 
     59                if ($return) { 
     60                        return $str; 
     61                } 
    6062 
    61         echo $str; 
     63                echo $str; 
    6264        } 
    6365} 

  • branches/0.10/manual/docs/en/utilities/pagination/working-with-pager.txt

    r3424 r3872  
    1818 
    1919Until 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. 
    20 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: 
     20At 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: 
    2121 
    2222<code type="php"> 
    23 echo 'Total of items found: ' . $pager->getNumResults(); 
     23$pager->getExecuted(); 
    2424</code> 
    2525 
    26 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. 
     26If 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. 
    2727 
    2828To 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: 
    … …  
    3232</code> 
    3333 
     34There 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: 
     35 
     36<code type="php"> 
     37$pager->setCountQuery($query [, $params = null]); 
     38 
     39// ... 
     40 
     41$rs = $pager->execute(); 
     42</code> 
     43 
     44The 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}}: 
     45 
     46<code type="php"> 
     47$pager->setCountQueryParams([$params = array() [, $append = false]]); 
     48</code> 
     49 
     50This 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. 
     51One 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. 
     52 
     53Count 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. 
     54 
    3455If you need access the other functionalities that {{Doctrine_Pager}} provides, you can access them through the API: 
    3556 
    3657<code type="php"> 
     58// Returns the check if Pager was already executed 
     59$pager->getExecuted(); 
     60 
    3761// Return the total number of itens found on query search 
    3862$pager->getNumResults(); 
    … …  
    4771$pager->getPage(); 
    4872 
    49 // Defines a new current page (automatically adjust offsets and values) 
     73// Defines a new current page (need to call execute again to adjust offsets and values) 
    5074$pager->setPage($page); 
    5175 
    … …  
    6286$pager->getMaxPerPage(); 
    6387 
    64 // Defined a new maximum number of records per page (automatically adjust offset and values) 
     88// Defined a new maximum number of records per page (need to call execute again to adjust offset and values) 
    6589$pager->setMaxPerPage($maxPerPage); 
     90 
     91// Returns the number of itens in current page 
     92$pager->getResultsInPage(); 
     93 
     94// Returns the Doctrine_Query object that is used to make the count results to pager 
     95$pager->getCountQuery(); 
     96 
     97// Defines the counter query to be used by pager 
     98$pager->setCountQuery($query, $params = null); 
     99 
     100// Returns the params to be used by counter Doctrine_Query (return $defaultParams if no param is defined) 
     101$pager->getCountQueryParams($defaultParams = array()); 
     102 
     103// Defines the params to be used by counter Doctrine_Query 
     104$pager->setCountQueryParams($params = array(), $append = false); 
    66105 
    67106// Return the Doctrine_Query object 

  • trunk/lib/Doctrine/Pager/Layout.php

    r3570 r3872  
    195195     * getTemplate 
    196196     * 
    197      * Returns the Template to be applied for inactive pages  
     197     * Returns the Template to be applied for inactive pages 
    198198     * 
    199199     * @return string        Template to be applied for inactive pages 

  • trunk/lib/Doctrine/Pager/Range.php

    r3570 r3872  
    3535{ 
    3636    /** 
    37      * @var array $options     Custom Doctrine_Pager_Range implementation options 
     37     * @var array $_options     Custom Doctrine_Pager_Range implementation options 
    3838     */ 
    39         protected $options; 
     39    protected $_options; 
    4040 
    4141    /** 
    … …  
    105105    public function getOptions() 
    106106    { 
    107         return $this->options; 
     107        return $this->_options; 
     108    } 
     109 
     110 
     111    /** 
     112     * getOption 
     113     * 
     114     * Returns the custom Doctrine_Pager_Range implementation offset option 
     115     * 
     116     * @return array        Custom Doctrine_Pager_Range implementation options 
     117     */ 
     118    public function getOption($option) 
     119    { 
     120        if (isset($this->_options[$option])) { 
     121            return $this->_options[$option]; 
     122        } 
     123 
     124        throw new Doctrine_Pager_Exception( 
     125            'Cannot access unexistent option \'' . $option . '\' in Doctrine_Pager_Range class' 
     126        ); 
    108127    } 
    109128 
    … …  
    119138    protected function _setOptions($options) 
    120139    { 
    121         $this->options = $options; 
     140        $this->_options = $options; 
    122141    } 
    123142 

  • trunk/lib/Doctrine/Pager/Range/Jumping.php

    r3570 r3872  
    5151    protected function _initialize() 
    5252    { 
    53         if (isset($this->options['chunk'])) { 
    54             $this->_setChunkLength($this->options['chunk']); 
     53        if (isset($this->_options['chunk'])) { 
     54            $this->_setChunkLength($this->_options['chunk']); 
    5555        } else { 
    5656            throw new Doctrine_Pager_Exception('Missing parameter \'chunk\' that must be define in options.'); 

  • trunk/lib/Doctrine/Pager/Range/Sliding.php

    r3570 r3872  
    5151    protected function _initialize() 
    5252    { 
    53         if (isset($this->options['chunk'])) { 
    54             $this->_setChunkLength($this->options['chunk']); 
     53        if (isset($this->_options['chunk'])) { 
     54            $this->_setChunkLength($this->_options['chunk']); 
    5555        } else { 
    5656            throw new Doctrine_Pager_Exception('Missing parameter \'chunk\' that must be defined in options.'); 

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

    r3424 r3872  
    3737        'chunk' => 5 
    3838    )), 
    39     'http://wwww.domain.com/app/User/list/page,{%page}' 
     39    'http://wwww.domain.com/app/User/list/page,{%page_number}' 
    4040); 
    4141 
    … …  
    4848 
    4949// Fetching users 
    50 $users = $pager->execute(); 
     50$users = $pager->execute(); // This is possible too! 
    5151 
    5252// Displaying page links 
    … …  
    7676        'chunk' => 5 
    7777    )), 
    78     'http://wwww.domain.com/app/User/list/page,{%page}?search={%search}' 
     78    'http://wwww.domain.com/app/User/list/page,{%page_number}?search={%search}' 
    7979); 
    8080</code> 
    … …  
    8888$pager_layout->setSelectedTemplate('[{%page}]'); 
    8989 
    90 // Retrieving Doctrine_Pager instance 
    91 $pager = $pager_layout->getPager(); 
    92  
    9390// Fetching users 
    94 $users = $pager->execute(); 
     91$users = $pager_layout->execute(); 
    9592</code> 
    9693 
    … …  
    124121$pager_layout->getSelectedTemplate(); 
    125122 
     123// Defines the Separator template, applied between each page 
     124$pager_layout->setSeparatorTemplate($separatorTemplate); 
     125 
    126126// Return the current page template associated to the Pager_Layout 
    127127$pager_layout->getSeparatorTemplate(); 
     128 
     129// Handy method to execute the query without need to retrieve the Pager instance 
     130$pager_layout->execute($params = array(), $hydrationMode = Doctrine::FETCH_RECORD); 
    128131</code> 
    129132 
     133There 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. 

  • trunk/manual/docs/en/utilities/pagination/controlling-range-styles.txt

    r3424 r3872  
    7373$pager_range->getOptions(); 
    7474 
     75// Returns the custom Doctrine_Pager_Range implementation offset option 
     76$pager_range->getOption($option); 
     77 
    7578// Return the range around the current page (obtained from Doctrine_Pager 
    7679// associated to the $pager_range instance) 

  • trunk/manual/docs/en/utilities/pagination/customizing-pager-layout.txt

    r3424 r3872  
    1 TBD 
     1{{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: 
    22 
    3 Basic customization to generate this page links generation: 
     3<<  <  1 2 3 4 5  >  >> 
    44 
    5 � � 1 2 3 4 5 � � 
     5Currently, 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: 
    66 
    77<code type="php"> 
    8 class PagerLayout extends Doctrine_Pager_Layout 
     8// $this refers to an instance of Doctrine_Pager_Layout 
     9 
     10// Defines a mask replacement. When parsing template, it converts replacement 
     11// masks into new ones (or values), allowing to change masks behavior on the fly 
     12$this->addMaskReplacement($oldMask, $newMask, $asValue = false); 
     13 
     14// Remove a mask replacement 
     15$this->removeMaskReplacement($oldMask); 
     16 
     17// Remove all mask replacements 
     18$this->cleanMaskReplacements(); 
     19 
     20// Parses the template and returns the string of a processed page 
     21$this->processPage($options = array()); // Needs at least page_number offset in $options array 
     22</code> 
     23 
     24Now 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: 
     25 
     26<code type="php"> 
     27class PagerLayoutWithArrows extends Doctrine_Pager_Layout 
    928{ 
    10         public function initialize() 
     29        public function display($options = array(), $return = false) 
    1130        { 
    12         } 
    13  
    14  
    15         public function display($options = array(), $return = false) 
    16     { 
     31                $pager = $this->getPager(); 
    1732                $str = ''; 
    1833 
    1934                // First page 
    20         $options['page_number'] = $this->getPager()->getFirstPage(); 
    21         $options['page'] = '&laquo;'; 
    22         $options['url'] = $this->_parseUrl($options); 
    23  
    24                 $str .= $this->_parseTemplate($options); 
     35                $this->addMaskReplacement('page', '&laquo;', true); 
     36                $options['page_number'] = $pager->getFirstPage(); 
     37                $str .= $this->processPage($options); 
    2538 
    2639                // Previous page 
    27                 $options['page_number'] = $this->getPager()->getPreviousPage(); 
    28         $options['page'] = '&lsaquo;'; 
    29         $options['url'] = $this->_parseUrl($options); 
     40                $this->addMaskReplacement('page', '&lsaquo;', true); 
     41                $options['page_number'] = $pager->getPreviousPage(); 
     42                $str .= $this->processPage($options); 
    3043 
    31                 $str .= $this->_parseTemplate($options); 
    32  
    33                 // Current chunk 
    34  
    35                 // Removing page, page_mask and url 
    36                 unset($options['page']); 
    37                 unset($options['page_text']); 
    38                 unset($options['url']); 
    39  
     44                // Pages listing 
     45                $this->removeMaskReplacement('page'); 
    4046                $str .= parent::display($options, true); 
    4147 
    4248                // Next page 
    43                 $options['page_number'] = $this->getPager()->getNextPage(); 
    44         $options['page'] = '&rsaquo;'; 
    45         $options['url'] = $this->_parseUrl($options); 
    46  
    47                 $str .= $this->_parseTemplate($options); 
     49                $this->addMaskReplacement('page', '&rsaquo;', true); 
     50                $options['page_number'] = $pager->getNextPage(); 
     51                $str .= $this->processPage($options); 
    4852 
    4953                // Last page 
    50                 $options['page_number'] = $this->getPager()->getLastPage(); 
    51         $options['page'] = '&raquo;'; 
    52                 $options['url'] = $this->_parseUrl($options); 
    53  
    54                 $str .= $this->_parseTemplate($options); 
     54                $this->addMaskReplacement('page', '&raquo;', true); 
     55                $options['page_number'] = $pager->getLastPage(); 
     56                $str .= $this->processPage($options); 
    5557 
    5658                // Possible wish to return value instead of print it on screen 
    57         if ($return) { 
    58             return $str; 
    59         } 
     59                if ($return) { 
     60                        return $str; 
     61                } 
    6062 
    61         echo $str; 
     63                echo $str; 
    6264        } 
    6365} 

  • trunk/manual/docs/en/utilities/pagination/working-with-pager.txt

    r3424 r3872  
    1818 
    1919Until 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. 
    20 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: 
     20At 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: 
    2121 
    2222<code type="php"> 
    23 echo 'Total of items found: ' . $pager->getNumResults(); 
     23$pager->getExecuted(); 
    2424</code> 
    2525 
    26 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. 
     26If 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. 
    2727 
    2828To 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: 
    … …  
    3232</code> 
    3333 
     34There 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: 
     35 
     36<code type="php"> 
     37$pager->setCountQuery($query [, $params = null]); 
     38 
     39// ... 
     40 
     41$rs = $pager->execute(); 
     42</code> 
     43 
     44The 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}}: 
     45 
     46<code type="php"> 
     47$pager->setCountQueryParams([$params = array() [, $append = false]]); 
     48</code> 
     49 
     50This 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. 
     51One 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. 
     52 
     53Count 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. 
     54 
    3455If you need access the other functionalities that {{Doctrine_Pager}} provides, you can access them through the API: 
    3556 
    3657<code type="php"> 
     58// Returns the check if Pager was already executed 
     59$pager->getExecuted(); 
     60 
    3761// Return the total number of itens found on query search 
    3862$pager->getNumResults(); 
    … …  
    4771$pager->getPage(); 
    4872 
    49 // Defines a new current page (automatically adjust offsets and values) 
     73// Defines a new current page (need to call execute again to adjust offsets and values) 
    5074$pager->setPage($page); 
    5175 
    … …  
    6286$pager->getMaxPerPage(); 
    6387 
    64 // Defined a new maximum number of records per page (automatically adjust offset and values) 
     88// Defined a new maximum number of records per page (need to call execute again to adjust offset and values) 
    6589$pager->setMaxPerPage($maxPerPage); 
     90 
     91// Returns the number of itens in current page 
     92$pager->getResultsInPage(); 
     93 
     94// Returns the Doctrine_Query object that is used to make the count results to pager 
     95$pager->getCountQuery(); 
     96 
     97// Defines the counter query to be used by pager 
     98$pager->setCountQuery($query, $params = null); 
     99 
     100// Returns the params to be used by counter Doctrine_Query (return $defaultParams if no param is defined) 
     101$pager->getCountQueryParams($defaultParams = array()); 
     102 
     103// Defines the params to be used by counter Doctrine_Query 
     104$pager->setCountQueryParams($params = array(), $append = false); 
    66105 
    67106// Return the Doctrine_Query object