HTMLForm

From MediaWiki.org
Jump to: navigation, search
Translate this page; This page contains changes which are not marked for translation.

Other languages:
català • ‎Deutsch • ‎English • ‎español • ‎suomi • ‎italiano • ‎日本語 • ‎polski • ‎português • ‎português do Brasil • ‎русский • ‎中文

HTMLForm is a class for handling everything related to user interface forms. It was introduced by Werdna in r48740 as a part of his preferences system rewrite. MediaWiki 1.16 and newer include HTMLForm in HTMLForm.php.

Historically MediaWikis from version 1.4.0 to version 1.11 included a different HTMLForm class, written by Hashar and JeLuF. This HTMLForm was removed in r29245.

HTMLForm/tutorial shows basics of HTMLForm .

Parameters[edit]

Documenting the parameters for HTMLForm forms so they don't get lost

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.
class string Subclass to use for this form content. This accomplishes the same thing as the type parameter, but more directly.
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
rows array The rows to present in a checkmatrix 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 disabled in a checkmatrix form element
section string Key for an i18n message to display as a section or subsection header
label-message,
buttonlabel-message
string Key for an i18n message to display as a label for a form input/button
label,
label-raw,
buttonlabel
string Label for a form input/button
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
validation-callback array Class and function to use for input validation
filter-callback array Class and function to use for input filtering
help-message string Key for an i18n message to display directly below the form element
help string Message to display directly below the form element
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
name string Override the name of the input (default is wp{$fieldname})
default string (or array) Default value(s) for the field (not to be confused with $wgDefaultUserOptions)

Example usage[edit]

<?php

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

	public function execute( $par ) {
		$this->getOutput()->setPageTitle( 'LOL TEST FORM' );

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

		$htmlForm = new HTMLForm( $formDescriptor, $this->getContext(), 'testform' );

		$htmlForm->setSubmitText( 'Foo submit' );
		$htmlForm->setSubmitCallback( array( 'SpecialTestForm', 'trySubmit' ) );

		$htmlForm->show();
	}

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

		return 'HAHA FAIL';
	}
}

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


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.

$form->setDisplayFormat( 'div' );

will use a div-style layout.


MediaWiki version: 1.26

To change the form to use the OOjs UIOOjs UI toolkit for HTML form elements, starting with MediaWiki 1.26, you'll need to use HTMLForm::factory:

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

See also[edit]