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