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
21 * @author Matthew Flaschen
24 use Wikimedia\Rdbms\IDatabase
;
27 * Represents a filter group with multiple string options. They are passed to the server as
28 * a single form parameter separated by a delimiter. The parameter name is the
29 * group name. E.g. groupname=opt1;opt2 .
31 * If all options are selected they are replaced by the term "all".
33 * There is also a single DB query modification for the whole group.
37 class ChangesListStringOptionsFilterGroup
extends ChangesListFilterGroup
{
39 * Type marker, used by JavaScript
41 const TYPE
= 'string_options';
46 const SEPARATOR
= ';';
49 * Signifies that all options in the group are selected.
54 * Signifies that no options in the group are selected, meaning the group has no effect.
56 * For full-coverage groups, this is the same as ALL if all filters are allowed.
57 * For others, it is not.
62 * Defaul parameter value
64 * @var string $defaultValue
66 protected $defaultValue;
69 * Callable used to do the actual query modification; see constructor
71 * @var callable $queryCallable
73 protected $queryCallable;
76 * Create a new filter group with the specified configuration
78 * @param array $groupDefinition Configuration of group
79 * * $groupDefinition['name'] string Group name
80 * * $groupDefinition['title'] string i18n key for title (optional, can be omitted
81 * only if none of the filters in the group display in the structured UI)
82 * * $groupDefinition['priority'] int Priority integer. Higher means higher in the
84 * * $groupDefinition['filters'] array Numeric array of filter definitions, each of which
85 * is an associative array to be passed to the filter constructor. However,
86 * 'priority' is optional for the filters. Any filter that has priority unset
87 * will be put to the bottom, in the order given.
88 * * $groupDefinition['default'] string Default for group.
89 * * $groupDefinition['isFullCoverage'] bool Whether the group is full coverage;
90 * if true, this means that checking every item in the group means no
91 * changes list entries are filtered out.
92 * * $groupDefinition['queryCallable'] callable Callable accepting parameters:
93 * * string $specialPageClassName Class name of current special page
94 * * IContextSource $context Context, for e.g. user
95 * * IDatabase $dbr Database, for addQuotes, makeList, and similar
96 * * array &$tables Array of tables; see IDatabase::select $table
97 * * array &$fields Array of fields; see IDatabase::select $vars
98 * * array &$conds Array of conditions; see IDatabase::select $conds
99 * * array &$query_options Array of query options; see IDatabase::select $options
100 * * array &$join_conds Array of join conditions; see IDatabase::select $join_conds
101 * * array $selectedValues The allowed and requested values, lower-cased and sorted
102 * * $groupDefinition['whatsThisHeader'] string i18n key for header of "What's
103 * This" popup (optional).
104 * * $groupDefinition['whatsThisBody'] string i18n key for body of "What's This"
106 * * $groupDefinition['whatsThisUrl'] string URL for main link of "What's This"
108 * * $groupDefinition['whatsThisLinkText'] string i18n key of text for main link of
109 * "What's This" popup (optional).
111 public function __construct( array $groupDefinition ) {
112 if ( !isset( $groupDefinition['isFullCoverage'] ) ) {
113 throw new MWException( 'You must specify isFullCoverage' );
116 $groupDefinition['type'] = self
::TYPE
;
118 parent
::__construct( $groupDefinition );
120 $this->queryCallable
= $groupDefinition['queryCallable'];
122 if ( isset( $groupDefinition['default'] ) ) {
123 $this->setDefault( $groupDefinition['default'] );
125 throw new MWException( 'You must specify a default' );
130 * Sets default of filter group.
132 * @param string $defaultValue
134 public function setDefault( $defaultValue ) {
135 $this->defaultValue
= $defaultValue;
139 * Gets default of filter group
141 * @return string $defaultValue
143 public function getDefault() {
144 return $this->defaultValue
;
150 protected function createFilter( array $filterDefinition ) {
151 return new ChangesListStringOptionsFilter( $filterDefinition );
155 * Registers a filter in this group
157 * @param ChangesListStringOptionsFilter $filter
158 * @suppress PhanParamSignaturePHPDocMismatchHasParamType,PhanParamSignatureMismatch
160 public function registerFilter( ChangesListStringOptionsFilter
$filter ) {
161 $this->filters
[$filter->getName()] = $filter;
167 public function modifyQuery( IDatabase
$dbr, ChangesListSpecialPage
$specialPage,
168 &$tables, &$fields, &$conds, &$query_options, &$join_conds,
169 FormOptions
$opts, $isStructuredFiltersEnabled
171 if ( !$this->isActive( $isStructuredFiltersEnabled ) ) {
175 $value = $opts[ $this->getName() ];
176 $allowedFilterNames = [];
177 foreach ( $this->filters
as $filter ) {
178 $allowedFilterNames[] = $filter->getName();
181 if ( $value === self
::ALL
) {
182 $selectedValues = $allowedFilterNames;
184 $selectedValues = explode( self
::SEPARATOR
, strtolower( $value ) );
186 // remove values that are not recognized or not currently allowed
187 $selectedValues = array_intersect(
193 // If there are now no values, because all are disallowed or invalid (also,
194 // the user may not have selected any), this is a no-op.
196 // If everything is unchecked, the group always has no effect, regardless
198 if ( count( $selectedValues ) === 0 ) {
202 sort( $selectedValues );
204 ( $this->queryCallable
)(
205 get_class( $specialPage ),
206 $specialPage->getContext(),
220 public function getJsData() {
221 $output = parent
::getJsData();
223 $output['separator'] = self
::SEPARATOR
;
224 $output['default'] = $this->getDefault();
232 public function addOptions( FormOptions
$opts, $allowDefaults, $isStructuredFiltersEnabled ) {
233 $opts->add( $this->getName(), $allowDefaults ?
$this->getDefault() : '' );
237 * Check if this filter group is currently active
239 * @param bool $isStructuredUI Is structured filters UI current enabled
242 private function isActive( $isStructuredUI ) {
243 // STRING_OPTIONS filter groups are exclusively active on Structured UI
244 return $isStructuredUI;