HTMLForm is a class for handling everything related to user interface forms. MediaWiki 1.16 and newer include HTMLForm in HTMLForm.php.

The HTMLForm tutorial shows basics of HTMLForm.

Parameters

edit

Precise specification for:

Parameter Type Description
type string Type of form content to create. For example: text, radio, or multiselect. These are mapped to specific subclasses in HTMLForm.

This roughly translates into the ‎<select> type attribute. If 'class' is not specified, this is used as a map through HTMLForm::$typeMappings to get the class name.

class string PHP Subclass to use for this form content. This accomplishes the same thing as the type parameter, but more directly. This is NOT the CSS class!
size integer Sets the length of text fields
maxlength integer Sets the maxlength of text fields
min integer The minimum amount for the value
max integer The maximum amount for the value
invert boolean Set inputs of type toggle to checked by default
options array The options to present in a multiselect, radio, or select form element. Maps raw text labels to values. Some field types support multi-level arrays. Overwrites 'options-message'.
rows array The rows to present in a checkmatrix form element or the number of rows shown for textarea form element
columns array The columns to present in a checkmatrix form element
force-options-off array Options to set unchecked and disabled in a checkmatrix form element
force-options-on array Options to set checked and enabled in a checkmatrix form element
section string Key for an i18n message to display as a section or subsection header. Subsections should make use of '/' character e.g. foo/bar/baz creates a preference 'baz' inside the section 'bar' which is inside the section 'foo'
label-message,

buttonlabel-message

string Key for an i18n message to display as a label for a form input/button. Message key or object for a message to use as the label. Can be an array of msg key and then parameters to the message.
label,

label-raw, buttonlabel

string Label for a form input/button. Overridden by label-message.
vertical-label boolean Set to true if you want the label to appear above the options rather than to the left of the options
id string ID attribute to assign to the input
cssclass string Class attribute to assign to the input
csshelpclass string CSS class used to style help text
validation-callback array Class and function to use for input validation. See HTMLFormField::validate()
filter-callback array Class and function to use for input filtering. It gives you the chance to massage the inputted value before it's processed. See HTMLFormField::filter()
help-message string Key for an i18n message to display directly below the form element. Overwrites 'help-messages' and 'help'. Can be an array of msg key and then parameters to the message.
help string Message to display directly below the form element to use as a help text.
tooltip string Key suffix for i18n messages to use for title and/or accesskey attributes (tooltip-YOURVALUE and accesskey-YOURVALUE)
placeholder string Value to use for the HTML5 placeholder attribute
placeholder-message string Key for an i18n message to display as a placeholder
disabled boolean Disable editing and submission of the form input
readonly boolean Disable editing of the form input
required boolean If true, the input cannot be left blank. It is passed through to the object, indicating that it is a required field.
name string Override the name of the input (default is wp{$fieldname}).

If you want a different name (eg one without the "wp" prefix), specify it here and it will be used without modification.

dir string Direction of the element.
'options-messages' array associative array mapping message keys to values. Some field types support multi-level arrays.

Overwrites 'options' and 'options-message'.

'options-message' array message key or object to be parsed to extract the list of options (like 'ipbreason-dropdown').
'help-messages' array array of message keys/objects. As above, each item can be an array of msg key and then parameters. Overwrites 'help'.
'help-inline' array Whether help text (defined using options above) will be shown inline after the input field, rather than in a popup.

Defaults to true. Only used by OOUI form fields.

'hide-if' array expression given as an array stating when the field should be hidden. The first array value has to be the expression's logic operator.

Suppo

[ 'NOT', array $expression ] To hide a field if a given expression is not true.

'==='

[ '===', string $fieldName, string $value ]

To hide a field if another field identified by $field has the value $value.

'!==' [ '!==', string $fieldName, string $value ]

