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