includes/widget/CheckMatrixWidget.php

   1 <?php
   2
   3 namespace MediaWiki\Widget;
   4
   5 /**
   6  * Check matrix widget. Displays a matrix of checkboxes for given options
   7  *
   8  * @copyright 2018 MediaWiki Widgets Team and others; see AUTHORS.txt
   9  * @license MIT
  10  */
  11 class CheckMatrixWidget extends \OOUI\Widget {
  12
  13         protected $name = '';
  14         protected $columns = [];
  15         protected $rows = [];
  16         protected $tooltips = [];
  17         protected $values = [];
  18         protected $forcedOn = [];
  19         protected $forcedOff = [];
  20
  21         /**
  22          * CheckMatrixWidget constructor
  23          *
  24          * Operates similarly to MultiSelectWidget, but instead of using an array of
  25          * options, uses an array of rows and an array of columns to dynamically
  26          * construct a matrix of options. The tags used to identify a particular cell
  27          * are of the form "columnName-rowName"
  28          *
  29          * @param array $config Configuration array with the following options:
  30          *   - columns
  31          *     - Required list of columns in the matrix.
  32          *   - rows
  33          *     - Required list of rows in the matrix.
  34          *   - force-options-on
  35          *     - Accepts array of column-row tags to be displayed as enabled but unavailable to change
  36          *   - force-options-off
  37          *     - Accepts array of column-row tags to be displayed as disabled but unavailable to change.
  38          *   - tooltips
  39          *     - Optional array mapping row label to tooltip content
  40          *   - tooltip-class
  41          *     - Optional CSS class used on tooltip container span. Defaults to mw-icon-question.
  42          */
  43         public function __construct( array $config = [] ) {
  44                 // Configuration initialization
  45
  46                 parent::__construct( $config );
  47
  48                 $this->name = isset( $config['name'] ) ?
  49                         $config[ 'name' ] : null;
  50                 $this->id = isset( $config['id'] ) ?
  51                         $config['id'] : null;
  52
  53                 // Properties
  54                 $this->rows = isset( $config['rows'] ) ?
  55                         $config['rows'] : [];
  56                 $this->columns = isset( $config['columns'] ) ?
  57                         $config['columns'] : [];
  58                 $this->tooltips = isset( $config['tooltips'] ) ?
  59                         $config['tooltips'] : [];
  60
  61                 $this->values = isset( $config['values'] ) ?
  62                         $config['values'] : [];
  63
  64                 $this->forcedOn = isset( $config['forcedOn'] ) ?
  65                         $config['forcedOn'] : [];
  66                 $this->forcedOff = isset( $config['forcedOff'] ) ?
  67                         $config['forcedOff'] : [];
  68
  69                 // Build the table
  70                 $table = new \OOUI\Tag( 'table' );
  71                 $tr = new \OOUI\Tag( 'tr' );
  72                 // Build the header
  73                 $tr->appendContent( $this->getCellTag( "\u{00A0}" ) );
  74                 foreach ( $this->columns as $columnLabel => $columnTag ) {
  75                         $tr->appendContent(
  76                                 $this->getCellTag( $columnLabel )
  77                         );
  78                 }
  79                 $table->appendContent( $tr );
  80
  81                 // Build the options matrix
  82                 foreach ( $this->rows as $rowLabel => $rowTag ) {
  83                         $table->appendContent(
  84                                 $this->getTableRow( $rowLabel, $rowTag )
  85                         );
  86                 }
  87
  88                 // Initialization
  89                 $this->addClasses( [ 'mw-widget-checkMatrixWidget' ] );
  90                 $this->appendContent( $table );
  91         }
  92
  93         /**
  94          * Get a formatted table row for the option, with
  95          * a checkbox widget.
  96          *
  97          * @param  string $label Row label
  98          * @param  string $tag   Row tag name
  99          * @return \OOUI\Tag The resulting table row
 100          */
 101         private function getTableRow( $label, $tag ) {
 102                 $row = new \OOUI\Tag( 'tr' );
 103                 $tooltip = $this->getTooltip( $label );
 104                 $labelFieldConfig = $tooltip ? [ 'help' => $tooltip ] : [];
 105                 // Build label cell
 106                 $labelField = new \OOUI\FieldLayout(
 107                         new \OOUI\Widget(), // Empty widget, since we don't have the checkboxes here
 108                         [
 109                                 'label' => $label,
 110                                 'align' => 'inline',
 111                         ] + $labelFieldConfig
 112                 );
 113                 $row->appendContent( $this->getCellTag( $labelField ) );
 114
 115                 // Build checkbox column cells
 116                 foreach ( $this->columns as $columnTag ) {
 117                         $thisTag = "$columnTag-$tag";
 118
 119                         // Construct a checkbox
 120                         $checkbox = new \OOUI\CheckboxInputWidget( [
 121                                 'value' => $thisTag,
 122                                 'name' => $this->name ? "{$this->name}[]" : null,
 123                                 'id' => $this->id ? "{$this->id}-$thisTag" : null,
 124                                 'selected' => $this->isTagChecked( $thisTag ),
 125                                 'disabled' => $this->isTagDisabled( $thisTag ),
 126                         ] );
 127
 128                         $row->appendContent( $this->getCellTag( $checkbox ) );
 129                 }
 130                 return $row;
 131         }
 132
 133         /**
 134          * Get an individual cell tag with requested content
 135          *
 136          * @param  string $content Content for the <td> cell
 137          * @return \OOUI\Tag Resulting cell
 138          */
 139         private function getCellTag( $content ) {
 140                 $cell = new \OOUI\Tag( 'td' );
 141                 $cell->appendContent( $content );
 142                 return $cell;
 143         }
 144
 145         /**
 146          * Check whether the given tag's checkbox should
 147          * be checked
 148          *
 149          * @param  string $tagName Tag name
 150          * @return boolean Tag should be checked
 151          */
 152         private function isTagChecked( $tagName ) {
 153                 // If the tag is in the value list
 154                 return in_array( $tagName, (array)$this->values, true ) ||
 155                         // Or if the tag is forced on
 156                         in_array( $tagName, (array)$this->forcedOn, true );
 157         }
 158
 159         /**
 160          * Check whether the given tag's checkbox should
 161          * be disabled
 162          *
 163          * @param  string $tagName Tag name
 164          * @return boolean Tag should be disabled
 165          */
 166         private function isTagDisabled( $tagName ) {
 167                 return (
 168                         // If the entire widget is disabled
 169                         $this->isDisabled() ||
 170                         // If the tag is 'forced on' or 'forced off'
 171                         in_array( $tagName, (array)$this->forcedOn, true ) ||
 172                         in_array( $tagName, (array)$this->forcedOff, true )
 173                 );
 174         }
 175
 176         /**
 177          * Get the tooltip help associated with this row
 178          *
 179          * @param  string $label Label name
 180          * @return string Tooltip. Null if none is available.
 181          */
 182         private function getTooltip( $label ) {
 183                 return isset( $this->tooltips[ $label ] ) ?
 184                         $this->tooltips[ $label ] : null;
 185         }
 186
 187         protected function getJavaScriptClassName() {
 188                 return 'mw.widgets.CheckMatrixWidget';
 189         }
 190
 191         public function getConfig( &$config ) {
 192                 $config += [
 193                         'name' => $this->name,
 194                         'id' => $this->id,
 195                         'rows' => $this->rows,
 196                         'columns' => $this->columns,
 197                         'tooltips' => $this->tooltips,
 198                         'forcedOff' => $this->forcedOff,
 199                         'forcedOn' => $this->forcedOn,
 200                         'values' => $this->values,
 201                 ];
 202                 return parent::getConfig( $config );
 203         }
 204 }