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