HTMLForm
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.
Parametry
Precise specification for:
- Generic Parameters on HTMLForm tutorial part 2
- Type/Class related Parameters on HTMLForm tutorial part 3
Parametr | Typ | Opis |
---|---|---|
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 |
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 | Długość pola tekstowego |
maxlength | integer | Maksymalna długość pola tekstowego |
min | integer | Wartość minimalna |
max | integer | Wartość maksymalna |
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.
|
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. |
Przykład użycia
class 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"
}
{{{text}}} |
Formaty wyświetlania
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
.
Wersja 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 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.