includes/specialpage/ChangesListSpecialPage.php

   1 <?php
   2 /**
   3  * Special page which uses a ChangesList to show query results.
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  * @ingroup SpecialPage
  22  */
  23
  24 /**
  25  * Special page which uses a ChangesList to show query results.
  26  * @todo Way too many public functions, most of them should be protected
  27  *
  28  * @ingroup SpecialPage
  29  */
  30 abstract class ChangesListSpecialPage extends SpecialPage {
  31         var $rcSubpage, $rcOptions; // @todo Rename these, make protected
  32         protected $customFilters;
  33
  34         /**
  35          * The feed format to output as (either 'rss' or 'atom'), or null if no
  36          * feed output was requested
  37          *
  38          * @var string $feedFormat
  39          */
  40         protected $feedFormat;
  41
  42         /**
  43          * Main execution point
  44          *
  45          * @param string $subpage
  46          */
  47         public function execute( $subpage ) {
  48                 $this->rcSubpage = $subpage;
  49                 $this->feedFormat = $this->including() ? null : $this->getRequest()->getVal( 'feed' );
  50                 if ( $this->feedFormat !== 'atom' && $this->feedFormat !== 'rss' ) {
  51                         $this->feedFormat = null;
  52                 }
  53
  54                 $this->setHeaders();
  55                 $this->outputHeader();
  56                 $this->addModules();
  57
  58                 $opts = $this->getOptions();
  59                 // Fetch results, prepare a batch link existence check query
  60                 $conds = $this->buildMainQueryConds( $opts );
  61                 $rows = $this->doMainQuery( $conds, $opts );
  62                 if ( $rows === false ) {
  63                         if ( !$this->including() ) {
  64                                 $this->doHeader( $opts );
  65                         }
  66
  67                         return;
  68                 }
  69
  70                 if ( !$this->feedFormat ) {
  71                         $batch = new LinkBatch;
  72                         foreach ( $rows as $row ) {
  73                                 $batch->add( NS_USER, $row->rc_user_text );
  74                                 $batch->add( NS_USER_TALK, $row->rc_user_text );
  75                                 $batch->add( $row->rc_namespace, $row->rc_title );
  76                         }
  77                         $batch->execute();
  78                 }
  79                 if ( $this->feedFormat ) {
  80                         list( $changesFeed, $formatter ) = $this->getFeedObject( $this->feedFormat );
  81                         /** @var ChangesFeed $changesFeed */
  82                         $changesFeed->execute( $formatter, $rows, $this->checkLastModified( $this->feedFormat ), $opts );
  83                 } else {
  84                         $this->webOutput( $rows, $opts );
  85                 }
  86
  87                 $rows->free();
  88         }
  89
  90         /**
  91          * Get the current FormOptions for this request
  92          *
  93          * @return FormOptions
  94          */
  95         public function getOptions() {
  96                 if ( $this->rcOptions === null ) {
  97                         $this->rcOptions = $this->setup( $this->rcSubpage );
  98                 }
  99
 100                 return $this->rcOptions;
 101         }
 102
 103         /**
 104          * Create a FormOptions object with options as specified by the user
 105          *
 106          * @param array $parameters
 107          *
 108          * @return FormOptions
 109          */
 110         public function setup( $parameters ) {
 111                 $opts = $this->getDefaultOptions();
 112                 foreach ( $this->getCustomFilters() as $key => $params ) {
 113                         $opts->add( $key, $params['default'] );
 114                 }
 115
 116                 $opts = $this->fetchOptionsFromRequest( $opts );
 117
 118                 // Give precedence to subpage syntax
 119                 if ( $parameters !== null ) {
 120                         $this->parseParameters( $parameters, $opts );
 121                 }
 122
 123                 $this->validateOptions( $opts );
 124
 125                 return $opts;
 126         }
 127
 128         /**
 129          * Get a FormOptions object containing the default options. By default returns some basic options,
 130          * you might want to not call parent method and discard them, or to override default values.
 131          *
 132          * @return FormOptions
 133          */
 134         public function getDefaultOptions() {
 135                 $opts = new FormOptions();
 136
 137                 $opts->add( 'hideminor', false );
 138                 $opts->add( 'hidebots', false );
 139                 $opts->add( 'hideanons', false );
 140                 $opts->add( 'hideliu', false );
 141                 $opts->add( 'hidepatrolled', false );
 142                 $opts->add( 'hidemyself', false );
 143
 144                 $opts->add( 'namespace', '', FormOptions::INTNULL );
 145                 $opts->add( 'invert', false );
 146                 $opts->add( 'associated', false );
 147
 148                 return $opts;
 149         }
 150
 151         /**
 152          * Get custom show/hide filters
 153          *
 154          * @return array Map of filter URL param names to properties (msg/default)
 155          */
 156         protected function getCustomFilters() {
 157                 // @todo Fire a Special{$this->getName()}Filters hook here
 158                 return array();
 159         }
 160
 161         /**
 162          * Fetch values for a FormOptions object from the WebRequest associated with this instance.
 163          *
 164          * Intended for subclassing, e.g. to add a backwards-compatibility layer.
 165          *
 166          * @param FormOptions $parameters
 167          * @return FormOptions
 168          */
 169         protected function fetchOptionsFromRequest( $opts ) {
 170                 $opts->fetchValuesFromRequest( $this->getRequest() );
 171                 return $opts;
 172         }
 173
 174         /**
 175          * Process $par and put options found in $opts. Used when including the page.
 176          *
 177          * @param string $par
 178          * @param FormOptions $opts
 179          */
 180         public function parseParameters( $par, FormOptions $opts ) {
 181                 // nothing by default
 182         }
 183
 184         /**
 185          * Validate a FormOptions object generated by getDefaultOptions() with values already populated.
 186          *
 187          * @param FormOptions $opts
 188          */
 189         public function validateOptions( FormOptions $opts ) {
 190                 // nothing by default
 191         }
 192
 193         /**
 194          * Return an array of conditions depending of options set in $opts
 195          *
 196          * @param FormOptions $opts
 197          * @return array
 198          */
 199         public function buildMainQueryConds( FormOptions $opts ) {
 200                 $dbr = $this->getDB();
 201                 $user = $this->getUser();
 202                 $conds = array();
 203
 204                 // It makes no sense to hide both anons and logged-in users. When this occurs, try a guess on
 205                 // what the user meant and either show only bots or force anons to be shown.
 206                 $botsonly = false;
 207                 $hideanons = $opts['hideanons'];
 208                 if ( $opts['hideanons'] && $opts['hideliu'] ) {
 209                         if ( $opts['hidebots'] ) {
 210                                 $hideanons = false;
 211                         } else {
 212                                 $botsonly = true;
 213                         }
 214                 }
 215
 216                 // Toggles
 217                 if ( $opts['hideminor'] ) {
 218                         $conds['rc_minor'] = 0;
 219                 }
 220                 if ( $opts['hidebots'] ) {
 221                         $conds['rc_bot'] = 0;
 222                 }
 223                 if ( $user->useRCPatrol() && $opts['hidepatrolled'] ) {
 224                         $conds['rc_patrolled'] = 0;
 225                 }
 226                 if ( $botsonly ) {
 227                         $conds['rc_bot'] = 1;
 228                 } else {
 229                         if ( $opts['hideliu'] ) {
 230                                 $conds[] = 'rc_user = 0';
 231                         }
 232                         if ( $hideanons ) {
 233                                 $conds[] = 'rc_user != 0';
 234                         }
 235                 }
 236                 if ( $opts['hidemyself'] ) {
 237                         if ( $user->getId() ) {
 238                                 $conds[] = 'rc_user != ' . $dbr->addQuotes( $user->getId() );
 239                         } else {
 240                                 $conds[] = 'rc_user_text != ' . $dbr->addQuotes( $user->getName() );
 241                         }
 242                 }
 243
 244                 // Namespace filtering
 245                 if ( $opts['namespace'] !== '' ) {
 246                         $selectedNS = $dbr->addQuotes( $opts['namespace'] );
 247                         $operator = $opts['invert'] ? '!=' : '=';
 248                         $boolean = $opts['invert'] ? 'AND' : 'OR';
 249
 250                         // Namespace association (bug 2429)
 251                         if ( !$opts['associated'] ) {
 252                                 $condition = "rc_namespace $operator $selectedNS";
 253                         } else {
 254                                 // Also add the associated namespace
 255                                 $associatedNS = $dbr->addQuotes(
 256                                         MWNamespace::getAssociated( $opts['namespace'] )
 257                                 );
 258                                 $condition = "(rc_namespace $operator $selectedNS "
 259                                         . $boolean
 260                                         . " rc_namespace $operator $associatedNS)";
 261                         }
 262
 263                         $conds[] = $condition;
 264                 }
 265
 266                 return $conds;
 267         }
 268
 269         /**
 270          * Process the query
 271          *
 272          * @param array $conds
 273          * @param FormOptions $opts
 274          * @return bool|ResultWrapper Result or false
 275          */
 276         public function doMainQuery( $conds, $opts ) {
 277                 $tables = array( 'recentchanges' );
 278                 $fields = RecentChange::selectFields();
 279                 $query_options = array();
 280                 $join_conds = array();
 281
 282                 ChangeTags::modifyDisplayQuery(
 283                         $tables,
 284                         $fields,
 285                         $conds,
 286                         $join_conds,
 287                         $query_options,
 288                         ''
 289                 );
 290
 291                 // @todo Fire a Special{$this->getName()}Query hook here
 292                 // @todo Uncomment and document
 293                 // if ( !wfRunHooks( 'ChangesListSpecialPageQuery',
 294                 //      array( &$tables, &$fields, &$conds, &$query_options, &$join_conds, $opts ) )
 295                 // ) {
 296                 //      return false;
 297                 // }
 298
 299                 $dbr = $this->getDB();
 300                 return $dbr->select(
 301                         $tables,
 302                         $fields,
 303                         $conds,
 304                         __METHOD__,
 305                         $query_options,
 306                         $join_conds
 307                 );
 308         }
 309
 310         /**
 311          * Return a DatabaseBase object for reading
 312          *
 313          * @return DatabaseBase
 314          */
 315         protected function getDB() {
 316                 return wfGetDB( DB_SLAVE );
 317         }
 318
 319         /**
 320          * Send output to the OutputPage object, only called if not used feeds
 321          *
 322          * @param ResultWrapper $rows Database rows
 323          * @param FormOptions $opts
 324          */
 325         public function webOutput( $rows, $opts ) {
 326                 if ( !$this->including() ) {
 327                         $this->outputFeedLinks();
 328                         $this->doHeader( $opts );
 329                 }
 330
 331                 $this->outputChangesList( $rows, $opts );
 332         }
 333
 334         /**
 335          * Output feed links.
 336          */
 337         public function outputFeedLinks() {
 338                 // nothing by default
 339         }
 340
 341         /**
 342          * Build and output the actual changes list.
 343          *
 344          * @param array $rows Database rows
 345          * @param FormOptions $opts
 346          */
 347         abstract public function outputChangesList( $rows, $opts );
 348
 349         /**
 350          * Return the text to be displayed above the changes
 351          *
 352          * @param FormOptions $opts
 353          * @return string XHTML
 354          */
 355         public function doHeader( $opts ) {
 356                 $this->setTopText( $opts );
 357
 358                 // @todo Lots of stuff should be done here.
 359
 360                 $this->setBottomText( $opts );
 361         }
 362
 363         /**
 364          * Send the text to be displayed before the options. Should use $this->getOutput()->addWikiText()
 365          * or similar methods to print the text.
 366          *
 367          * @param FormOptions $opts
 368          */
 369         function setTopText( FormOptions $opts ) {
 370                 // nothing by default
 371         }
 372
 373         /**
 374          * Send the text to be displayed after the options. Should use $this->getOutput()->addWikiText()
 375          * or similar methods to print the text.
 376          *
 377          * @param FormOptions $opts
 378          */
 379         function setBottomText( FormOptions $opts ) {
 380                 // nothing by default
 381         }
 382
 383         /**
 384          * Get options to be displayed in a form
 385          * @todo This should handle options returned by getDefaultOptions().
 386          * @todo Not called by anything, should be called by something… doHeader() maybe?
 387          *
 388          * @param FormOptions $opts
 389          * @return array
 390          */
 391         function getExtraOptions( $opts ) {
 392                 return array();
 393         }
 394
 395         /**
 396          * Return the legend displayed within the fieldset
 397          * @todo This should not be static, then we can drop the parameter
 398          * @todo Not called by anything, should be called by doHeader()
 399          *
 400          * @param $context the object available as $this in non-static functions
 401          * @return string
 402          */
 403         public static function makeLegend( IContextSource $context ) {
 404                 global $wgRecentChangesFlags;
 405                 $user = $context->getUser();
 406                 # The legend showing what the letters and stuff mean
 407                 $legend = Xml::openElement( 'dl' ) . "\n";
 408                 # Iterates through them and gets the messages for both letter and tooltip
 409                 $legendItems = $wgRecentChangesFlags;
 410                 if ( !$user->useRCPatrol() ) {
 411                         unset( $legendItems['unpatrolled'] );
 412                 }
 413                 foreach ( $legendItems as $key => $legendInfo ) { # generate items of the legend
 414                         $label = $legendInfo['title'];
 415                         $letter = $legendInfo['letter'];
 416                         $cssClass = isset( $legendInfo['class'] ) ? $legendInfo['class'] : $key;
 417
 418                         $legend .= Xml::element( 'dt',
 419                                 array( 'class' => $cssClass ), $context->msg( $letter )->text()
 420                         ) . "\n";
 421                         if ( $key === 'newpage' ) {
 422                                 $legend .= Xml::openElement( 'dd' );
 423                                 $legend .= $context->msg( $label )->escaped();
 424                                 $legend .= ' ' . $context->msg( 'recentchanges-legend-newpage' )->parse();
 425                                 $legend .= Xml::closeElement( 'dd' ) . "\n";
 426                         } else {
 427                                 $legend .= Xml::element( 'dd', array(),
 428                                         $context->msg( $label )->text()
 429                                 ) . "\n";
 430                         }
 431                 }
 432                 # (+-123)
 433                 $legend .= Xml::tags( 'dt',
 434                         array( 'class' => 'mw-plusminus-pos' ),
 435                         $context->msg( 'recentchanges-legend-plusminus' )->parse()
 436                 ) . "\n";
 437                 $legend .= Xml::element(
 438                         'dd',
 439                         array( 'class' => 'mw-changeslist-legend-plusminus' ),
 440                         $context->msg( 'recentchanges-label-plusminus' )->text()
 441                 ) . "\n";
 442                 $legend .= Xml::closeElement( 'dl' ) . "\n";
 443
 444                 # Collapsibility
 445                 $legend =
 446                         '<div class="mw-changeslist-legend">' .
 447                                 $context->msg( 'recentchanges-legend-heading' )->parse() .
 448                                 '<div class="mw-collapsible-content">' . $legend . '</div>' .
 449                         '</div>';
 450
 451                 return $legend;
 452         }
 453
 454         /**
 455          * Add page-specific modules.
 456          */
 457         protected function addModules() {
 458                 $out = $this->getOutput();
 459                 // Styles and behavior for the legend box (see makeLegend())
 460                 $out->addModuleStyles( 'mediawiki.special.changeslist.legend' );
 461                 $out->addModules( 'mediawiki.special.changeslist.legend.js' );
 462         }
 463
 464         /**
 465          * Return an array with a ChangesFeed object and ChannelFeed object.
 466          *
 467          * This is intentionally not abstract not to require subclasses which don't
 468          * use feeds functionality to implement it.
 469          *
 470          * @param string $feedFormat Feed's format (either 'rss' or 'atom')
 471          * @return array
 472          */
 473         public function getFeedObject( $feedFormat ) {
 474                 throw new MWException( "Not implemented" );
 475         }
 476
 477         /**
 478          * Get last-modified date, for client caching. Not implemented by default
 479          * (returns current time).
 480          *
 481          * @param string $feedFormat
 482          * @return string|bool
 483          */
 484         public function checkLastModified( $feedFormat ) {
 485                 return wfTimestampNow();
 486         }
 487
 488         protected function getGroupName() {
 489                 return 'changes';
 490         }
 491 }