Same as [ 'NOT', [ '===', $fieldName, $value ]

'OR', 'AND', 'NOR', 'NAND'

[ 'XXX', array $expression1, ..., array $expressionN ]

To hide a field if one or more (OR), all (AND), neither (NOR) or not all (NAND) given expressions are evaluated as true.


The expressions will be given to a JavaScript frontend module which will continually update the field's visibility.

nodata boolean if set (to any value, which casts to true), the data for this field will not be loaded from the actual request. Instead, always the default data is set as the value of this field.
default string (or array) Default value(s) for the field (not to be confused with $wgDefaultUserOptions ). Note extensions/skins adding preferences via hook must make use of UserGetDefaultOptions to set default value.

Example usage

edit

class SpecialTestForm

edit
<?php

class SpecialTestForm extends SpecialPage {
	public function __construct() {
		parent::__construct( 'TestForm' );
	}

	public function execute( $par ) {
		$this->getOutput()->setPageTitle( 'Test form' );

		$formDescriptor = [
			'myfield1' => [
				'section' => 'section1/subsection',
				'label-message' => 'testform-myfield1',
				'type' => 'text',
				'default' => 'Meep',
			],
			'myfield2' => [
				'section' => 'section1',
				'class' => 'HTMLTextField', // HTMLTextField same as type 'text'
				'label-message' => 'testform-myfield2',
			],
			'myfield3' => [
				'class' => 'HTMLTextField',
				'label' => 'Foo bar baz',
			],
			'myfield4' => [
				'class' => 'HTMLCheckField',
				'label' => 'This be a pirate checkbox',
				'default' => true,
			],
			'omgaselectbox' => [
				'class' => 'HTMLSelectField',
				'label' => 'Select an oooption',
				'options' => [
					'Pirates' => 'pirate',
					'Ninjas' => 'ninja',
					'Back to the NINJAR!' => 'ninjars',
				],
			],
			'omgmultiselect' => [
				'class' => 'HTMLMultiSelectField',
				'label' => 'Weapons to use',
				'options' => [
					'Cannons' => 'cannon',
					'Swords' => 'sword',
				],
				'default' => [ 'sword' ],
			],
			'radiolol' => [
				'class' => 'HTMLRadioField',
				'label' => 'Who do you like?',
				'options' => [
					'Pirates' => 'pirates',
					'Ninjas' => 'ninjas',
					'Both' => 'both',
				],
				'default' => 'pirates',
			],
		];

		$htmlForm = new HTMLForm( $formDescriptor, $this->getContext() );
		$htmlForm
			->setSubmitText( 'Foo submit' )
			->setSubmitCallback( [ $this, 'trySubmit' ] )
			->show();
	}

	public function trySubmit( $formData ) {
		if ( $formData[ 'myfield1' ] === 'Fleep' ) {
			return true;
		}

		return 'Fail';
	}
}

$wgSpecialPages['TestForm'] = 'SpecialTestForm';

i18n/en.json

edit
{
	"@metadata": {
		"authors": [
			"MW_Kappa"
		]
	},
	"testform-desc": "some informative text for page Special:Version",
	"section1": "display text for section1",
	"subsection": "display text for subsection"
}

Display formats

edit

The default display format for HTMLForm is a table layout, with labels in the left column and inputs in the right column. It is possible to select a few different formats e.g. $htmlForm->setDisplayFormat( 'div' ); will use a div-based layout, the others more rare ones are raw and inline.

MediaWiki version:
1.26

To change the form to use the OOUI toolkit for HTMLform elements, starting with MediaWiki 1.26, you'll need to use 'ooui' as display format in HTMLForm::factory:

$htmlForm = HTMLForm::factory( 'ooui', $formDescriptor, $this->getContext() );

Historical notes

edit

HTMLForm was introduced by Werdna in r48740 as a part of his preferences system rewrite. Historically MediaWikis from version 1.4.0 to version 1.11.0 included a different HTMLForm class, written by Hashar and JeLuF. This HTMLForm was removed in r29245.