5 * Operates similarly to HTMLMultiSelectField, but instead of using an array of
6 * options, uses an array of rows and an array of columns to dynamically
7 * construct a matrix of options. The tags used to identify a particular cell
8 * are of the form "columnName-rowName"
12 * - Required associative array mapping column labels (as HTML) to their tags.
14 * - Required associative array mapping row labels (as HTML) to their tags.
16 * - Array of column-row tags to be displayed as enabled but unavailable to change.
18 * - Array of column-row tags to be displayed as disabled but unavailable to change.
20 * - Optional associative array mapping row labels to tooltips (as text, will be escaped).
22 * - Optional CSS class used on tooltip container span. Defaults to mw-icon-question.
23 * Not used by OOUI form fields.
25 class HTMLCheckMatrix
extends HTMLFormField
implements HTMLNestedFilterable
{
26 private static $requiredParams = [
27 // Required by underlying HTMLFormField
29 // Required by HTMLCheckMatrix
34 public function __construct( $params ) {
35 $missing = array_diff( self
::$requiredParams, array_keys( $params ) );
37 throw new HTMLFormFieldRequiredOptionsException( $this, $missing );
39 parent
::__construct( $params );
42 public function validate( $value, $alldata ) {
43 $rows = $this->mParams
['rows'];
44 $columns = $this->mParams
['columns'];
46 // Make sure user-defined validation callback is run
47 $p = parent
::validate( $value, $alldata );
52 // Make sure submitted value is an array
53 if ( !is_array( $value ) ) {
57 // If all options are valid, array_intersect of the valid options
58 // and the provided options will return the provided options.
60 foreach ( $rows as $rowTag ) {
61 foreach ( $columns as $columnTag ) {
62 $validOptions[] = $columnTag . '-' . $rowTag;
65 $validValues = array_intersect( $value, $validOptions );
66 if ( count( $validValues ) == count( $value ) ) {
69 return $this->msg( 'htmlform-select-badoption' );
74 * Build a table containing a matrix of checkbox options.
75 * The value of each option is a combination of the row tag and column tag.
76 * mParams['rows'] is an array with row labels as keys and row tags as values.
77 * mParams['columns'] is an array with column labels as keys and column tags as values.
79 * @param array $value Array of the options that should be checked
80 * @suppress PhanParamSignatureMismatch
84 public function getInputHTML( $value ) {
87 $rows = $this->mParams
['rows'];
88 $columns = $this->mParams
['columns'];
90 $attribs = $this->getAttributes( [ 'disabled', 'tabindex' ] );
92 // Build the column headers
93 $headerContents = Html
::rawElement( 'td', [], "\u{00A0}" );
94 foreach ( $columns as $columnLabel => $columnTag ) {
95 $headerContents .= Html
::rawElement( 'th', [], $columnLabel );
97 $thead = Html
::rawElement( 'tr', [], "\n$headerContents\n" );
98 $tableContents .= Html
::rawElement( 'thead', [], "\n$thead\n" );
100 $tooltipClass = 'mw-icon-question';
101 if ( isset( $this->mParams
['tooltip-class'] ) ) {
102 $tooltipClass = $this->mParams
['tooltip-class'];
105 // Build the options matrix
106 foreach ( $rows as $rowLabel => $rowTag ) {
107 // Append tooltip if configured
108 if ( isset( $this->mParams
['tooltips'][$rowLabel] ) ) {
110 'class' => "mw-htmlform-tooltip $tooltipClass",
111 'title' => $this->mParams
['tooltips'][$rowLabel],
112 'aria-label' => $this->mParams
['tooltips'][$rowLabel]
114 $rowLabel .= ' ' . Html
::element( 'span', $tooltipAttribs, '' );
116 $rowContents = Html
::rawElement( 'td', [], $rowLabel );
117 foreach ( $columns as $columnTag ) {
118 $thisTag = "$columnTag-$rowTag";
119 // Construct the checkbox
121 'id' => "{$this->mID}-$thisTag",
124 $checked = in_array( $thisTag, (array)$value, true );
125 if ( $this->isTagForcedOff( $thisTag ) ) {
127 $thisAttribs['disabled'] = 1;
128 $thisAttribs['class'] = 'checkmatrix-forced checkmatrix-forced-off';
129 } elseif ( $this->isTagForcedOn( $thisTag ) ) {
131 $thisAttribs['disabled'] = 1;
132 $thisAttribs['class'] = 'checkmatrix-forced checkmatrix-forced-on';
135 $checkbox = $this->getOneCheckboxHTML( $checked, $attribs +
$thisAttribs );
137 $rowContents .= Html
::rawElement(
143 $tableContents .= Html
::rawElement( 'tr', [], "\n$rowContents\n" );
146 // Put it all in a table
147 $html .= Html
::rawElement( 'table',
148 [ 'class' => 'mw-htmlform-matrix' ],
149 Html
::rawElement( 'tbody', [], "\n$tableContents\n" ) ) . "\n";
154 public function getInputOOUI( $value ) {
155 $attribs = $this->getAttributes( [ 'disabled', 'tabindex' ] );
157 return new MediaWiki\Widget\
CheckMatrixWidget(
159 'name' => $this->mName
,
162 'rows' => $this->mParams
['rows'],
163 'columns' => $this->mParams
['columns'],
164 'tooltips' => $this->mParams
['tooltips'] ??
[],
165 'forcedOff' => $this->mParams
['force-options-off'] ??
[],
166 'forcedOn' => $this->mParams
['force-options-on'] ??
[],
168 ] + OOUI\Element
::configFromHtmlAttributes( $attribs )
172 protected function getOneCheckboxHTML( $checked, $attribs ) {
173 $checkbox = Xml
::check( "{$this->mName}[]", $checked, $attribs );
174 if ( $this->mParent
->getConfig()->get( 'UseMediaWikiUIEverywhere' ) ) {
175 $checkbox = Html
::openElement( 'div', [ 'class' => 'mw-ui-checkbox' ] ) .
177 Html
::element( 'label', [ 'for' => $attribs['id'] ] ) .
178 Html
::closeElement( 'div' );
183 protected function isTagForcedOff( $tag ) {
184 return isset( $this->mParams
['force-options-off'] )
185 && in_array( $tag, $this->mParams
['force-options-off'] );
188 protected function isTagForcedOn( $tag ) {
189 return isset( $this->mParams
['force-options-on'] )
190 && in_array( $tag, $this->mParams
['force-options-on'] );
194 * Get the complete table row for the input, including help text,
195 * labels, and whatever.
196 * We override this function since the label should always be on a separate
197 * line above the options in the case of a checkbox matrix, i.e. it's always
198 * a "vertical-label".
200 * @param string|array $value The value to set the input to
202 * @return string Complete HTML table row
204 public function getTableRow( $value ) {
205 list( $errors, $errorClass ) = $this->getErrorsAndErrorClass( $value );
206 $inputHtml = $this->getInputHTML( $value );
207 $fieldType = static::class;
208 $helptext = $this->getHelpTextHtmlTable( $this->getHelpText() );
209 $cellAttributes = [ 'colspan' => 2 ];
212 $hideAttributes = [];
213 if ( $this->mHideIf
) {
214 $hideAttributes['data-hide-if'] = FormatJson
::encode( $this->mHideIf
);
215 $hideClass = 'mw-htmlform-hide-if';
218 $label = $this->getLabelHtml( $cellAttributes );
220 $field = Html
::rawElement(
222 [ 'class' => 'mw-input' ] +
$cellAttributes,
223 $inputHtml . "\n$errors"
226 $html = Html
::rawElement( 'tr',
227 [ 'class' => "mw-htmlform-vertical-label $hideClass" ] +
$hideAttributes,
229 $html .= Html
::rawElement( 'tr',
230 [ 'class' => "mw-htmlform-field-$fieldType {$this->mClass} $errorClass $hideClass" ] +
234 return $html . $helptext;
238 * @param WebRequest $request
242 public function loadDataFromRequest( $request ) {
243 if ( $this->isSubmitAttempt( $request ) ) {
244 // Checkboxes are just not added to the request arrays if they're not checked,
245 // so it's perfectly possible for there not to be an entry at all
246 return $request->getArray( $this->mName
, [] );
248 // That's ok, the user has not yet submitted the form, so show the defaults
249 return $this->getDefault();
253 public function getDefault() {
254 return $this->mDefault ??
[];
257 public function filterDataForSubmit( $data ) {
258 $columns = HTMLFormField
::flattenOptions( $this->mParams
['columns'] );
259 $rows = HTMLFormField
::flattenOptions( $this->mParams
['rows'] );
261 foreach ( $columns as $column ) {
262 foreach ( $rows as $row ) {
263 // Make sure option hasn't been forced
264 $thisTag = "$column-$row";
265 if ( $this->isTagForcedOff( $thisTag ) ) {
266 $res[$thisTag] = false;
267 } elseif ( $this->isTagForcedOn( $thisTag ) ) {
268 $res[$thisTag] = true;
270 $res[$thisTag] = in_array( $thisTag, $data );
278 protected function getOOUIModules() {
279 return [ 'mediawiki.widgets.CheckMatrixWidget' ];
282 protected function shouldInfuseOOUI() {