| Index: trunk/phase3/includes/Pager.php |
| — | — | @@ -12,42 +12,43 @@ |
| 13 | 13 | /** |
| 14 | 14 | * IndexPager is an efficient pager which uses a (roughly unique) index in the |
| 15 | 15 | * data set to implement paging, rather than a "LIMIT offset,limit" clause. |
| 16 | | - * In MySQL, such a limit/offset clause requires counting through the specified number |
| 17 | | - * of offset rows to find the desired data, which can be expensive for large offsets. |
| | 16 | + * In MySQL, such a limit/offset clause requires counting through the |
| | 17 | + * specified number of offset rows to find the desired data, which can be |
| | 18 | + * expensive for large offsets. |
| 18 | 19 | * |
| 19 | | - * ReverseChronologicalPager is a child class of the abstract IndexPager, and contains |
| 20 | | - * some formatting and display code which is specific to the use of timestamps as |
| 21 | | - * indexes. Here is a synopsis of its operation: |
| | 20 | + * ReverseChronologicalPager is a child class of the abstract IndexPager, and |
| | 21 | + * contains some formatting and display code which is specific to the use of |
| | 22 | + * timestamps as indexes. Here is a synopsis of its operation: |
| 22 | 23 | * |
| 23 | | - * * The query is specified by the offset, limit and direction (dir) parameters, in |
| 24 | | - * addition to any subclass-specific parameters. |
| | 24 | + * * The query is specified by the offset, limit and direction (dir) |
| | 25 | + * parameters, in addition to any subclass-specific parameters. |
| | 26 | + * * The offset is the non-inclusive start of the DB query. A row with an |
| | 27 | + * index value equal to the offset will never be shown. |
| | 28 | + * * The query may either be done backwards, where the rows are returned by |
| | 29 | + * the database in the opposite order to which they are displayed to the |
| | 30 | + * user, or forwards. This is specified by the "dir" parameter, dir=prev |
| | 31 | + * means backwards, anything else means forwards. The offset value |
| | 32 | + * specifies the start of the database result set, which may be either |
| | 33 | + * the start or end of the displayed data set. This allows "previous" |
| | 34 | + * links to be implemented without knowledge of the index value at the |
| | 35 | + * start of the previous page. |
| | 36 | + * * An additional row beyond the user-specified limit is always requested. |
| | 37 | + * This allows us to tell whether we should display a "next" link in the |
| | 38 | + * case of forwards mode, or a "previous" link in the case of backwards |
| | 39 | + * mode. Determining whether to display the other link (the one for the |
| | 40 | + * page before the start of the database result set) can be done |
| | 41 | + * heuristically by examining the offset. |
| 25 | 42 | * |
| 26 | | - * * The offset is the non-inclusive start of the DB query. A row with an index value |
| 27 | | - * equal to the offset will never be shown. |
| | 43 | + * * An empty offset indicates that the offset condition should be omitted |
| | 44 | + * from the query. This naturally produces either the first page or the |
| | 45 | + * last page depending on the dir parameter. |
| 28 | 46 | * |
| 29 | | - * * The query may either be done backwards, where the rows are returned by the database |
| 30 | | - * in the opposite order to which they are displayed to the user, or forwards. This is |
| 31 | | - * specified by the "dir" parameter, dir=prev means backwards, anything else means |
| 32 | | - * forwards. The offset value specifies the start of the database result set, which |
| 33 | | - * may be either the start or end of the displayed data set. This allows "previous" |
| 34 | | - * links to be implemented without knowledge of the index value at the start of the |
| 35 | | - * previous page. |
| | 47 | + * Subclassing the pager to implement concrete functionality should be fairly |
| | 48 | + * simple, please see the examples in PageHistory.php and |
| | 49 | + * SpecialIpblocklist.php. You just need to override formatRow(), |
| | 50 | + * getQueryInfo() and getIndexField(). Don't forget to call the parent |
| | 51 | + * constructor if you override it. |
| 36 | 52 | * |
| 37 | | - * * An additional row beyond the user-specified limit is always requested. This allows |
| 38 | | - * us to tell whether we should display a "next" link in the case of forwards mode, |
| 39 | | - * or a "previous" link in the case of backwards mode. Determining whether to |
| 40 | | - * display the other link (the one for the page before the start of the database |
| 41 | | - * result set) can be done heuristically by examining the offset. |
| 42 | | - * |
| 43 | | - * * An empty offset indicates that the offset condition should be omitted from the query. |
| 44 | | - * This naturally produces either the first page or the last page depending on the |
| 45 | | - * dir parameter. |
| 46 | | - * |
| 47 | | - * Subclassing the pager to implement concrete functionality should be fairly simple, |
| 48 | | - * please see the examples in PageHistory.php and SpecialIpblocklist.php. You just need |
| 49 | | - * to override formatRow(), getQueryInfo() and getIndexField(). Don't forget to call the |
| 50 | | - * parent constructor if you override it. |
| 51 | | - * |
| 52 | 53 | * @addtogroup Pager |
| 53 | 54 | */ |
| 54 | 55 | abstract class IndexPager implements Pager { |
| — | — | @@ -75,9 +76,9 @@ |
| 76 | 77 | global $wgRequest, $wgUser; |
| 77 | 78 | $this->mRequest = $wgRequest; |
| 78 | 79 | |
| 79 | | - # NB: the offset is quoted, not validated. It is treated as an arbitrary string |
| 80 | | - # to support the widest variety of index types. Be careful outputting it into |
| 81 | | - # HTML! |
| | 80 | + # NB: the offset is quoted, not validated. It is treated as an |
| | 81 | + # arbitrary string to support the widest variety of index types. Be |
| | 82 | + # careful outputting it into HTML! |
| 82 | 83 | $this->mOffset = $this->mRequest->getText( 'offset' ); |
| 83 | 84 | |
| 84 | 85 | # Use consistent behavior for the limit options |
| — | — | @@ -131,9 +132,10 @@ |
| 132 | 133 | $lastIndex = $row[$this->mIndexField]; |
| 133 | 134 | } else { |
| 134 | 135 | $this->mPastTheEndRow = null; |
| 135 | | - # Setting indexes to an empty string means that they will be omitted |
| 136 | | - # if they would otherwise appear in URLs. It just so happens that this |
| 137 | | - # is the right thing to do in the standard UI, in all the relevant cases. |
| | 136 | + # Setting indexes to an empty string means that they will be |
| | 137 | + # omitted if they would otherwise appear in URLs. It just so |
| | 138 | + # happens that this is the right thing to do in the standard |
| | 139 | + # UI, in all the relevant cases. |
| 138 | 140 | $this->mPastTheEndIndex = ''; |
| 139 | 141 | $res->seek( $numRows - 1 ); |
| 140 | 142 | $row = $res->fetchRow(); |
| — | — | @@ -160,7 +162,8 @@ |
| 161 | 163 | } |
| 162 | 164 | |
| 163 | 165 | /** |
| 164 | | - * Do a query with specified parameters, rather than using the object context |
| | 166 | + * Do a query with specified parameters, rather than using the object |
| | 167 | + * context |
| 165 | 168 | * |
| 166 | 169 | * @param string $offset Index offset, inclusive |
| 167 | 170 | * @param integer $limit Exact query limit |
| — | — | @@ -331,9 +334,10 @@ |
| 332 | 335 | } |
| 333 | 336 | |
| 334 | 337 | /** |
| 335 | | - * Get paging links. If a link is disabled, the item from $disabledTexts will |
| 336 | | - * be used. If there is no such item, the unlinked text from $linkTexts will |
| 337 | | - * be used. Both $linkTexts and $disabledTexts are arrays of HTML. |
| | 338 | + * Get paging links. If a link is disabled, the item from $disabledTexts |
| | 339 | + * will be used. If there is no such item, the unlinked text from |
| | 340 | + * $linkTexts will be used. Both $linkTexts and $disabledTexts are arrays |
| | 341 | + * of HTML. |
| 338 | 342 | */ |
| 339 | 343 | function getPagingLinks( $linkTexts, $disabledTexts = array() ) { |
| 340 | 344 | $queries = $this->getPagingQueries(); |
| — | — | @@ -667,20 +671,22 @@ |
| 668 | 672 | } |
| 669 | 673 | |
| 670 | 674 | /** |
| 671 | | - * Return true if the named field should be sortable by the UI, false otherwise |
| | 675 | + * Return true if the named field should be sortable by the UI, false |
| | 676 | + * otherwise |
| | 677 | + * |
| 672 | 678 | * @param string $field |
| 673 | 679 | */ |
| 674 | 680 | abstract function isFieldSortable( $field ); |
| 675 | 681 | |
| 676 | 682 | /** |
| 677 | | - * Format a table cell. The return value should be HTML, but use an empty string |
| 678 | | - * not for empty cells. Do not include the <td> and </td>. |
| | 683 | + * Format a table cell. The return value should be HTML, but use an empty |
| | 684 | + * string not for empty cells. Do not include the <td> and </td>. |
| 679 | 685 | * |
| | 686 | + * The current result row is available as $this->mCurrentRow, in case you |
| | 687 | + * need more context. |
| | 688 | + * |
| 680 | 689 | * @param string $name The database field name |
| 681 | 690 | * @param string $value The value retrieved from the database |
| 682 | | - * |
| 683 | | - * The current result row is available as $this->mCurrentRow, in case you need |
| 684 | | - * more context. |
| 685 | 691 | */ |
| 686 | 692 | abstract function formatValue( $name, $value ); |
| 687 | 693 | |
| — | — | @@ -690,9 +696,9 @@ |
| 691 | 697 | abstract function getDefaultSort(); |
| 692 | 698 | |
| 693 | 699 | /** |
| 694 | | - * An array mapping database field names to a textual description of the field |
| 695 | | - * name, for use in the table header. The description should be plain text, it |
| 696 | | - * will be HTML-escaped later. |
| | 700 | + * An array mapping database field names to a textual description of the |
| | 701 | + * field name, for use in the table header. The description should be plain |
| | 702 | + * text, it will be HTML-escaped later. |
| 697 | 703 | */ |
| 698 | 704 | abstract function getFieldNames(); |
| 699 | 705 | } |