Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00% covered (success)
100.00%
11 / 11
100.00% covered (success)
100.00%
8 / 8
 CRAP
100.00% covered (success)
100.00%
1 / 1
SlotRoleHandler
100.00% covered (success)
100.00%
11 / 11
100.00% covered (success)
100.00%
8 / 8
 8
100.00% covered (success)
100.00%
1 / 1
 __construct
100.00% covered (success)
100.00%
4 / 4
100.00% covered (success)
100.00%
1 / 1
 1
 getRole
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 getOutputLayoutHints
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 isDerived
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 getNameMessageKey
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 getDefaultModel
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 isAllowedModel
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 supportsArticleCount
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
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
23namespace MediaWiki\Revision;
24
25use MediaWiki\Linker\LinkTarget;
26use 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 */
37class 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}