includes/htmlform/fields/HTMLCheckMatrix.php

   1 <?php
   2
   3 /**
   4  * A checkbox matrix
   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"
   9  *
  10  * Options:
  11  *   - columns
  12  *     - Required associative array mapping column labels (as HTML) to their tags.
  13  *   - rows
  14  *     - Required associative array mapping row labels (as HTML) to their tags.
  15  *   - force-options-on
  16  *     - Array of column-row tags to be displayed as enabled but unavailable to change.
  17  *   - force-options-off
  18  *     - Array of column-row tags to be displayed as disabled but unavailable to change.
  19  *   - tooltips
  20  *     - Optional associative array mapping row labels to tooltips (as text, will be escaped).
  21  *   - tooltip-class
  22  *     - Optional CSS class used on tooltip container span. Defaults to mw-icon-question.
  23  *       Not used by OOUI form fields.
  24  */
  25 class HTMLCheckMatrix extends HTMLFormField implements HTMLNestedFilterable {
  26         private static $requiredParams = [
  27                 // Required by underlying HTMLFormField
  28                 'fieldname',
  29                 // Required by HTMLCheckMatrix
  30                 'rows',
  31                 'columns'
  32         ];
  33
  34         public function __construct( $params ) {
  35                 $missing = array_diff( self::$requiredParams, array_keys( $params ) );
  36                 if ( $missing ) {
  37                         throw new HTMLFormFieldRequiredOptionsException( $this, $missing );
  38                 }
  39                 parent::__construct( $params );
  40         }
  41
  42         public function validate( $value, $alldata ) {
  43                 $rows = $this->mParams['rows'];
  44                 $columns = $this->mParams['columns'];
  45
  46                 // Make sure user-defined validation callback is run
  47                 $p = parent::validate( $value, $alldata );
  48                 if ( $p !== true ) {
  49                         return $p;
  50                 }
  51
  52                 // Make sure submitted value is an array
  53                 if ( !is_array( $value ) ) {
  54                         return false;
  55                 }
  56
  57                 // If all options are valid, array_intersect of the valid options
  58                 // and the provided options will return the provided options.
  59                 $validOptions = [];
  60                 foreach ( $rows as $rowTag ) {
  61                         foreach ( $columns as $columnTag ) {
  62                                 $validOptions[] = $columnTag . '-' . $rowTag;
  63                         }
  64                 }
  65                 $validValues = array_intersect( $value, $validOptions );
  66                 if ( count( $validValues ) == count( $value ) ) {
  67                         return true;
  68                 } else {
  69                         return $this->msg( 'htmlform-select-badoption' );
  70                 }
  71         }
  72
  73         /**
  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.
  78          *
  79          * @param array $value Array of the options that should be checked
  80          * @suppress PhanParamSignatureMismatch
  81          *
  82          * @return string
  83          */
  84         public function getInputHTML( $value ) {
  85                 $html = '';
  86                 $tableContents = '';
  87                 $rows = $this->mParams['rows'];
  88                 $columns = $this->mParams['columns'];
  89
  90                 $attribs = $this->getAttributes( [ 'disabled', 'tabindex' ] );
  91
  92                 // Build the column headers
  93                 $headerContents = Html::rawElement( 'td', [], "\u{00A0}" );
  94                 foreach ( $columns as $columnLabel => $columnTag ) {
  95                         $headerContents .= Html::rawElement( 'th', [], $columnLabel );
  96                 }
  97                 $thead = Html::rawElement( 'tr', [], "\n$headerContents\n" );
  98                 $tableContents .= Html::rawElement( 'thead', [], "\n$thead\n" );
  99
 100                 $tooltipClass = 'mw-icon-question';
 101                 if ( isset( $this->mParams['tooltip-class'] ) ) {
 102                         $tooltipClass = $this->mParams['tooltip-class'];
 103                 }
 104
 105                 // Build the options matrix
 106                 foreach ( $rows as $rowLabel => $rowTag ) {
 107                         // Append tooltip if configured
 108                         if ( isset( $this->mParams['tooltips'][$rowLabel] ) ) {
 109                                 $tooltipAttribs = [
 110                                         'class' => "mw-htmlform-tooltip $tooltipClass",
 111                                         'title' => $this->mParams['tooltips'][$rowLabel],
 112                                         'aria-label' => $this->mParams['tooltips'][$rowLabel]
 113                                 ];
 114                                 $rowLabel .= ' ' . Html::element( 'span', $tooltipAttribs, '' );
 115                         }
 116                         $rowContents = Html::rawElement( 'td', [], $rowLabel );
 117                         foreach ( $columns as $columnTag ) {
 118                                 $thisTag = "$columnTag-$rowTag";
 119                                 // Construct the checkbox
 120                                 $thisAttribs = [
 121                                         'id' => "{$this->mID}-$thisTag",
 122                                         'value' => $thisTag,
 123                                 ];
 124                                 $checked = in_array( $thisTag, (array)$value, true );
 125                                 if ( $this->isTagForcedOff( $thisTag ) ) {
 126                                         $checked = false;
 127                                         $thisAttribs['disabled'] = 1;
 128                                         $thisAttribs['class'] = 'checkmatrix-forced checkmatrix-forced-off';
 129                                 } elseif ( $this->isTagForcedOn( $thisTag ) ) {
 130                                         $checked = true;
 131                                         $thisAttribs['disabled'] = 1;
 132                                         $thisAttribs['class'] = 'checkmatrix-forced checkmatrix-forced-on';
 133                                 }
 134
 135                                 $checkbox = $this->getOneCheckboxHTML( $checked, $attribs + $thisAttribs );
 136
 137                                 $rowContents .= Html::rawElement(
 138                                         'td',
 139                                         [],
 140                                         $checkbox
 141                                 );
 142                         }
 143                         $tableContents .= Html::rawElement( 'tr', [], "\n$rowContents\n" );
 144                 }
 145
 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";
 150
 151                 return $html;
 152         }
 153
 154         public function getInputOOUI( $value ) {
 155                 $attribs = $this->getAttributes( [ 'disabled', 'tabindex' ] );
 156
 157                 return new MediaWiki\Widget\CheckMatrixWidget(
 158                         [
 159                                 'name' => $this->mName,
 160                                 'infusable' => true,
 161                                 'id' => $this->mID,
 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'] ?? [],
 167                                 'values' => $value,
 168                         ] + OOUI\Element::configFromHtmlAttributes( $attribs )
 169                 );
 170         }
 171
 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' ] ) .
 176                                 $checkbox .
 177                                 Html::element( 'label', [ 'for' => $attribs['id'] ] ) .
 178                                 Html::closeElement( 'div' );
 179                 }
 180                 return $checkbox;
 181         }
 182
 183         protected function isTagForcedOff( $tag ) {
 184                 return isset( $this->mParams['force-options-off'] )
 185                         && in_array( $tag, $this->mParams['force-options-off'] );
 186         }
 187
 188         protected function isTagForcedOn( $tag ) {
 189                 return isset( $this->mParams['force-options-on'] )
 190                         && in_array( $tag, $this->mParams['force-options-on'] );
 191         }
 192
 193         /**
 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".
 199          *
 200          * @param string|array $value The value to set the input to
 201          *
 202          * @return string Complete HTML table row
 203          */
 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 ];
 210
 211                 $hideClass = '';
 212                 $hideAttributes = [];
 213                 if ( $this->mHideIf ) {
 214                         $hideAttributes['data-hide-if'] = FormatJson::encode( $this->mHideIf );
 215                         $hideClass = 'mw-htmlform-hide-if';
 216                 }
 217
 218                 $label = $this->getLabelHtml( $cellAttributes );
 219
 220                 $field = Html::rawElement(
 221                         'td',
 222                         [ 'class' => 'mw-input' ] + $cellAttributes,
 223                         $inputHtml . "\n$errors"
 224                 );
 225
 226                 $html = Html::rawElement( 'tr',
 227                         [ 'class' => "mw-htmlform-vertical-label $hideClass" ] + $hideAttributes,
 228                         $label );
 229                 $html .= Html::rawElement( 'tr',
 230                         [ 'class' => "mw-htmlform-field-$fieldType {$this->mClass} $errorClass $hideClass" ] +
 231                                 $hideAttributes,
 232                         $field );
 233
 234                 return $html . $helptext;
 235         }
 236
 237         /**
 238          * @param WebRequest $request
 239          *
 240          * @return array
 241          */
 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, [] );
 247                 } else {
 248                         // That's ok, the user has not yet submitted the form, so show the defaults
 249                         return $this->getDefault();
 250                 }
 251         }
 252
 253         public function getDefault() {
 254                 return $this->mDefault ?? [];
 255         }
 256
 257         public function filterDataForSubmit( $data ) {
 258                 $columns = HTMLFormField::flattenOptions( $this->mParams['columns'] );
 259                 $rows = HTMLFormField::flattenOptions( $this->mParams['rows'] );
 260                 $res = [];
 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;
 269                                 } else {
 270                                         $res[$thisTag] = in_array( $thisTag, $data );
 271                                 }
 272                         }
 273                 }
 274
 275                 return $res;
 276         }
 277
 278         protected function getOOUIModules() {
 279                 return [ 'mediawiki.widgets.CheckMatrixWidget' ];
 280         }
 281
 282         protected function shouldInfuseOOUI() {
 283                 return true;
 284         }
 285 }