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