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 use Wikimedia\Rdbms\IDatabase
;
28 * Represents a filter group with multiple string options. They are passed to the server as
29 * a single form parameter separated by a delimiter. The parameter name is the
30 * group name. E.g. groupname=opt1;opt2 .
32 * If all options are selected they are replaced by the term "all".
34 * There is also a single DB query modification for the whole group.
39 class ChangesListStringOptionsFilterGroup
extends ChangesListFilterGroup
{
41 * Type marker, used by JavaScript
43 const TYPE
= 'string_options';
48 const SEPARATOR
= ';';
51 * Signifies that all options in the group are selected.
56 * Signifies that no options in the group are selected, meaning the group has no effect.
58 * For full-coverage groups, this is the same as ALL if all filters are allowed.
59 * For others, it is not.
64 * Group name; used as form parameter.
70 * Defaul parameter value
72 * @var string $defaultValue
74 protected $defaultValue;
77 * Callable used to do the actual query modification; see constructor
79 * @var callable $queryCallable
81 protected $queryCallable;
84 * Create a new filter group with the specified configuration
86 * @param array $groupDefinition Configuration of group
87 * * $groupDefinition['name'] string Group name
88 * * $groupDefinition['title'] string i18n key for title (optional, can be omitted
89 * * only if none of the filters in the group display in the structured UI)
90 * * $groupDefinition['priority'] int Priority integer. Higher means higher in the
92 * * $groupDefinition['filters'] array Numeric array of filter definitions, each of which
93 * * is an associative array to be passed to the filter constructor. However,
94 * * 'priority' is optional for the filters. Any filter that has priority unset
95 * * will be put to the bottom, in the order given.
96 * * $groupDefinition['default'] string Default for group.
97 * * $groupDefinition['isFullCoverage'] bool Whether the group is full coverage;
98 * * if true, this means that checking every item in the group means no
99 * * changes list entries are filtered out.
100 * * $groupDefinition['queryCallable'] callable Callable accepting parameters:
101 * * string $specialPageClassName Class name of current special page
102 * * IContextSource $context Context, for e.g. user
103 * * IDatabase $dbr Database, for addQuotes, makeList, and similar
104 * * array &$tables Array of tables; see IDatabase::select $table
105 * * array &$fields Array of fields; see IDatabase::select $vars
106 * * array &$conds Array of conditions; see IDatabase::select $conds
107 * * array &$query_options Array of query options; see IDatabase::select $options
108 * * array &$join_conds Array of join conditions; see IDatabase::select $join_conds
109 * * array $selectedValues The allowed and requested values, lower-cased and sorted
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' );
132 public function isPerGroupRequestParameter() {
137 * Sets default of filter group.
139 * @param string $defaultValue
141 public function setDefault( $defaultValue ) {
142 $this->defaultValue
= $defaultValue;
146 * Gets default of filter group
148 * @return string $defaultValue
150 public function getDefault() {
151 return $this->defaultValue
;
157 protected function createFilter( array $filterDefinition ) {
158 return new ChangesListStringOptionsFilter( $filterDefinition );
162 * Registers a filter in this group
164 * @param ChangesListStringOptionsFilter $filter ChangesListStringOptionsFilter
166 public function registerFilter( ChangesListStringOptionsFilter
$filter ) {
167 $this->filters
[$filter->getName()] = $filter;
171 * Modifies the query to include the filter group.
173 * The modification is only done if the filter group is in effect. This means that
174 * one or more valid and allowed filters were selected.
176 * @param IDatabase $dbr Database, for addQuotes, makeList, and similar
177 * @param ChangesListSpecialPage $specialPage Current special page
178 * @param array &$tables Array of tables; see IDatabase::select $table
179 * @param array &$fields Array of fields; see IDatabase::select $vars
180 * @param array &$conds Array of conditions; see IDatabase::select $conds
181 * @param array &$query_options Array of query options; see IDatabase::select $options
182 * @param array &$join_conds Array of join conditions; see IDatabase::select $join_conds
183 * @param string $value URL parameter value
185 public function modifyQuery( IDatabase
$dbr, ChangesListSpecialPage
$specialPage,
186 &$tables, &$fields, &$conds, &$query_options, &$join_conds, $value ) {
188 $allowedFilterNames = [];
189 foreach ( $this->filters
as $filter ) {
190 $allowedFilterNames[] = $filter->getName();
193 if ( $value === self
::ALL
) {
194 $selectedValues = $allowedFilterNames;
196 $selectedValues = explode( self
::SEPARATOR
, strtolower( $value ) );
198 // remove values that are not recognized or not currently allowed
199 $selectedValues = array_intersect(
205 // If there are now no values, because all are disallowed or invalid (also,
206 // the user may not have selected any), this is a no-op.
208 // If everything is unchecked, the group always has no effect, regardless
210 if ( count( $selectedValues ) === 0 ) {
214 sort( $selectedValues );
216 call_user_func_array(
217 $this->queryCallable
,
219 get_class( $specialPage ),
220 $specialPage->getContext(),
235 public function getJsData() {
236 $output = parent
::getJsData();
238 $output['separator'] = self
::SEPARATOR
;
239 $output['default'] = $this->getDefault();