SlotRoleHandler.php 5.2 KB

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