3 * Represents a filter (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
21 * @author Matthew Flaschen
25 * Represents a filter (used on ChangesListSpecialPage and descendants)
29 abstract class ChangesListFilter
{
38 * CSS class suffix used for attribution, e.g. 'bot'.
40 * In this example, if bot actions are included in the result set, this CSS class
41 * will then be included in all bot-flagged actions.
43 * @var string|null $cssClassSuffix
45 protected $cssClassSuffix;
48 * Callable that returns true if and only if a row is attributed to this filter
50 * @var callable $isRowApplicableCallable
52 protected $isRowApplicableCallable;
55 * Group. ChangesListFilterGroup this belongs to
57 * @var ChangesListFilterGroup $group
62 * i18n key of label for structured UI
69 * i18n key of description for structured UI
71 * @var string $description
73 protected $description;
76 * Array of associative arrays with conflict information. See
77 * setUnidirectionalConflict
79 * @var array $conflictingGroups
81 protected $conflictingGroups = [];
84 * Array of associative arrays with conflict information. See
85 * setUnidirectionalConflict
87 * @var array $conflictingFilters
89 protected $conflictingFilters = [];
92 * Array of associative arrays with subset information
94 * @var array $subsetFilters
96 protected $subsetFilters = [];
99 * Priority integer. Higher value means higher up in the group's filter list.
101 * @var string $priority
107 * @var string $defaultHighlightColor
109 protected $defaultHighlightColor;
111 const RESERVED_NAME_CHAR
= '_';
114 * Creates a new filter with the specified configuration, and registers it to the
117 * It infers which UI (it can be either or both) to display the filter on based on
118 * which messages are provided.
120 * If 'label' is provided, it will be displayed on the structured UI. Thus,
121 * 'label', 'description', and sub-class parameters are optional depending on which
124 * @param array $filterDefinition ChangesListFilter definition
125 * * $filterDefinition['name'] string Name of filter; use lowercase with no
127 * * $filterDefinition['cssClassSuffix'] string CSS class suffix, used to mark
128 * that a particular row belongs to this filter (when a row is included by the
130 * * $filterDefinition['isRowApplicableCallable'] Callable taking two parameters, the
131 * IContextSource, and the RecentChange object for the row, and returning true if
132 * the row is attributed to this filter. The above CSS class will then be
133 * automatically added (optional, required if cssClassSuffix is used).
134 * * $filterDefinition['group'] ChangesListFilterGroup Group. Filter group this
136 * * $filterDefinition['label'] string i18n key of label for structured UI.
137 * * $filterDefinition['description'] string i18n key of description for structured
139 * * $filterDefinition['priority'] int Priority integer. Higher value means higher
140 * up in the group's filter list.
142 public function __construct( array $filterDefinition ) {
143 if ( isset( $filterDefinition['group'] ) ) {
144 $this->group
= $filterDefinition['group'];
146 throw new MWException( 'You must use \'group\' to specify the ' .
147 'ChangesListFilterGroup this filter belongs to' );
150 if ( strpos( $filterDefinition['name'], self
::RESERVED_NAME_CHAR
) !== false ) {
151 throw new MWException( 'Filter names may not contain \'' .
152 self
::RESERVED_NAME_CHAR
.
153 '\'. Use the naming convention: \'lowercase\''
157 if ( $this->group
->getFilter( $filterDefinition['name'] ) ) {
158 throw new MWException( 'Two filters in a group cannot have the ' .
159 "same name: '{$filterDefinition['name']}'" );
162 $this->name
= $filterDefinition['name'];
164 if ( isset( $filterDefinition['cssClassSuffix'] ) ) {
165 $this->cssClassSuffix
= $filterDefinition['cssClassSuffix'];
166 $this->isRowApplicableCallable
= $filterDefinition['isRowApplicableCallable'];
169 if ( isset( $filterDefinition['label'] ) ) {
170 $this->label
= $filterDefinition['label'];
171 $this->description
= $filterDefinition['description'];
174 $this->priority
= $filterDefinition['priority'];
176 $this->group
->registerFilter( $this );
180 * Marks that the given ChangesListFilterGroup or ChangesListFilter conflicts with this object.
182 * WARNING: This means there is a conflict when both things are *shown*
183 * (not filtered out), even for the hide-based filters. So e.g. conflicting with
184 * 'hideanons' means there is a conflict if only anonymous users are *shown*.
186 * @param ChangesListFilterGroup|ChangesListFilter $other
187 * @param string $globalKey i18n key for top-level conflict message
188 * @param string $forwardKey i18n key for conflict message in this
189 * direction (when in UI context of $this object)
190 * @param string $backwardKey i18n key for conflict message in reverse
191 * direction (when in UI context of $other object)
193 public function conflictsWith( $other, $globalKey, $forwardKey, $backwardKey ) {
194 if ( $globalKey === null ||
$forwardKey === null ||
$backwardKey === null ) {
195 throw new MWException( 'All messages must be specified' );
198 $this->setUnidirectionalConflict(
204 $other->setUnidirectionalConflict(
212 * Marks that the given ChangesListFilterGroup or ChangesListFilter conflicts with
217 * @param ChangesListFilterGroup|ChangesListFilter $other
218 * @param string $globalDescription i18n key for top-level conflict message
219 * @param string $contextDescription i18n key for conflict message in this
220 * direction (when in UI context of $this object)
222 public function setUnidirectionalConflict( $other, $globalDescription, $contextDescription ) {
223 if ( $other instanceof ChangesListFilterGroup
) {
224 $this->conflictingGroups
[] = [
225 'group' => $other->getName(),
226 'groupObject' => $other,
227 'globalDescription' => $globalDescription,
228 'contextDescription' => $contextDescription,
230 } elseif ( $other instanceof ChangesListFilter
) {
231 $this->conflictingFilters
[] = [
232 'group' => $other->getGroup()->getName(),
233 'filter' => $other->getName(),
234 'filterObject' => $other,
235 'globalDescription' => $globalDescription,
236 'contextDescription' => $contextDescription,
239 throw new MWException( 'You can only pass in a ChangesListFilterGroup or a ChangesListFilter' );
244 * Marks that the current instance is (also) a superset of the filter passed in.
245 * This can be called more than once.
247 * This means that anything in the results for the other filter is also in the
248 * results for this one.
250 * @param ChangesListFilter $other The filter the current instance is a superset of
252 public function setAsSupersetOf( ChangesListFilter
$other ) {
253 if ( $other->getGroup() !== $this->getGroup() ) {
254 throw new MWException( 'Supersets can only be defined for filters in the same group' );
257 $this->subsetFilters
[] = [
258 // It's always the same group, but this makes the representation
259 // more consistent with conflicts.
260 'group' => $other->getGroup()->getName(),
261 'filter' => $other->getName(),
266 * @return string Name, e.g. hideanons
268 public function getName() {
273 * @return ChangesListFilterGroup Group this belongs to
275 public function getGroup() {
280 * @return string i18n key of label for structured UI
282 public function getLabel() {
287 * @return string i18n key of description for structured UI
289 public function getDescription() {
290 return $this->description
;
294 * Checks whether the filter should display on the unstructured UI
296 * @return bool Whether to display
298 abstract public function displaysOnUnstructuredUi();
301 * Checks whether the filter should display on the structured UI
302 * This refers to the exact filter. See also isFeatureAvailableOnStructuredUi.
304 * @return bool Whether to display
306 public function displaysOnStructuredUi() {
307 return $this->label
!== null;
311 * Checks whether an equivalent feature for this filter is available on the
314 * This can either be the exact filter, or a new filter that replaces it.
317 public function isFeatureAvailableOnStructuredUi() {
318 return $this->displaysOnStructuredUi();
322 * @return int Priority. Higher value means higher up in the group list
324 public function getPriority() {
325 return $this->priority
;
331 * @return string|null CSS class, or null if not defined
333 protected function getCssClass() {
334 if ( $this->cssClassSuffix
!== null ) {
335 return ChangesList
::CSS_CLASS_PREFIX
. $this->cssClassSuffix
;
342 * Add CSS class if needed
344 * @param IContextSource $ctx Context source
345 * @param RecentChange $rc Recent changes object
346 * @param array &$classes Non-associative array of CSS class names; appended to if needed
348 public function applyCssClassIfNeeded( IContextSource
$ctx, RecentChange
$rc, array &$classes ) {
349 if ( $this->isRowApplicableCallable
=== null ) {
353 if ( call_user_func( $this->isRowApplicableCallable
, $ctx, $rc ) ) {
354 $classes[] = $this->getCssClass();
359 * Gets the JS data required by the front-end of the structured UI
361 * @return array Associative array Data required by the front-end. messageKeys is
362 * a special top-level value, with the value being an array of the message keys to
363 * send to the client.
365 public function getJsData() {
367 'name' => $this->getName(),
368 'label' => $this->getLabel(),
369 'description' => $this->getDescription(),
370 'cssClass' => $this->getCssClass(),
371 'priority' => $this->priority
,
372 'subset' => $this->subsetFilters
,
374 'defaultHighlightColor' => $this->defaultHighlightColor
377 $output['messageKeys'] = [
379 $this->getDescription(),
382 $conflicts = array_merge(
383 $this->conflictingGroups
,
384 $this->conflictingFilters
387 foreach ( $conflicts as $conflictInfo ) {
388 unset( $conflictInfo['filterObject'] );
389 unset( $conflictInfo['groupObject'] );
390 $output['conflicts'][] = $conflictInfo;
392 $output['messageKeys'],
393 $conflictInfo['globalDescription'],
394 $conflictInfo['contextDescription']
402 * Checks whether this filter is selected in the provided options
404 * @param FormOptions $opts
407 abstract public function isSelected( FormOptions
$opts );
410 * Get groups conflicting with this filter
412 * @return ChangesListFilterGroup[]
414 public function getConflictingGroups() {
416 function ( $conflictDesc ) {
417 return $conflictDesc[ 'groupObject' ];
419 $this->conflictingGroups
424 * Get filters conflicting with this filter
426 * @return ChangesListFilter[]
428 public function getConflictingFilters() {
430 function ( $conflictDesc ) {
431 return $conflictDesc[ 'filterObject' ];
433 $this->conflictingFilters
438 * Check if the conflict with a group is currently "active"
440 * @param ChangesListFilterGroup $group
441 * @param FormOptions $opts
444 public function activelyInConflictWithGroup( ChangesListFilterGroup
$group, FormOptions
$opts ) {
445 if ( $group->anySelected( $opts ) && $this->isSelected( $opts ) ) {
446 /** @var ChangesListFilter $siblingFilter */
447 foreach ( $this->getSiblings() as $siblingFilter ) {
448 if ( $siblingFilter->isSelected( $opts ) && !$siblingFilter->hasConflictWithGroup( $group ) ) {
457 private function hasConflictWithGroup( ChangesListFilterGroup
$group ) {
458 return in_array( $group, $this->getConflictingGroups() );
462 * Check if the conflict with a filter is currently "active"
464 * @param ChangesListFilter $filter
465 * @param FormOptions $opts
468 public function activelyInConflictWithFilter( ChangesListFilter
$filter, FormOptions
$opts ) {
469 if ( $this->isSelected( $opts ) && $filter->isSelected( $opts ) ) {
470 /** @var ChangesListFilter $siblingFilter */
471 foreach ( $this->getSiblings() as $siblingFilter ) {
473 $siblingFilter->isSelected( $opts ) &&
474 !$siblingFilter->hasConflictWithFilter( $filter )
484 private function hasConflictWithFilter( ChangesListFilter
$filter ) {
485 return in_array( $filter, $this->getConflictingFilters() );
489 * Get filters in the same group
491 * @return ChangesListFilter[]
493 protected function getSiblings() {
495 $this->getGroup()->getFilters(),
496 function ( $filter ) {
497 return $filter !== $this;
503 * @param string $defaultHighlightColor
505 public function setDefaultHighlightColor( $defaultHighlightColor ) {
506 $this->defaultHighlightColor
= $defaultHighlightColor;