includes/Pager.php

   1 <?php
   2
   3 /**
   4  * Basic pager interface.
   5  * @addtogroup Pager
   6  */
   7 interface Pager {
   8         function getNavigationBar();
   9         function getBody();
  10 }
  11
  12 /**
  13  * IndexPager is an efficient pager which uses a (roughly unique) index in the
  14  * data set to implement paging, rather than a "LIMIT offset,limit" clause.
  15  * In MySQL, such a limit/offset clause requires counting through the
  16  * specified number of offset rows to find the desired data, which can be
  17  * expensive for large offsets.
  18  *
  19  * ReverseChronologicalPager is a child class of the abstract IndexPager, and
  20  * contains  some formatting and display code which is specific to the use of
  21  * timestamps as  indexes. Here is a synopsis of its operation:
  22  *
  23  *    * The query is specified by the offset, limit and direction (dir)
  24  *      parameters, in addition to any subclass-specific parameters.
  25  *    * The offset is the non-inclusive start of the DB query. A row with an
  26  *      index value equal to the offset will never be shown.
  27  *    * The query may either be done backwards, where the rows are returned by
  28  *      the database in the opposite order to which they are displayed to the
  29  *      user, or forwards. This is specified by the "dir" parameter, dir=prev
  30  *      means backwards, anything else means forwards. The offset value
  31  *      specifies the start of the database result set, which may be either
  32  *      the start or end of the displayed data set. This allows "previous"
  33  *      links to be implemented without knowledge of the index value at the
  34  *      start of the previous page.
  35  *    * An additional row beyond the user-specified limit is always requested.
  36  *      This allows us to tell whether we should display a "next" link in the
  37  *      case of forwards mode, or a "previous" link in the case of backwards
  38  *      mode. Determining whether to display the other link (the one for the
  39  *      page before the start of the database result set) can be done
  40  *      heuristically by examining the offset.
  41  *
  42  *    * An empty offset indicates that the offset condition should be omitted
  43  *      from the query. This naturally produces either the first page or the
  44  *      last page depending on the dir parameter.
  45  *
  46  *  Subclassing the pager to implement concrete functionality should be fairly
  47  *  simple, please see the examples in PageHistory.php and
  48  *  SpecialIpblocklist.php. You just need to override formatRow(),
  49  *  getQueryInfo() and getIndexField(). Don't forget to call the parent
  50  *  constructor if you override it.
  51  *
  52  * @addtogroup Pager
  53  */
  54 abstract class IndexPager implements Pager {
  55         public $mRequest;
  56         public $mLimitsShown = array( 20, 50, 100, 250, 500 );
  57         public $mDefaultLimit = 50;
  58         public $mOffset, $mLimit;
  59         public $mQueryDone = false;
  60         public $mDb;
  61         public $mPastTheEndRow;
  62
  63         /**
  64          * The index to actually be used for ordering.  This is a single string e-
  65          * ven if multiple orderings are supported.
  66          */
  67         protected $mIndexField;
  68         /** For pages that support multiple types of ordering, which one to use. */
  69         protected $mOrderType;
  70         /**
  71          * $mDefaultDirection gives the direction to use when sorting results:
  72          * false for ascending, true for descending.  If $mIsBackwards is set, we
  73          * start from the opposite end, but we still sort the page itself according
  74          * to $mDefaultDirection.  E.g., if $mDefaultDirection is false but we're
  75          * going backwards, we'll display the last page of results, but the last
  76          * result will be at the bottom, not the top.
  77          *
  78          * "Default" is really a misnomer here, since now it's possible for the
  79          * user to directly modify this with query parameters.  TODO: rename that
  80          * to $mDescending, maybe set this to that by reference for compatibility.
  81          */
  82         public $mDefaultDirection;
  83         public $mIsBackwards;
  84
  85         /**
  86          * Result object for the query. Warning: seek before use.
  87          */
  88         public $mResult;
  89
  90         public function __construct() {
  91                 global $wgRequest, $wgUser;
  92                 $this->mRequest = $wgRequest;
  93
  94                 # NB: the offset is quoted, not validated. It is treated as an
  95                 # arbitrary string to support the widest variety of index types. Be
  96                 # careful outputting it into HTML!
  97                 $this->mOffset = $this->mRequest->getText( 'offset' );
  98
  99                 # Use consistent behavior for the limit options
 100                 $this->mDefaultLimit = intval( $wgUser->getOption( 'rclimit' ) );
 101                 list( $this->mLimit, /* $offset */ ) = $this->mRequest->getLimitOffset();
 102
 103                 $this->mIsBackwards = ( $this->mRequest->getVal( 'dir' ) == 'prev' );
 104                 $this->mDb = wfGetDB( DB_SLAVE );
 105
 106                 $index = $this->getIndexField();
 107                 $order = $this->mRequest->getVal( 'order' );
 108                 if( is_array( $index ) && isset( $index[$order] ) ) {
 109                         $this->mOrderType = $order;
 110                         $this->mIndexField = $index[$order];
 111                 } elseif( is_array( $index ) ) {
 112                         # First element is the default
 113                         reset( $index );
 114                         list( $this->mOrderType, $this->mIndexField ) = each( $index );
 115                 } else {
 116                         # $index is not an array
 117                         $this->mOrderType = null;
 118                         $this->mIndexField = $index;
 119                 }
 120
 121                 if( !isset( $this->mDefaultDirection ) ) {
 122                         $dir = $this->getDefaultDirection();
 123                         $this->mDefaultDirection = is_array( $dir )
 124                                 ? $dir[$this->mOrderType]
 125                                 : $dir;
 126                 }
 127
 128                 # FIXME: Can we figure out a less confusing convention than using a
 129                 # "direction" parameter when we already have "dir" and "order"?
 130                 if( $this->mRequest->getVal( 'direction' ) == 'asc' ) {
 131                         $this->mDefaultDirection = false;
 132                 }
 133                 if( $this->mRequest->getVal( 'direction' ) == 'desc' ) {
 134                         $this->mDefaultDirection = true;
 135                 }
 136         }
 137
 138         /**
 139          * Do the query, using information from the object context. This function
 140          * has been kept minimal to make it overridable if necessary, to allow for
 141          * result sets formed from multiple DB queries.
 142          */
 143         function doQuery() {
 144                 # Use the child class name for profiling
 145                 $fname = __METHOD__ . ' (' . get_class( $this ) . ')';
 146                 wfProfileIn( $fname );
 147
 148                 $descending = ( $this->mIsBackwards == $this->mDefaultDirection );
 149                 # Plus an extra row so that we can tell the "next" link should be shown
 150                 $queryLimit = $this->mLimit + 1;
 151
 152                 $this->mResult = $this->reallyDoQuery( $this->mOffset, $queryLimit, $descending );
 153                 $this->extractResultInfo( $this->mOffset, $queryLimit, $this->mResult );
 154                 $this->mQueryDone = true;
 155
 156                 $this->preprocessResults( $this->mResult );
 157                 $this->mResult->rewind(); // Paranoia
 158
 159                 wfProfileOut( $fname );
 160         }
 161
 162         /**
 163          * Extract some useful data from the result object for use by
 164          * the navigation bar, put it into $this
 165          */
 166         function extractResultInfo( $offset, $limit, ResultWrapper $res ) {
 167                 $numRows = $res->numRows();
 168                 if ( $numRows ) {
 169                         $row = $res->fetchRow();
 170                         $firstIndex = $row[$this->mIndexField];
 171
 172                         # Discard the extra result row if there is one
 173                         if ( $numRows > $this->mLimit && $numRows > 1 ) {
 174                                 $res->seek( $numRows - 1 );
 175                                 $this->mPastTheEndRow = $res->fetchObject();
 176                                 $indexField = $this->mIndexField;
 177                                 $this->mPastTheEndIndex = $this->mPastTheEndRow->$indexField;
 178                                 $res->seek( $numRows - 2 );
 179                                 $row = $res->fetchRow();
 180                                 $lastIndex = $row[$this->mIndexField];
 181                         } else {
 182                                 $this->mPastTheEndRow = null;
 183                                 # Setting indexes to an empty string means that they will be
 184                                 # omitted if they would otherwise appear in URLs. It just so
 185                                 # happens that this  is the right thing to do in the standard
 186                                 # UI, in all the relevant cases.
 187                                 $this->mPastTheEndIndex = '';
 188                                 $res->seek( $numRows - 1 );
 189                                 $row = $res->fetchRow();
 190                                 $lastIndex = $row[$this->mIndexField];
 191                         }
 192                 } else {
 193                         $firstIndex = '';
 194                         $lastIndex = '';
 195                         $this->mPastTheEndRow = null;
 196                         $this->mPastTheEndIndex = '';
 197                 }
 198
 199                 if ( $this->mIsBackwards ) {
 200                         $this->mIsFirst = ( $numRows < $limit );
 201                         $this->mIsLast = ( $offset == '' );
 202                         $this->mLastShown = $firstIndex;
 203                         $this->mFirstShown = $lastIndex;
 204                 } else {
 205                         $this->mIsFirst = ( $offset == '' );
 206                         $this->mIsLast = ( $numRows < $limit );
 207                         $this->mLastShown = $lastIndex;
 208                         $this->mFirstShown = $firstIndex;
 209                 }
 210         }
 211
 212         /**
 213          * Do a query with specified parameters, rather than using the object
 214          * context
 215          *
 216          * @param string $offset Index offset, inclusive
 217          * @param integer $limit Exact query limit
 218          * @param boolean $descending Query direction, false for ascending, true for descending
 219          * @return ResultWrapper
 220          */
 221         function reallyDoQuery( $offset, $limit, $descending ) {
 222                 $fname = __METHOD__ . ' (' . get_class( $this ) . ')';
 223                 $info = $this->getQueryInfo();
 224                 $tables = $info['tables'];
 225                 $fields = $info['fields'];
 226                 $conds = isset( $info['conds'] ) ? $info['conds'] : array();
 227                 $options = isset( $info['options'] ) ? $info['options'] : array();
 228                 if ( $descending ) {
 229                         $options['ORDER BY'] = $this->mIndexField;
 230                         $operator = '>';
 231                 } else {
 232                         $options['ORDER BY'] = $this->mIndexField . ' DESC';
 233                         $operator = '<';
 234                 }
 235                 if ( $offset != '' ) {
 236                         $conds[] = $this->mIndexField . $operator . $this->mDb->addQuotes( $offset );
 237                 }
 238                 $options['LIMIT'] = intval( $limit );
 239                 $res = $this->mDb->select( $tables, $fields, $conds, $fname, $options );
 240                 return new ResultWrapper( $this->mDb, $res );
 241         }
 242
 243         /**
 244          * Pre-process results; useful for performing batch existence checks, etc.
 245          *
 246          * @param ResultWrapper $result Result wrapper
 247          */
 248         protected function preprocessResults( $result ) {}
 249
 250         /**
 251          * Get the formatted result list. Calls getStartBody(), formatRow() and
 252          * getEndBody(), concatenates the results and returns them.
 253          */
 254         function getBody() {
 255                 if ( !$this->mQueryDone ) {
 256                         $this->doQuery();
 257                 }
 258                 # Don't use any extra rows returned by the query
 259                 $numRows = min( $this->mResult->numRows(), $this->mLimit );
 260
 261                 $s = $this->getStartBody();
 262                 if ( $numRows ) {
 263                         if ( $this->mIsBackwards ) {
 264                                 for ( $i = $numRows - 1; $i >= 0; $i-- ) {
 265                                         $this->mResult->seek( $i );
 266                                         $row = $this->mResult->fetchObject();
 267                                         $s .= $this->formatRow( $row );
 268                                 }
 269                         } else {
 270                                 $this->mResult->seek( 0 );
 271                                 for ( $i = 0; $i < $numRows; $i++ ) {
 272                                         $row = $this->mResult->fetchObject();
 273                                         $s .= $this->formatRow( $row );
 274                                 }
 275                         }
 276                 } else {
 277                         $s .= $this->getEmptyBody();
 278                 }
 279                 $s .= $this->getEndBody();
 280                 return $s;
 281         }
 282
 283         /**
 284          * Make a self-link
 285          */
 286         function makeLink($text, $query = null) {
 287                 if ( $query === null ) {
 288                         return $text;
 289                 }
 290                 return $this->getSkin()->makeKnownLinkObj( $this->getTitle(), $text,
 291                                 wfArrayToCGI( $query, $this->getDefaultQuery() ) );
 292         }
 293
 294         /**
 295          * Hook into getBody(), allows text to be inserted at the start. This
 296          * will be called even if there are no rows in the result set.
 297          */
 298         function getStartBody() {
 299                 return '';
 300         }
 301
 302         /**
 303          * Hook into getBody() for the end of the list
 304          */
 305         function getEndBody() {
 306                 return '';
 307         }
 308
 309         /**
 310          * Hook into getBody(), for the bit between the start and the
 311          * end when there are no rows
 312          */
 313         function getEmptyBody() {
 314                 return '';
 315         }
 316
 317         /**
 318          * Title used for self-links. Override this if you want to be able to
 319          * use a title other than $wgTitle
 320          */
 321         function getTitle() {
 322                 return $GLOBALS['wgTitle'];
 323         }
 324
 325         /**
 326          * Get the current skin. This can be overridden if necessary.
 327          */
 328         function getSkin() {
 329                 if ( !isset( $this->mSkin ) ) {
 330                         global $wgUser;
 331                         $this->mSkin = $wgUser->getSkin();
 332                 }
 333                 return $this->mSkin;
 334         }
 335
 336         /**
 337          * Get an array of query parameters that should be put into self-links.
 338          * By default, all parameters passed in the URL are used, except for a
 339          * short blacklist.
 340          */
 341         function getDefaultQuery() {
 342                 if ( !isset( $this->mDefaultQuery ) ) {
 343                         $this->mDefaultQuery = $_GET;
 344                         unset( $this->mDefaultQuery['title'] );
 345                         unset( $this->mDefaultQuery['dir'] );
 346                         unset( $this->mDefaultQuery['offset'] );
 347                         unset( $this->mDefaultQuery['limit'] );
 348                         unset( $this->mDefaultQuery['direction'] );
 349                         unset( $this->mDefaultQuery['order'] );
 350                 }
 351                 return $this->mDefaultQuery;
 352         }
 353
 354         /**
 355          * Get the number of rows in the result set
 356          */
 357         function getNumRows() {
 358                 if ( !$this->mQueryDone ) {
 359                         $this->doQuery();
 360                 }
 361                 return $this->mResult->numRows();
 362         }
 363
 364         /**
 365          * Get a query array for the prev, next, first and last links.
 366          */
 367         function getPagingQueries() {
 368                 if ( !$this->mQueryDone ) {
 369                         $this->doQuery();
 370                 }
 371
 372                 # Don't announce the limit everywhere if it's the default
 373                 $urlLimit = $this->mLimit == $this->mDefaultLimit ? '' : $this->mLimit;
 374
 375                 if ( $this->mIsFirst ) {
 376                         $prev = false;
 377                         $first = false;
 378                 } else {
 379                         $prev = array( 'dir' => 'prev', 'offset' => $this->mFirstShown, 'limit' => $urlLimit );
 380                         $first = array( 'limit' => $urlLimit );
 381                 }
 382                 if ( $this->mIsLast ) {
 383                         $next = false;
 384                         $last = false;
 385                 } else {
 386                         $next = array( 'offset' => $this->mLastShown, 'limit' => $urlLimit );
 387                         $last = array( 'dir' => 'prev', 'limit' => $urlLimit );
 388                 }
 389                 return array( 'prev' => $prev, 'next' => $next, 'first' => $first, 'last' => $last );
 390         }
 391
 392         /**
 393          * Get paging links. If a link is disabled, the item from $disabledTexts
 394          * will be used. If there is no such item, the unlinked text from
 395          * $linkTexts will be used. Both $linkTexts and $disabledTexts are arrays
 396          * of HTML.
 397          */
 398         function getPagingLinks( $linkTexts, $disabledTexts = array() ) {
 399                 $queries = $this->getPagingQueries();
 400                 $links = array();
 401                 foreach ( $queries as $type => $query ) {
 402                         if ( $query !== false ) {
 403                                 $links[$type] = $this->makeLink( $linkTexts[$type], $queries[$type] );
 404                         } elseif ( isset( $disabledTexts[$type] ) ) {
 405                                 $links[$type] = $disabledTexts[$type];
 406                         } else {
 407                                 $links[$type] = $linkTexts[$type];
 408                         }
 409                 }
 410                 return $links;
 411         }
 412
 413         function getLimitLinks() {
 414                 global $wgLang;
 415                 $links = array();
 416                 if ( $this->mIsBackwards ) {
 417                         $offset = $this->mPastTheEndIndex;
 418                 } else {
 419                         $offset = $this->mOffset;
 420                 }
 421                 foreach ( $this->mLimitsShown as $limit ) {
 422                         $links[] = $this->makeLink( $wgLang->formatNum( $limit ),
 423                                 array( 'offset' => $offset, 'limit' => $limit ) );
 424                 }
 425                 return $links;
 426         }
 427
 428         /**
 429          * Abstract formatting function. This should return an HTML string
 430          * representing the result row $row. Rows will be concatenated and
 431          * returned by getBody()
 432          */
 433         abstract function formatRow( $row );
 434
 435         /**
 436          * This function should be overridden to provide all parameters
 437          * needed for the main paged query. It returns an associative
 438          * array with the following elements:
 439          *    tables => Table(s) for passing to Database::select()
 440          *    fields => Field(s) for passing to Database::select(), may be *
 441          *    conds => WHERE conditions
 442          *    options => option array
 443          */
 444         abstract function getQueryInfo();
 445
 446         /**
 447          * This function should be overridden to return the name of the index fi-
 448          * eld.  If the pager supports multiple orders, it may return an array of
 449          * 'querykey' => 'indexfield' pairs, so that a request with &count=querykey
 450          * will use indexfield to sort.  In this case, the first returned key is
 451          * the default.
 452          */
 453         abstract function getIndexField();
 454
 455         /**
 456          * Return the default sorting direction: false for ascending, true for de-
 457          * scending.  You can also have an associative array of ordertype => dir,
 458          * if multiple order types are supported.  In this case getIndexField()
 459          * must return an array, and the keys of that must exactly match the keys
 460          * of this.
 461          *
 462          * For backward compatibility, this method's return value will be ignored
 463          * if $this->mDefaultDirection is already set when the constructor is
 464          * called, for instance if it's statically initialized.  In that case the
 465          * value of that variable (which must be a boolean) will be used.
 466          *
 467          * Note that despite its name, this does not return the value of the now-
 468          * misnamed $this->mDefaultDirection member variable.  That is not a
 469          * default, it's the actual direction used.  This is just the default and
 470          * can be overridden by user input.
 471          */
 472         protected function getDefaultDirection() { return false; }
 473 }
 474
 475
 476 /**
 477  * IndexPager with an alphabetic list and a formatted navigation bar
 478  * @addtogroup Pager
 479  */
 480 abstract class AlphabeticPager extends IndexPager {
 481         function __construct() {
 482                 parent::__construct();
 483         }
 484
 485         /**
 486          * Shamelessly stolen bits from ReverseChronologicalPager, d
 487          * didn't want to do class magic as may be still revamped
 488          */
 489         function getNavigationBar() {
 490                 global $wgLang;
 491
 492                 if( isset( $this->mNavigationBar ) ) {
 493                         return $this->mNavigationBar;
 494                 }
 495
 496                 $linkTexts = array(
 497                         'prev' => wfMsgHtml( 'prevn', $wgLang->formatNum( $this->mLimit ) ),
 498                         'next' => wfMsgHtml( 'nextn', $wgLang->formatNum($this->mLimit ) ),
 499                         'first' => wfMsgHtml( 'page_first' ),
 500                         'last' => wfMsgHtml( 'page_last' )
 501                 );
 502
 503                 $pagingLinks = $this->getPagingLinks( $linkTexts );
 504                 $limitLinks = $this->getLimitLinks();
 505                 $limits = implode( ' | ', $limitLinks );
 506
 507                 $this->mNavigationBar =
 508                         "({$pagingLinks['first']} | {$pagingLinks['last']}) " .
 509                         wfMsgHtml( 'viewprevnext', $pagingLinks['prev'],
 510                         $pagingLinks['next'], $limits );
 511
 512                 # Which direction should the link go?  Opposite of the current.
 513                 $dir = $this->mDefaultDirection ? 'asc' : 'desc';
 514                 $query = array( 'direction' => $dir );
 515                 if( $this->mOrderType !== null ) {
 516                         $query['order'] = $this->mOrderType;
 517                 }
 518                 # Note for grep: uses pager-sort-asc, pager-sort-desc
 519                 $this->mNavigationBar .= ' (' . $this->makeLink(
 520                         wfMsgHTML( "pager-sort-$dir" ),
 521                         $query
 522                 ) . ')';
 523
 524                 if( !is_array( $this->getIndexField() ) ) {
 525                         # Early return to avoid undue nesting
 526                         return $this->mNavigationBar;
 527                 }
 528
 529                 $extra = '';
 530                 $first = true;
 531                 $msgs = $this->getOrderTypeMessages();
 532                 foreach( array_keys( $msgs ) as $order ) {
 533                         if( $order == $this->mOrderType ) {
 534                                 continue;
 535                         }
 536                         if( !$first ) {
 537                                 $extra .= ' | ';
 538                                 $first = false;
 539                         }
 540                         $extra .= $this->makeLink(
 541                                 wfMsgHTML( $msgs[$order] ),
 542                                 array( 'order' => $order )
 543                         );
 544                 }
 545
 546                 if( $extra !== '' ) {
 547                         $this->mNavigationBar .= " ($extra)";
 548                 }
 549
 550                 return $this->mNavigationBar;
 551         }
 552
 553         /**
 554          * If this supports multiple order type messages, give the message key for
 555          * enabling each one in getNavigationBar.  The return type is an associa-
 556          * tive array whose keys must exactly match the keys of the array returned
 557          * by getIndexField(), and whose values are message keys.
 558          * @return array
 559          */
 560         protected function getOrderTypeMessages() {
 561                 return null;
 562         }
 563 }
 564
 565 /**
 566  * IndexPager with a formatted navigation bar
 567  * @addtogroup Pager
 568  */
 569 abstract class ReverseChronologicalPager extends IndexPager {
 570         public $mDefaultDirection = true;
 571
 572         function __construct() {
 573                 parent::__construct();
 574         }
 575
 576         function getNavigationBar() {
 577                 global $wgLang;
 578
 579                 if ( isset( $this->mNavigationBar ) ) {
 580                         return $this->mNavigationBar;
 581                 }
 582                 $nicenumber = $wgLang->formatNum( $this->mLimit );
 583                 $linkTexts = array(
 584                         'prev' => wfMsgExt( 'pager-newer-n', array( 'parsemag' ), $nicenumber ),
 585                         'next' => wfMsgExt( 'pager-older-n', array( 'parsemag' ), $nicenumber ),
 586                         'first' => wfMsgHtml( 'histlast' ),
 587                         'last' => wfMsgHtml( 'histfirst' )
 588                 );
 589
 590                 $pagingLinks = $this->getPagingLinks( $linkTexts );
 591                 $limitLinks = $this->getLimitLinks();
 592                 $limits = implode( ' | ', $limitLinks );
 593
 594                 $this->mNavigationBar = "({$pagingLinks['first']} | {$pagingLinks['last']}) " .
 595                         wfMsgHtml("viewprevnext", $pagingLinks['prev'], $pagingLinks['next'], $limits);
 596                 return $this->mNavigationBar;
 597         }
 598 }
 599
 600 /**
 601  * Table-based display with a user-selectable sort order
 602  * @addtogroup Pager
 603  */
 604 abstract class TablePager extends IndexPager {
 605         var $mSort;
 606         var $mCurrentRow;
 607
 608         function __construct() {
 609                 global $wgRequest;
 610                 $this->mSort = $wgRequest->getText( 'sort' );
 611                 if ( !array_key_exists( $this->mSort, $this->getFieldNames() ) ) {
 612                         $this->mSort = $this->getDefaultSort();
 613                 }
 614                 if ( $wgRequest->getBool( 'asc' ) ) {
 615                         $this->mDefaultDirection = false;
 616                 } elseif ( $wgRequest->getBool( 'desc' ) ) {
 617                         $this->mDefaultDirection = true;
 618                 } /* Else leave it at whatever the class default is */
 619
 620                 parent::__construct();
 621         }
 622
 623         function getStartBody() {
 624                 global $wgStylePath;
 625                 $tableClass = htmlspecialchars( $this->getTableClass() );
 626                 $sortClass = htmlspecialchars( $this->getSortHeaderClass() );
 627
 628                 $s = "<table border='1' class=\"$tableClass\"><thead><tr>\n";
 629                 $fields = $this->getFieldNames();
 630
 631                 # Make table header
 632                 foreach ( $fields as $field => $name ) {
 633                         if ( strval( $name ) == '' ) {
 634                                 $s .= "<th>&nbsp;</th>\n";
 635                         } elseif ( $this->isFieldSortable( $field ) ) {
 636                                 $query = array( 'sort' => $field, 'limit' => $this->mLimit );
 637                                 if ( $field == $this->mSort ) {
 638                                         # This is the sorted column
 639                                         # Prepare a link that goes in the other sort order
 640                                         if ( $this->mDefaultDirection ) {
 641                                                 # Descending
 642                                                 $image = 'Arr_u.png';
 643                                                 $query['asc'] = '1';
 644                                                 $query['desc'] = '';
 645                                                 $alt = htmlspecialchars( wfMsg( 'descending_abbrev' ) );
 646                                         } else {
 647                                                 # Ascending
 648                                                 $image = 'Arr_d.png';
 649                                                 $query['asc'] = '';
 650                                                 $query['desc'] = '1';
 651                                                 $alt = htmlspecialchars( wfMsg( 'ascending_abbrev' ) );
 652                                         }
 653                                         $image = htmlspecialchars( "$wgStylePath/common/images/$image" );
 654                                         $link = $this->makeLink(
 655                                                 "<img width=\"12\" height=\"12\" alt=\"$alt\" src=\"$image\" />" .
 656                                                 htmlspecialchars( $name ), $query );
 657                                         $s .= "<th class=\"$sortClass\">$link</th>\n";
 658                                 } else {
 659                                         $s .= '<th>' . $this->makeLink( htmlspecialchars( $name ), $query ) . "</th>\n";
 660                                 }
 661                         } else {
 662                                 $s .= '<th>' . htmlspecialchars( $name ) . "</th>\n";
 663                         }
 664                 }
 665                 $s .= "</tr></thead><tbody>\n";
 666                 return $s;
 667         }
 668
 669         function getEndBody() {
 670                 return "</tbody></table>\n";
 671         }
 672
 673         function getEmptyBody() {
 674                 $colspan = count( $this->getFieldNames() );
 675                 $msgEmpty = wfMsgHtml( 'table_pager_empty' );
 676                 return "<tr><td colspan=\"$colspan\">$msgEmpty</td></tr>\n";
 677         }
 678
 679         function formatRow( $row ) {
 680                 $s = "<tr>\n";
 681                 $fieldNames = $this->getFieldNames();
 682                 $this->mCurrentRow = $row;  # In case formatValue needs to know
 683                 foreach ( $fieldNames as $field => $name ) {
 684                         $value = isset( $row->$field ) ? $row->$field : null;
 685                         $formatted = strval( $this->formatValue( $field, $value ) );
 686                         if ( $formatted == '' ) {
 687                                 $formatted = '&nbsp;';
 688                         }
 689                         $class = 'TablePager_col_' . htmlspecialchars( $field );
 690                         $s .= "<td class=\"$class\">$formatted</td>\n";
 691                 }
 692                 $s .= "</tr>\n";
 693                 return $s;
 694         }
 695
 696         function getIndexField() {
 697                 return $this->mSort;
 698         }
 699
 700         function getTableClass() {
 701                 return 'TablePager';
 702         }
 703
 704         function getNavClass() {
 705                 return 'TablePager_nav';
 706         }
 707
 708         function getSortHeaderClass() {
 709                 return 'TablePager_sort';
 710         }
 711
 712         /**
 713          * A navigation bar with images
 714          */
 715         function getNavigationBar() {
 716                 global $wgStylePath, $wgContLang;
 717                 $path = "$wgStylePath/common/images";
 718                 $labels = array(
 719                         'first' => 'table_pager_first',
 720                         'prev' => 'table_pager_prev',
 721                         'next' => 'table_pager_next',
 722                         'last' => 'table_pager_last',
 723                 );
 724                 $images = array(
 725                         'first' => $wgContLang->isRTL() ? 'arrow_last_25.png' : 'arrow_first_25.png',
 726                         'prev' =>  $wgContLang->isRTL() ? 'arrow_right_25.png' : 'arrow_left_25.png',
 727                         'next' =>  $wgContLang->isRTL() ? 'arrow_left_25.png' : 'arrow_right_25.png',
 728                         'last' =>  $wgContLang->isRTL() ? 'arrow_first_25.png' : 'arrow_last_25.png',
 729                 );
 730                 $disabledImages = array(
 731                         'first' => $wgContLang->isRTL() ? 'arrow_disabled_last_25.png' : 'arrow_disabled_first_25.png',
 732                         'prev' =>  $wgContLang->isRTL() ? 'arrow_disabled_right_25.png' : 'arrow_disabled_left_25.png',
 733                         'next' =>  $wgContLang->isRTL() ? 'arrow_disabled_left_25.png' : 'arrow_disabled_right_25.png',
 734                         'last' =>  $wgContLang->isRTL() ? 'arrow_disabled_first_25.png' : 'arrow_disabled_last_25.png',
 735                 );
 736
 737                 $linkTexts = array();
 738                 $disabledTexts = array();
 739                 foreach ( $labels as $type => $label ) {
 740                         $msgLabel = wfMsgHtml( $label );
 741                         $linkTexts[$type] = "<img src=\"$path/{$images[$type]}\" alt=\"$msgLabel\"/><br/>$msgLabel";
 742                         $disabledTexts[$type] = "<img src=\"$path/{$disabledImages[$type]}\" alt=\"$msgLabel\"/><br/>$msgLabel";
 743                 }
 744                 $links = $this->getPagingLinks( $linkTexts, $disabledTexts );
 745
 746                 $navClass = htmlspecialchars( $this->getNavClass() );
 747                 $s = "<table class=\"$navClass\" align=\"center\" cellpadding=\"3\"><tr>\n";
 748                 $cellAttrs = 'valign="top" align="center" width="' . 100 / count( $links ) . '%"';
 749                 foreach ( $labels as $type => $label ) {
 750                         $s .= "<td $cellAttrs>{$links[$type]}</td>\n";
 751                 }
 752                 $s .= "</tr></table>\n";
 753                 return $s;
 754         }
 755
 756         /**
 757          * Get a <select> element which has options for each of the allowed limits
 758          */
 759         function getLimitSelect() {
 760                 global $wgLang;
 761                 $s = "<select name=\"limit\">";
 762                 foreach ( $this->mLimitsShown as $limit ) {
 763                         $selected = $limit == $this->mLimit ? 'selected="selected"' : '';
 764                         $formattedLimit = $wgLang->formatNum( $limit );
 765                         $s .= "<option value=\"$limit\" $selected>$formattedLimit</option>\n";
 766                 }
 767                 $s .= "</select>";
 768                 return $s;
 769         }
 770
 771         /**
 772          * Get <input type="hidden"> elements for use in a method="get" form.
 773          * Resubmits all defined elements of the $_GET array, except for a
 774          * blacklist, passed in the $blacklist parameter.
 775          */
 776         function getHiddenFields( $blacklist = array() ) {
 777                 $blacklist = (array)$blacklist;
 778                 $query = $_GET;
 779                 foreach ( $blacklist as $name ) {
 780                         unset( $query[$name] );
 781                 }
 782                 $s = '';
 783                 foreach ( $query as $name => $value ) {
 784                         $encName = htmlspecialchars( $name );
 785                         $encValue = htmlspecialchars( $value );
 786                         $s .= "<input type=\"hidden\" name=\"$encName\" value=\"$encValue\"/>\n";
 787                 }
 788                 return $s;
 789         }
 790
 791         /**
 792          * Get a form containing a limit selection dropdown
 793          */
 794         function getLimitForm() {
 795                 # Make the select with some explanatory text
 796                 $url = $this->getTitle()->escapeLocalURL();
 797                 $msgSubmit = wfMsgHtml( 'table_pager_limit_submit' );
 798                 return
 799                         "<form method=\"get\" action=\"$url\">" .
 800                         wfMsgHtml( 'table_pager_limit', $this->getLimitSelect() ) .
 801                         "\n<input type=\"submit\" value=\"$msgSubmit\"/>\n" .
 802                         $this->getHiddenFields( 'limit' ) .
 803                         "</form>\n";
 804         }
 805
 806         /**
 807          * Return true if the named field should be sortable by the UI, false
 808          * otherwise
 809          *
 810          * @param string $field
 811          */
 812         abstract function isFieldSortable( $field );
 813
 814         /**
 815          * Format a table cell. The return value should be HTML, but use an empty
 816          * string not &nbsp; for empty cells. Do not include the <td> and </td>.
 817          *
 818          * The current result row is available as $this->mCurrentRow, in case you
 819          * need more context.
 820          *
 821          * @param string $name The database field name
 822          * @param string $value The value retrieved from the database
 823          */
 824         abstract function formatValue( $name, $value );
 825
 826         /**
 827          * The database field name used as a default sort order
 828          */
 829         abstract function getDefaultSort();
 830
 831         /**
 832          * An array mapping database field names to a textual description of the
 833          * field name, for use in the table header. The description should be plain
 834          * text, it will be HTML-escaped later.
 835          */
 836         abstract function getFieldNames();
 837 }