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"
11 * - Required list of columns in the matrix.
13 * - Required list of rows in the matrix.
15 * - Accepts array of column-row tags to be displayed as enabled but unavailable to change
17 * - Accepts array of column-row tags to be displayed as disabled but unavailable to change.
19 * - Optional array mapping row label to tooltip content
21 * - Optional CSS class used on tooltip container span. Defaults to mw-icon-question.
23 class HTMLCheckMatrix
extends HTMLFormField
implements HTMLNestedFilterable
{
25 static private $requiredParams = array(
26 // Required by underlying HTMLFormField
28 // Required by HTMLCheckMatrix
33 public function __construct( $params ) {
34 $missing = array_diff( self
::$requiredParams, array_keys( $params ) );
36 throw new HTMLFormFieldRequiredOptionsException( $this, $missing );
38 parent
::__construct( $params );
41 function validate( $value, $alldata ) {
42 $rows = $this->mParams
[ 'rows' ];
43 $columns = $this->mParams
[ 'columns' ];
45 // Make sure user-defined validation callback is run
46 $p = parent
::validate( $value, $alldata );
51 // Make sure submitted value is an array
52 if ( ! is_array( $value ) ) {
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;
64 $validValues = array_intersect( $value, $validOptions );
65 if ( count( $validValues ) == count( $value ) ) {
68 return $this->msg( 'htmlform-select-badoption' )->parse();
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.
78 * @param array $value of the options that should be checked
82 function getInputHTML( $value ) {
86 $rows = $this->mParams
[ 'rows' ];
87 $columns = $this->mParams
[ 'columns' ];
89 // If the disabled param is set, disable all the options
90 if ( ! empty( $this->mParams
[ 'disabled' ] ) ) {
91 $attribs[ 'disabled' ] = 'disabled';
94 // Build the column headers
95 $headerContents = Html
::rawElement( 'td', array(), ' ' );
96 foreach ( $columns as $columnLabel => $columnTag ) {
97 $headerContents .= Html
::rawElement( 'td', array(), $columnLabel );
99 $tableContents .= Html
::rawElement( 'tr', array(), "\n$headerContents\n" );
101 $tooltipClass = 'mw-icon-question';
102 if ( isset( $this->mParams
[ 'tooltip-class' ] ) ) {
103 $tooltipClass = $this->mParams
[ 'tooltip-class' ];
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 ],
114 $rowLabel .= ' ' . Html
::element( 'span', $tooltipAttribs, '' );
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",
124 $checked = in_array( $thisTag, (array)$value, true );
125 if ( $this->isTagForcedOff( $thisTag ) ) {
127 $thisAttribs[ 'disabled' ] = 1;
128 } elseif ( $this->isTagForcedOn( $thisTag ) ) {
130 $thisAttribs[ 'disabled' ] = 1;
132 $rowContents .= Html
::rawElement( 'td', array(), Xml
::check( "{$this->mName}[]", $checked, $attribs +
$thisAttribs ) );
134 $tableContents .= Html
::rawElement( 'tr', array(), "\n$rowContents\n" );
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";
143 protected function isTagForcedOff( $tag ) {
144 return isset( $this->mParams
[ 'force-options-off' ] ) && in_array( $tag, $this->mParams
[ 'force-options-off' ] );
147 protected function isTagForcedOn( $tag ) {
148 return isset( $this->mParams
[ 'force-options-on' ] ) && in_array( $tag, $this->mParams
[ 'force-options-on' ] );
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".
158 * @param string $value the value to set the input to
160 * @return String complete HTML table row
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 );
169 $label = $this->getLabelHtml( $cellAttributes );
171 $field = Html
::rawElement( 'td', array( 'class' => 'mw-input' ) +
$cellAttributes, $inputHtml . "\n$errors" );
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 );
176 return $html . $helptext;
180 * @param $request WebRequest
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() );
191 // That's ok, the user has not yet submitted the form, so show the defaults
192 return $this->getDefault();
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
200 return $request->getArray( $this->mName
, array() );
204 function getDefault() {
205 if ( isset( $this->mDefault
) ) {
206 return $this->mDefault
;
212 function filterDataForSubmit( $data ) {
213 $columns = HTMLFormField
::flattenOptions( $this->mParams
[ 'columns' ] );
214 $rows = HTMLFormField
::flattenOptions( $this->mParams
[ 'rows' ] );
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;
225 $res[ $thisTag ] = in_array( $thisTag, $data );