HTMLForm

HTMLFormはユーザーインターフェイスフォームに関連するすべてのものを取り扱うためのクラスである。MediaWiki 1.16とそれ以降では、HTMLForm.phpにHTMLFormが含まれています。

HTMLFormチュートリアルは、HTMLFormの基本を説明します。

パラメータ

Precise specification for:

• Generic Parameters on HTMLForm tutorial part 2

• Type/Class related Parameters on HTMLForm tutorial part 3

パラメーター	型	説明	Default
type	文字列	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	文字列	PHP Subclass to use for this form content. This accomplishes the same thing as the type parameter, but more directly. これはCSSのクラスではありません。
size	整数	テキストフィールドの長さを設定します。
maxlength	整数	テキストフィールドの最大長を設定します。
min	整数	The minimum amount for the value
max	整数	The maximum amount for the value
invert	真偽値	Set inputs of type toggle to checked by default
options	配列	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	配列	The rows to present in a checkmatrix form element or the number of rows shown for textarea form element
columns	配列	The columns to present in a checkmatrix form element
force-options-off	配列	Options to set unchecked and disabled in a checkmatrix form element
force-options-on	配列	Options to set checked and enabled in a checkmatrix form element
section	文字列	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	文字列	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	文字列	フォームの入力欄/ボタンのラベル Overridden by label-message.
vertical-label	真偽値	Set to true if you want the label to appear above the options rather than to the left of the options
id	文字列	入力欄に割り当てる ID 属性
cssclass	文字列	入力欄に割り当てる class 属性
csshelpclass	文字列	CSS class used to style help text
validation-callback	配列	Class and function to use for input validation. HTMLFormField::validate() を参照
filter-callback	配列	Class and function to use for input filtering. It gives you the chance to massage the inputted value before it's processed. HTMLFormField::filter() を参照
help-message	文字列	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	文字列	Message to display directly below the form element to use as a help text.
tooltip	文字列	Key suffix for i18n messages to use for title and/or accesskey attributes (tooltip-YOURVALUE and accesskey-YOURVALUE)
placeholder	文字列	Value to use for the HTML5 placeholder attribute
placeholder-message	文字列	Key for an i18n message to display as a placeholder
disabled	真偽値	Disable editing and submission of the form input
readonly	真偽値	Disable editing of the form input
required	真偽値	If true, the input cannot be left blank. It is passed through to the object, indicating that it is a required field.
name	文字列	Override the name of the input. If you want a different name (eg one without the "wp" prefix), specify it here and it will be used without modification.	wp{$fieldname}
dir	文字列	Direction of the element.
'options-messages'	配列	associative array mapping message keys to values. Some field types support multi-level arrays. Overwrites 'options' and 'options-message'.
'options-message'	配列	message key or object to be parsed to extract the list of options (like ipbreason-dropdown).
'help-messages'	配列	array of message keys/objects. As above, each item can be an array of msg key and then parameters. Overwrites help.
'help-inline'	配列	Whether help text (defined using options above) will be shown inline after the input field, rather than in a popup. Only used by OOUI form fields.	true
'hide-if'	配列	Expression given as an array stating when the field should be hidden. The first array value has to be the expression's logic operator. Supported expressions: Expression Syntax Description 'NOT' [ '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. Note, you can only check expressions against preferences. If you want to hide preferences based on other criteria you should consider altering the type to hidden based on that condition. For example, do not check ['!==', 'skin', 'minerva'] to check the current skin, as this will not work as skin is the preference for the desktop skin which will not hold true for a mobile page view or a view using useskin=minerva.
'disable-if'	配列	Expression given as an array stating when the field should be disabled, using the same syntax of the hide-if conditions discussed above.
nodata	真偽値	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	文字列 (または配列)	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.

使用例

クラス SpecialTestForm

<?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

{
	"@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

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. There are rarer display formats such as raw and inline.

MediaWiki バージョン:

≧ 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 the display format in HTMLForm::factory:

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

Historical notes

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.