includes/Revision/SlotRoleHandler.php

   1 <?php
   2 /**
   3  * This file is part of MediaWiki.
   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  */
  22
  23 namespace MediaWiki\Revision;
  24
  25 use MediaWiki\Linker\LinkTarget;
  26
  27 /**
  28  * SlotRoleHandler instances are used to declare the existence and behavior of slot roles.
  29  * Most importantly, they control which content model can be used for the slot, and how it is
  30  * represented in the rendered verswion of page content.
  31  *
  32  * @since 1.33
  33  */
  34 class SlotRoleHandler {
  35
  36         /**
  37          * @var string
  38          */
  39         private $role;
  40
  41         /**
  42          * @var array
  43          * @see getOutputLayoutHints
  44          */
  45         private $layout = [
  46                 'display' => 'section', // use 'none' to suppress
  47                 'region' => 'center',
  48                 'placement' => 'append'
  49         ];
  50
  51         /**
  52          * @var string
  53          */
  54         private $contentModel;
  55
  56         /**
  57          * @param string $role The name of the slot role defined by this SlotRoleHandler. See
  58          *        SlotRoleRegistry::defineRole for more information.
  59          * @param string $contentModel The default content model for this slot. As per the default
  60          *        implementation of isAllowedModel(), also the only content model allowed for the
  61          *        slot. Subclasses may however handle default and allowed models differently.
  62          * @param array $layout Layout hints, for use by RevisionRenderer. See getOutputLayoutHints.
  63          */
  64         public function __construct( $role, $contentModel, $layout = [] ) {
  65                 $this->role = $role;
  66                 $this->contentModel = $contentModel;
  67                 $this->layout = array_merge( $this->layout, $layout );
  68         }
  69
  70         /**
  71          * @return string The role this SlotRoleHandler applies to
  72          */
  73         public function getRole() {
  74                 return $this->role;
  75         }
  76
  77         /**
  78          * Layout hints for use while laying out the combined output of all slots, typically by
  79          * RevisionRenderer. The layout hints are given as an associative array. Well-known keys
  80          * to use:
  81          *
  82          * * "display": how the output of this slot should be represented. Supported values:
  83          *   - "section": show as a top level section of the region.
  84          *   - "none": do not show at all
  85          *   Further values that may be supported in the future include "box" and "banner".
  86          * * "region": in which region of the page the output should be placed. Supported values:
  87          *   - "center": the central content area.
  88          *   Further values that may be supported in the future include "top" and "bottom", "left"
  89          *   and "right", "header" and "footer".
  90          * * "placement": placement relative to other content of the same area.
  91          *   - "append": place at the end, after any output processed previously.
  92          *   Further values that may be supported in the future include "prepend". A "weight" key
  93          *   may be introduced for more fine grained control.
  94          *
  95          * @return array an associative array of hints
  96          */
  97         public function getOutputLayoutHints() {
  98                 return $this->layout;
  99         }
 100
 101         /**
 102          * The message key for the translation of the slot name.
 103          *
 104          * @return string
 105          */
 106         public function getNameMessageKey() {
 107                 return 'slot-name-' . $this->role;
 108         }
 109
 110         /**
 111          * Determines the content model to use per default for this slot on the given page.
 112          *
 113          * The default implementation always returns the content model provided to the constructor.
 114          * Subclasses may base the choice on default model on the page title or namespace.
 115          * The choice should not depend on external state, such as the page content.
 116          *
 117          * @param LinkTarget $page
 118          *
 119          * @return string
 120          */
 121         public function getDefaultModel( LinkTarget $page ) {
 122                 return $this->contentModel;
 123         }
 124
 125         /**
 126          * Determines whether the given model can be used on this slot on the given page.
 127          *
 128          * The default implementation checks whether $model is the content model provided to the
 129          * constructor. Subclasses may allow other models and may base the decision on the page title
 130          * or namespace. The choice should not depend on external state, such as the page content.
 131          *
 132          * @note This should be checked when creating new revisions. Existing revisions
 133          *       are not guaranteed to comply with the return value.
 134          *
 135          * @param string $model
 136          * @param LinkTarget $page
 137          *
 138          * @return bool
 139          */
 140         public function isAllowedModel( $model, LinkTarget $page ) {
 141                 return ( $model === $this->contentModel );
 142         }
 143
 144         /**
 145          * Whether this slot should be considered when determining whether a page should be counted
 146          * as an "article" in the site statistics.
 147          *
 148          * For a page to be considered countable, one of the page's slots must return true from this
 149          * method, and Content::isCountable() must return true for the content of that slot.
 150          *
 151          * The default implementation always returns false.
 152          *
 153          * @return bool
 154          */
 155         public function supportsArticleCount() {
 156                 return false;
 157         }
 158
 159 }