includes/htmlform/HTMLCheckMatrix.php

   1 <?php
   2 /**
   3  * A checkbox matrix
   4  * Operates similarly to HTMLMultiSelectField, but instead of using an array of
   5  * options, uses an array of rows and an array of columns to dynamically
   6  * construct a matrix of options. The tags used to identify a particular cell
   7  * are of the form "columnName-rowName"
   8  *
   9  * Options:
  10  *   - columns
  11  *     - Required list of columns in the matrix.
  12  *   - rows
  13  *     - Required list of rows in the matrix.
  14  *   - force-options-on
  15  *     - Accepts array of column-row tags to be displayed as enabled but unavailable to change
  16  *   - force-options-off
  17  *     - Accepts array of column-row tags to be displayed as disabled but unavailable to change.
  18  *   - tooltips
  19  *     - Optional array mapping row label to tooltip content
  20  *   - tooltip-class
  21  *     - Optional CSS class used on tooltip container span. Defaults to mw-icon-question.
  22  */
  23 class HTMLCheckMatrix extends HTMLFormField implements HTMLNestedFilterable {
  24
  25         static private $requiredParams = array(
  26                 // Required by underlying HTMLFormField
  27                 'fieldname',
  28                 // Required by HTMLCheckMatrix
  29                 'rows',
  30                 'columns'
  31         );
  32
  33         public function __construct( $params ) {
  34                 $missing = array_diff( self::$requiredParams, array_keys( $params ) );
  35                 if ( $missing ) {
  36                         throw new HTMLFormFieldRequiredOptionsException( $this, $missing );
  37                 }
  38                 parent::__construct( $params );
  39         }
  40
  41         function validate( $value, $alldata ) {
  42                 $rows = $this->mParams[ 'rows' ];
  43                 $columns = $this->mParams[ 'columns' ];
  44
  45                 // Make sure user-defined validation callback is run
  46                 $p = parent::validate( $value, $alldata );
  47                 if ( $p !== true ) {
  48                         return $p;
  49                 }
  50
  51                 // Make sure submitted value is an array
  52                 if ( ! is_array( $value ) ) {
  53                         return false;
  54                 }
  55
  56                 // If all options are valid, array_intersect of the valid options
  57                 // and the provided options will return the provided options.
  58                 $validOptions = array();
  59                 foreach ( $rows as $rowTag ) {
  60                         foreach ( $columns as $columnTag ) {
  61                                 $validOptions[ ] = $columnTag . '-' . $rowTag;
  62                         }
  63                 }
  64                 $validValues = array_intersect( $value, $validOptions );
  65                 if ( count( $validValues ) == count( $value ) ) {
  66                         return true;
  67                 } else {
  68                         return $this->msg( 'htmlform-select-badoption' )->parse();
  69                 }
  70         }
  71
  72         /**
  73          * Build a table containing a matrix of checkbox options.
  74          * The value of each option is a combination of the row tag and column tag.
  75          * mParams['rows'] is an array with row labels as keys and row tags as values.
  76          * mParams['columns'] is an array with column labels as keys and column tags as values.
  77          *
  78          * @param array $value of the options that should be checked
  79          *
  80          * @return String
  81          */
  82         function getInputHTML( $value ) {
  83                 $html = '';
  84                 $tableContents = '';
  85                 $attribs = array();
  86                 $rows = $this->mParams[ 'rows' ];
  87                 $columns = $this->mParams[ 'columns' ];
  88
  89                 // If the disabled param is set, disable all the options
  90                 if ( ! empty( $this->mParams[ 'disabled' ] ) ) {
  91                         $attribs[ 'disabled' ] = 'disabled';
  92                 }
  93
  94                 // Build the column headers
  95                 $headerContents = Html::rawElement( 'td', array(), '&#160;' );
  96                 foreach ( $columns as $columnLabel => $columnTag ) {
  97                         $headerContents .= Html::rawElement( 'td', array(), $columnLabel );
  98                 }
  99                 $tableContents .= Html::rawElement( 'tr', array(), "\n$headerContents\n" );
 100
 101                 $tooltipClass = 'mw-icon-question';
 102                 if ( isset( $this->mParams[ 'tooltip-class' ] ) ) {
 103                         $tooltipClass = $this->mParams[ 'tooltip-class' ];
 104                 }
 105
 106                 // Build the options matrix
 107                 foreach ( $rows as $rowLabel => $rowTag ) {
 108                         // Append tooltip if configured
 109                         if ( isset( $this->mParams[ 'tooltips' ][ $rowLabel ] ) ) {
 110                                 $tooltipAttribs = array(
 111                                         'class' => "mw-htmlform-tooltip $tooltipClass",
 112                                         'title' => $this->mParams[ 'tooltips' ][ $rowLabel ],
 113                                 );
 114                                 $rowLabel .= ' ' . Html::element( 'span', $tooltipAttribs, '' );
 115                         }
 116                         $rowContents = Html::rawElement( 'td', array(), $rowLabel );
 117                         foreach ( $columns as $columnTag ) {
 118                                 $thisTag = "$columnTag-$rowTag";
 119                                 // Construct the checkbox
 120                                 $thisAttribs = array(
 121                                         'id' => "{$this->mID}-$thisTag",
 122                                         'value' => $thisTag,
 123                                 );
 124                                 $checked = in_array( $thisTag, (array)$value, true );
 125                                 if ( $this->isTagForcedOff( $thisTag ) ) {
 126                                         $checked = false;
 127                                         $thisAttribs[ 'disabled' ] = 1;
 128                                 } elseif ( $this->isTagForcedOn( $thisTag ) ) {
 129                                         $checked = true;
 130                                         $thisAttribs[ 'disabled' ] = 1;
 131                                 }
 132                                 $rowContents .= Html::rawElement( 'td', array(), Xml::check( "{$this->mName}[]", $checked, $attribs + $thisAttribs ) );
 133                         }
 134                         $tableContents .= Html::rawElement( 'tr', array(), "\n$rowContents\n" );
 135                 }
 136
 137                 // Put it all in a table
 138                 $html .= Html::rawElement( 'table', array( 'class' => 'mw-htmlform-matrix' ), Html::rawElement( 'tbody', array(), "\n$tableContents\n" ) ) . "\n";
 139
 140                 return $html;
 141         }
 142
 143         protected function isTagForcedOff( $tag ) {
 144                 return isset( $this->mParams[ 'force-options-off' ] ) && in_array( $tag, $this->mParams[ 'force-options-off' ] );
 145         }
 146
 147         protected function isTagForcedOn( $tag ) {
 148                 return isset( $this->mParams[ 'force-options-on' ] ) && in_array( $tag, $this->mParams[ 'force-options-on' ] );
 149         }
 150
 151         /**
 152          * Get the complete table row for the input, including help text,
 153          * labels, and whatever.
 154          * We override this function since the label should always be on a separate
 155          * line above the options in the case of a checkbox matrix, i.e. it's always
 156          * a "vertical-label".
 157          *
 158          * @param string $value the value to set the input to
 159          *
 160          * @return String complete HTML table row
 161          */
 162         function getTableRow( $value ) {
 163                 list( $errors, $errorClass ) = $this->getErrorsAndErrorClass( $value );
 164                 $inputHtml = $this->getInputHTML( $value );
 165                 $fieldType = get_class( $this );
 166                 $helptext = $this->getHelpTextHtmlTable( $this->getHelpText() );
 167                 $cellAttributes = array( 'colspan' => 2 );
 168
 169                 $label = $this->getLabelHtml( $cellAttributes );
 170
 171                 $field = Html::rawElement( 'td', array( 'class' => 'mw-input' ) + $cellAttributes, $inputHtml . "\n$errors" );
 172
 173                 $html = Html::rawElement( 'tr', array( 'class' => 'mw-htmlform-vertical-label' ), $label );
 174                 $html .= Html::rawElement( 'tr', array( 'class' => "mw-htmlform-field-$fieldType {$this->mClass} $errorClass" ), $field );
 175
 176                 return $html . $helptext;
 177         }
 178
 179         /**
 180          * @param $request WebRequest
 181          *
 182          * @return Array
 183          */
 184         function loadDataFromRequest( $request ) {
 185                 if ( $this->mParent->getMethod() == 'post' ) {
 186                         if ( $request->wasPosted() ) {
 187                                 // Checkboxes are not added to the request arrays if they're not checked,
 188                                 // so it's perfectly possible for there not to be an entry at all
 189                                 return $request->getArray( $this->mName, array() );
 190                         } else {
 191                                 // That's ok, the user has not yet submitted the form, so show the defaults
 192                                 return $this->getDefault();
 193                         }
 194                 } else {
 195                         // This is the impossible case: if we look at $_GET and see no data for our
 196                         // field, is it because the user has not yet submitted the form, or that they
 197                         // have submitted it with all the options unchecked. We will have to assume the
 198                         // latter, which basically means that you can't specify 'positive' defaults
 199                         // for GET forms.
 200                         return $request->getArray( $this->mName, array() );
 201                 }
 202         }
 203
 204         function getDefault() {
 205                 if ( isset( $this->mDefault ) ) {
 206                         return $this->mDefault;
 207                 } else {
 208                         return array();
 209                 }
 210         }
 211
 212         function filterDataForSubmit( $data ) {
 213                 $columns = HTMLFormField::flattenOptions( $this->mParams[ 'columns' ] );
 214                 $rows = HTMLFormField::flattenOptions( $this->mParams[ 'rows' ] );
 215                 $res = array();
 216                 foreach ( $columns as $column ) {
 217                         foreach ( $rows as $row ) {
 218                                 // Make sure option hasn't been forced
 219                                 $thisTag = "$column-$row";
 220                                 if ( $this->isTagForcedOff( $thisTag ) ) {
 221                                         $res[ $thisTag ] = false;
 222                                 } elseif ( $this->isTagForcedOn( $thisTag ) ) {
 223                                         $res[ $thisTag ] = true;
 224                                 } else {
 225                                         $res[ $thisTag ] = in_array( $thisTag, $data );
 226                                 }
 227                         }
 228                 }
 229
 230                 return $res;
 231         }
 232 }