3 * Represents a filter group (used on ChangesListSpecialPage and descendants)
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.
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.
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
22 * @author Matthew Flaschen
25 // TODO: Might want to make a super-class or trait to share behavior (especially re
26 // conflicts) between ChangesListFilter and ChangesListFilterGroup.
27 // What to call it. FilterStructure? That would also let me make
28 // setUnidirectionalConflict protected.
30 use Wikimedia\Rdbms\IDatabase
;
33 * Represents a filter group (used on ChangesListSpecialPage and descendants)
37 abstract class ChangesListFilterGroup
{
39 * Name (internal identifier)
53 * i18n key for header of What's This?
55 * @var string|null $whatsThisHeader
57 protected $whatsThisHeader;
60 * i18n key for body of What's This?
62 * @var string|null $whatsThisBody
64 protected $whatsThisBody;
67 * URL of What's This? link
69 * @var string|null $whatsThisUrl
71 protected $whatsThisUrl;
74 * i18n key for What's This? link
76 * @var string|null $whatsThisLinkText
78 protected $whatsThisLinkText;
81 * Type, from a TYPE constant of a subclass
88 * Priority integer. Higher values means higher up in the
91 * @var string $priority
96 * Associative array of filters, as ChangesListFilter objects, with filter name as key
103 * Whether this group is full coverage. This means that checking every item in the
104 * group means no changes list (e.g. RecentChanges) entries are filtered out.
106 * @var bool $isFullCoverage
108 protected $isFullCoverage;
111 * Array of associative arrays with conflict information. See
112 * setUnidirectionalConflict
114 * @var array $conflictingGroups
116 protected $conflictingGroups = [];
119 * Array of associative arrays with conflict information. See
120 * setUnidirectionalConflict
122 * @var array $conflictingFilters
124 protected $conflictingFilters = [];
126 const DEFAULT_PRIORITY
= -100;
128 const RESERVED_NAME_CHAR
= '_';
131 * Create a new filter group with the specified configuration
133 * @param array $groupDefinition Configuration of group
134 * * $groupDefinition['name'] string Group name; use camelCase with no punctuation
135 * * $groupDefinition['title'] string i18n key for title (optional, can be omitted
136 * only if none of the filters in the group display in the structured UI)
137 * * $groupDefinition['type'] string A type constant from a subclass of this one
138 * * $groupDefinition['priority'] int Priority integer. Higher value means higher
139 * up in the group list (optional, defaults to -100).
140 * * $groupDefinition['filters'] array Numeric array of filter definitions, each of which
141 * is an associative array to be passed to the filter constructor. However,
142 * 'priority' is optional for the filters. Any filter that has priority unset
143 * will be put to the bottom, in the order given.
144 * * $groupDefinition['isFullCoverage'] bool Whether the group is full coverage;
145 * if true, this means that checking every item in the group means no
146 * changes list entries are filtered out.
147 * * $groupDefinition['whatsThisHeader'] string i18n key for header of "What's
148 * This" popup (optional).
149 * * $groupDefinition['whatsThisBody'] string i18n key for body of "What's This"
151 * * $groupDefinition['whatsThisUrl'] string URL for main link of "What's This"
153 * * $groupDefinition['whatsThisLinkText'] string i18n key of text for main link of
154 * "What's This" popup (optional).
156 public function __construct( array $groupDefinition ) {
157 if ( strpos( $groupDefinition['name'], self
::RESERVED_NAME_CHAR
) !== false ) {
158 throw new MWException( 'Group names may not contain \'' .
159 self
::RESERVED_NAME_CHAR
.
160 '\'. Use the naming convention: \'camelCase\''
164 $this->name
= $groupDefinition['name'];
166 if ( isset( $groupDefinition['title'] ) ) {
167 $this->title
= $groupDefinition['title'];
170 if ( isset( $groupDefinition['whatsThisHeader'] ) ) {
171 $this->whatsThisHeader
= $groupDefinition['whatsThisHeader'];
172 $this->whatsThisBody
= $groupDefinition['whatsThisBody'];
173 $this->whatsThisUrl
= $groupDefinition['whatsThisUrl'];
174 $this->whatsThisLinkText
= $groupDefinition['whatsThisLinkText'];
177 $this->type
= $groupDefinition['type'];
178 if ( isset( $groupDefinition['priority'] ) ) {
179 $this->priority
= $groupDefinition['priority'];
181 $this->priority
= self
::DEFAULT_PRIORITY
;
184 $this->isFullCoverage
= $groupDefinition['isFullCoverage'];
187 $lowestSpecifiedPriority = -1;
188 foreach ( $groupDefinition['filters'] as $filterDefinition ) {
189 if ( isset( $filterDefinition['priority'] ) ) {
190 $lowestSpecifiedPriority = min( $lowestSpecifiedPriority, $filterDefinition['priority'] );
194 // Convenience feature: If you specify a group (and its filters) all in
195 // one place, you don't have to specify priority. You can just put them
196 // in order. However, if you later add one (e.g. an extension adds a filter
197 // to a core-defined group), you need to specify it.
198 $autoFillPriority = $lowestSpecifiedPriority - 1;
199 foreach ( $groupDefinition['filters'] as $filterDefinition ) {
200 if ( !isset( $filterDefinition['priority'] ) ) {
201 $filterDefinition['priority'] = $autoFillPriority;
204 $filterDefinition['group'] = $this;
206 $filter = $this->createFilter( $filterDefinition );
207 $this->registerFilter( $filter );
212 * Creates a filter of the appropriate type for this group, from the definition
214 * @param array $filterDefinition Filter definition
215 * @return ChangesListFilter Filter
217 abstract protected function createFilter( array $filterDefinition );
220 * Marks that the given ChangesListFilterGroup or ChangesListFilter conflicts with this object.
222 * WARNING: This means there is a conflict when both things are *shown*
223 * (not filtered out), even for the hide-based filters. So e.g. conflicting with
224 * 'hideanons' means there is a conflict if only anonymous users are *shown*.
226 * @param ChangesListFilterGroup|ChangesListFilter $other Other
227 * ChangesListFilterGroup or ChangesListFilter
228 * @param string $globalKey i18n key for top-level conflict message
229 * @param string $forwardKey i18n key for conflict message in this
230 * direction (when in UI context of $this object)
231 * @param string $backwardKey i18n key for conflict message in reverse
232 * direction (when in UI context of $other object)
234 public function conflictsWith( $other, $globalKey, $forwardKey, $backwardKey ) {
235 if ( $globalKey === null ||
$forwardKey === null ||
$backwardKey === null ) {
236 throw new MWException( 'All messages must be specified' );
239 $this->setUnidirectionalConflict(
245 $other->setUnidirectionalConflict(
253 * Marks that the given ChangesListFilterGroup or ChangesListFilter conflicts with
258 * @param ChangesListFilterGroup|ChangesListFilter $other Other
259 * ChangesListFilterGroup or ChangesListFilter
260 * @param string $globalDescription i18n key for top-level conflict message
261 * @param string $contextDescription i18n key for conflict message in this
262 * direction (when in UI context of $this object)
264 public function setUnidirectionalConflict( $other, $globalDescription, $contextDescription ) {
265 if ( $other instanceof ChangesListFilterGroup
) {
266 $this->conflictingGroups
[] = [
267 'group' => $other->getName(),
268 'groupObject' => $other,
269 'globalDescription' => $globalDescription,
270 'contextDescription' => $contextDescription,
272 } elseif ( $other instanceof ChangesListFilter
) {
273 $this->conflictingFilters
[] = [
274 'group' => $other->getGroup()->getName(),
275 'filter' => $other->getName(),
276 'filterObject' => $other,
277 'globalDescription' => $globalDescription,
278 'contextDescription' => $contextDescription,
281 throw new MWException( 'You can only pass in a ChangesListFilterGroup or a ChangesListFilter' );
286 * @return string Internal name
288 public function getName() {
293 * @return string i18n key for title
295 public function getTitle() {
300 * @return string Type (TYPE constant from a subclass)
302 public function getType() {
307 * @return int Priority. Higher means higher in the group list
309 public function getPriority() {
310 return $this->priority
;
314 * @return ChangesListFilter[] Associative array of ChangesListFilter objects, with
317 public function getFilters() {
318 return $this->filters
;
324 * @param string $name Filter name
325 * @return ChangesListFilter|null Specified filter, or null if it is not registered
327 public function getFilter( $name ) {
328 return isset( $this->filters
[$name] ) ?
$this->filters
[$name] : null;
332 * Gets the JS data in the format required by the front-end of the structured UI
334 * @return array|null Associative array, or null if there are no filters that
335 * display in the structured UI. messageKeys is a special top-level value, with
336 * the value being an array of the message keys to send to the client.
338 public function getJsData() {
340 'name' => $this->name
,
341 'type' => $this->type
,
342 'fullCoverage' => $this->isFullCoverage
,
344 'priority' => $this->priority
,
346 'messageKeys' => [ $this->title
]
349 if ( isset( $this->whatsThisHeader
) ) {
350 $output['whatsThisHeader'] = $this->whatsThisHeader
;
351 $output['whatsThisBody'] = $this->whatsThisBody
;
352 $output['whatsThisUrl'] = $this->whatsThisUrl
;
353 $output['whatsThisLinkText'] = $this->whatsThisLinkText
;
356 $output['messageKeys'],
357 $output['whatsThisHeader'],
358 $output['whatsThisBody'],
359 $output['whatsThisLinkText']
363 usort( $this->filters
, function ( $a, $b ) {
364 return $b->getPriority() - $a->getPriority();
367 foreach ( $this->filters
as $filterName => $filter ) {
368 if ( $filter->displaysOnStructuredUi() ) {
369 $filterData = $filter->getJsData();
370 $output['messageKeys'] = array_merge(
371 $output['messageKeys'],
372 $filterData['messageKeys']
374 unset( $filterData['messageKeys'] );
375 $output['filters'][] = $filterData;
379 if ( count( $output['filters'] ) === 0 ) {
383 $output['title'] = $this->title
;
385 $conflicts = array_merge(
386 $this->conflictingGroups
,
387 $this->conflictingFilters
390 foreach ( $conflicts as $conflictInfo ) {
391 unset( $conflictInfo['filterObject'] );
392 unset( $conflictInfo['groupObject'] );
393 $output['conflicts'][] = $conflictInfo;
395 $output['messageKeys'],
396 $conflictInfo['globalDescription'],
397 $conflictInfo['contextDescription']
405 * Get groups conflicting with this filter group
407 * @return ChangesListFilterGroup[]
409 public function getConflictingGroups() {
411 function ( $conflictDesc ) {
412 return $conflictDesc[ 'groupObject' ];
414 $this->conflictingGroups
419 * Get filters conflicting with this filter group
421 * @return ChangesListFilter[]
423 public function getConflictingFilters() {
425 function ( $conflictDesc ) {
426 return $conflictDesc[ 'filterObject' ];
428 $this->conflictingFilters
433 * Check if any filter in this group is selected
435 * @param FormOptions $opts
438 public function anySelected( FormOptions
$opts ) {
439 return !!count( array_filter(
441 function ( ChangesListFilter
$filter ) use ( $opts ) {
442 return $filter->isSelected( $opts );
448 * Modifies the query to include the filter group.
450 * The modification is only done if the filter group is in effect. This means that
451 * one or more valid and allowed filters were selected.
453 * @param IDatabase $dbr Database, for addQuotes, makeList, and similar
454 * @param ChangesListSpecialPage $specialPage Current special page
455 * @param array &$tables Array of tables; see IDatabase::select $table
456 * @param array &$fields Array of fields; see IDatabase::select $vars
457 * @param array &$conds Array of conditions; see IDatabase::select $conds
458 * @param array &$query_options Array of query options; see IDatabase::select $options
459 * @param array &$join_conds Array of join conditions; see IDatabase::select $join_conds
460 * @param FormOptions $opts Wrapper for the current request options and their defaults
461 * @param bool $isStructuredFiltersEnabled True if the Structured UI is currently enabled
463 abstract public function modifyQuery( IDatabase
$dbr, ChangesListSpecialPage
$specialPage,
464 &$tables, &$fields, &$conds, &$query_options, &$join_conds,
465 FormOptions
$opts, $isStructuredFiltersEnabled );
468 * All the options represented by this filter group to $opts
470 * @param FormOptions $opts
471 * @param bool $allowDefaults
472 * @param bool $isStructuredFiltersEnabled
474 abstract public function addOptions( FormOptions
$opts, $allowDefaults,
475 $isStructuredFiltersEnabled );