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 = $config['name'] ?? null;
  49                 $this->id = $config['id'] ?? null;
  50
  51                 // Properties
  52                 $this->rows = $config['rows'] ?? [];
  53                 $this->columns = $config['columns'] ?? [];
  54                 $this->tooltips = $config['tooltips'] ?? [];
  55
  56                 $this->values = $config['values'] ?? [];
  57
  58                 $this->forcedOn = $config['forcedOn'] ?? [];
  59                 $this->forcedOff = $config['forcedOff'] ?? [];
  60
  61                 // Build the table
  62                 $table = new \OOUI\Tag( 'table' );
  63                 $tr = new \OOUI\Tag( 'tr' );
  64                 // Build the header
  65                 $tr->appendContent( $this->getCellTag( "\u{00A0}" ) );
  66                 foreach ( $this->columns as $columnLabel => $columnTag ) {
  67                         $tr->appendContent(
  68                                 $this->getCellTag( $columnLabel )
  69                         );
  70                 }
  71                 $table->appendContent( $tr );
  72
  73                 // Build the options matrix
  74                 foreach ( $this->rows as $rowLabel => $rowTag ) {
  75                         $table->appendContent(
  76                                 $this->getTableRow( $rowLabel, $rowTag )
  77                         );
  78                 }
  79
  80                 // Initialization
  81                 $this->addClasses( [ 'mw-widget-checkMatrixWidget' ] );
  82                 $this->appendContent( $table );
  83         }
  84
  85         /**
  86          * Get a formatted table row for the option, with
  87          * a checkbox widget.
  88          *
  89          * @param  string $label Row label
  90          * @param  string $tag   Row tag name
  91          * @return \OOUI\Tag The resulting table row
  92          */
  93         private function getTableRow( $label, $tag ) {
  94                 $row = new \OOUI\Tag( 'tr' );
  95                 $tooltip = $this->getTooltip( $label );
  96                 $labelFieldConfig = $tooltip ? [ 'help' => $tooltip ] : [];
  97                 // Build label cell
  98                 $labelField = new \OOUI\FieldLayout(
  99                         new \OOUI\Widget(), // Empty widget, since we don't have the checkboxes here
 100                         [
 101                                 'label' => $label,
 102                                 'align' => 'inline',
 103                         ] + $labelFieldConfig
 104                 );
 105                 $row->appendContent( $this->getCellTag( $labelField ) );
 106
 107                 // Build checkbox column cells
 108                 foreach ( $this->columns as $columnTag ) {
 109                         $thisTag = "$columnTag-$tag";
 110
 111                         // Construct a checkbox
 112                         $checkbox = new \OOUI\CheckboxInputWidget( [
 113                                 'value' => $thisTag,
 114                                 'name' => $this->name ? "{$this->name}[]" : null,
 115                                 'id' => $this->id ? "{$this->id}-$thisTag" : null,
 116                                 'selected' => $this->isTagChecked( $thisTag ),
 117                                 'disabled' => $this->isTagDisabled( $thisTag ),
 118                         ] );
 119
 120                         $row->appendContent( $this->getCellTag( $checkbox ) );
 121                 }
 122                 return $row;
 123         }
 124
 125         /**
 126          * Get an individual cell tag with requested content
 127          *
 128          * @param  string $content Content for the <td> cell
 129          * @return \OOUI\Tag Resulting cell
 130          */
 131         private function getCellTag( $content ) {
 132                 $cell = new \OOUI\Tag( 'td' );
 133                 $cell->appendContent( $content );
 134                 return $cell;
 135         }
 136
 137         /**
 138          * Check whether the given tag's checkbox should
 139          * be checked
 140          *
 141          * @param  string $tagName Tag name
 142          * @return boolean Tag should be checked
 143          */
 144         private function isTagChecked( $tagName ) {
 145                 // If the tag is in the value list
 146                 return in_array( $tagName, (array)$this->values, true ) ||
 147                         // Or if the tag is forced on
 148                         in_array( $tagName, (array)$this->forcedOn, true );
 149         }
 150
 151         /**
 152          * Check whether the given tag's checkbox should
 153          * be disabled
 154          *
 155          * @param  string $tagName Tag name
 156          * @return boolean Tag should be disabled
 157          */
 158         private function isTagDisabled( $tagName ) {
 159                 return (
 160                         // If the entire widget is disabled
 161                         $this->isDisabled() ||
 162                         // If the tag is 'forced on' or 'forced off'
 163                         in_array( $tagName, (array)$this->forcedOn, true ) ||
 164                         in_array( $tagName, (array)$this->forcedOff, true )
 165                 );
 166         }
 167
 168         /**
 169          * Get the tooltip help associated with this row
 170          *
 171          * @param  string $label Label name
 172          * @return string Tooltip. Null if none is available.
 173          */
 174         private function getTooltip( $label ) {
 175                 return $this->tooltips[ $label ] ?? null;
 176         }
 177
 178         protected function getJavaScriptClassName() {
 179                 return 'mw.widgets.CheckMatrixWidget';
 180         }
 181
 182         public function getConfig( &$config ) {
 183                 $config += [
 184                         'name' => $this->name,
 185                         'id' => $this->id,
 186                         'rows' => $this->rows,
 187                         'columns' => $this->columns,
 188                         'tooltips' => $this->tooltips,
 189                         'forcedOff' => $this->forcedOff,
 190                         'forcedOn' => $this->forcedOn,
 191                         'values' => $this->values,
 192                 ];
 193                 return parent::getConfig( $config );
 194         }
 195 }