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