Manual:HTMLForm Tutorial 3

Translate this page

Any kind of field can be generated by HTMLForm, field-specific options will be described here. Generic options (those any field can be assigned) are described on Tutorial 2.

Introduction

In $formDescriptor, there are two ways to declare a field type: by the class or the type attributes.

Using class attribute

First you can set the class attribute (do not mix or confuse with cssclass)

'class' => 'HTMLTextField'

Name	Description
HTMLTextField	A simple text field
HTMLFloatField	A simple text field with float (number) validation
HTMLIntField	A simple text field with integer validation
HTMLUserTextField	A simple text field for user names
HTMLTextAreaField	An extended text field
HTMLSelectField	A dropdown menu
HTMLSelectOrOtherField	A dropdown menu with an 'other' option that toggles a simple text field on
HTMLSelectAndOtherField	A dropdown menu and a simple text field
HTMLMultiSelectField	List of checkboxes
HTMLRadioField	Radio buttons
HTMLCheckField	Single checkbox
HTMLCheckMatrix	2D matrix of checkboxes
HTMLInfoField	Just text, no input
HTMLSubmitField	Additional submit button (HTMLForm always adds one by default)
HTMLHiddenField	Hidden field (data you need to send, but not shown or edited)
HTMLTagFilter	Tags filter
HTMLSizeFilterField	File's size filter
HTMLUsersMultiselectField	Select Multiple Users
HTMLTitleTextField	Textbox to take Page Name
HTMLDateTimeField	Date and Time Selector

Using type attribute

Before in this tutorial, we used class, now we're going to use type. type provides a shortcut to class, but class takes priority. Therefore, you should not use both!

'type' => 'text'

Name	Type	Description
text	HTMLTextField
password	HTMLTextField
textarea	HTMLTextAreaField
select	HTMLSelectField
radio	HTMLRadioField
multiselect	HTMLMultiSelectField
check	HTMLCheckField
checkmatrix	HTMLCheckMatrix
int	HTMLIntField
float	HTMLFloatField
info	HTMLInfoField
selectorother	HTMLSelectOrOtherField
selectandother	HTMLSelectAndOtherField
submit	HTMLSubmitField
hidden	HTMLHiddenField
tagfilter	HTMLTagFilter
sizefilter	HTMLSizeFilterField
user	HTMLUserTextField
usersmultiselect	HTMLUsersMultiselectField
url	HTMLTextField
title	HTMLTitleTextField
date	HTMLDateTimeField
time	HTMLDateTimeField
datetime	HTMLDateTimeField
limitselect	HTMLSelectField
email	HTMLTextField	supposedly for HTML5 client-side validation, NO SERVER-SIDE VALIDATION HERE!
toggle	HTMLCheckField	similar to check, but through use of `'invert' => true` default state can be set to checked
edittools	HTMLEditTools	inserts system message, a parsed content of MediaWiki:Edittools

Goal

The following code builds this form:

text

A simple text field called 'text':

$formDescriptor = [
    'text' => [
        'type' => 'text',
        'label' => 'text',
        // Default value of the field
        'default' => 'Valeur par défaut',
        // Display size of field
        'size' => 10,
        // Maximum length of the input
        'maxlength'=> 7, 
    ]
];

password

A text field displayed like password field called 'password':

$formDescriptor = [
    'password' => [
        'type' => 'password',
        'label' => 'password',
        // Default value of the field
        'default' => '',
        // Display size of field
        'size' => 16,
        // Maximum length of the input
        'maxlength'=> 16,
    ]
];

float

A text field validated only by floating numbers called 'float':

$formDescriptor = [
    'float' => [
        'type' => 'float',
        'label' => 'float',
         // Default value of the field (recommendation: put a float as default)
        'default' => 41.976,
         // Display size of field
        'size' => 8,
		// Maximum length of the input
        'maxlength'=> 6,
        // Minimum value for input
        'min' => 41,
        // Maximum value for input
        'max' => 43,
    ]
];

int

A text field validated only by integers called 'int':

$formDescriptor = [
    'int' => [
        'type' => 'int',
        'label' => 'int',
        // Default value of the field (recommendation: put an int as default)
        'default' => 1789,
        // Display size of field
        'size' => 4,
		// Maximum length of the input
        'maxlength'=> 4,
		// Minimum value for input
        'min' => 0,
		// Maximum value for input
        'max' => 2011,
    ]
];

textarea

An extended text field called 'textarea':

$formDescriptor = [
    'textarea' => [
        'type' => 'textarea',
        'label' => 'textarea',
		// Default value of the field
        'default' => 'Valeur par défaut',
		// Amount of rows (height of the field)
        'rows' => 3, // Display height of field 
    ]
]

select

A drop-down menu called 'select':

$formDescriptor = [
    'select' => [
        'type' => 'select',
        'label' => 'select',
		// The options available within the menu (displayed => value)
        'options' => [
            'Option 0' => 0, // depends on how you see it but keys and values are kind of mixed here
            'Option 1' => 1, // "Option 1" is the displayed content, "1" is the value
            'Option 2' => 'option2id', // HTML Result = <option value="option2id">Option 2</option>
        ]
    ]
];

selectorother

A dropdown menu with an 'other' option that toggles a simple text field on called 'selectorother':

$formDescriptor = [
    'selectorother' => [
        'type' => 'selectorother',
        'label' => 'selectorother',
		// The options available within the menu (displayed => value)
        'options' => [
            'Option 0' => 0,
            'Option 1' => 1,
            'Option 2' => 'option2id',
        ],
		// Maximum size of the 'other' field
        'size' => 7,
		// Maximum length of the 'other' field
        'maxlength'=> 10,
    ]
];

selectandother

A dropdown menu and a simple text field called 'selectandother':

$formDescriptor = [
    'selectandother' => [
        'type' => 'selectandother',
        'label' => 'selectandother',
		// The options available within the menu (displayed => value)
        'options' => [
            'Option 0' => 0,
            'Option 1' => 1,
            'Option 2' => 'option2id',
        ],
		// Maximum size of the 'other' field
        'size' => 18,
		// Maximum length of the 'other' field
        'maxlength'=> 10, 
    ]
];

multiselect

Checkboxes field called 'multiselect':

$formDescriptor = [
    'multiselect' => [
        'type' => 'multiselect',
        'label' => 'multiselect',
		// The options available within the checkboxes (displayed => value)
        'options' => [
            'Option 0' => 0,
            'Option 1' => 1,
            'Option 2' => 'option2id',
        ],
		// The options selected by default (identified by value)
        'default' => [ 0, 'option2id' ],
    ]
];

radio

Radio buttons field called 'radio':

$formDescriptor = [
    'radio' => [
        'type' => 'radio',
        'label' => 'radio',
		// The options available within the checkboxes (displayed => value)
        'options' => [
            'Option 0' => 0,
            'Option 1' => 1,
            'Option 2' => 'option2id',
        ],
		// The options selected by default (identified by value)
        'default' => 1,
        // If true, displays the options in a row, rather than a column
        'flatlist' => false,
    ]
];

check

A single checkbox field called 'mycheck':

$formDescriptor = [
    'mycheck' => [
        'type' => 'check',
        'label' => 'mycheck',
    ]
];

checkmatrix

A 2D matrix of checkboxes called 'checkmatrix':

$formDescriptor = [
    'checkmatrix' => [
        'type' => 'checkmatrix',
        'label' => 'checkmatrix',
        // The columns are combined with the rows to create the options available within the matrix
        // displayed => value
        'columns' => [
            // displayed => value
            'Column A' => 'A',
            'Column B' => 'B',
            'Column C' => 'C',
        ],
        // The rows are combined with the columns to create the options available within the matrix
        'rows' => [
            // displayed => value
            'Row 1' => 1,
            'Row 2' => 2,
            'Row 3' => 3,
        ],
        'force-options-on' => [ 'C-2' ], // Options to make checked and enabled (identified by values)
        'force-options-off' => [ 'C-3' ], // Options to make unchecked and disabled (identified by values)
        'tooltips' => [ 'Row 3' => 'These options are in row 3.' ], // Tooltip to add to the Row 3 row label
        'default' => [ 'A-1', 'B-3' ], // Options selected by default (identified by values)
    ]
];

info

Just raw text string (no input at all) called 'info':

$formDescriptor = [
    'info' => [
        'type' => 'info',
        'label' => 'info',
        // Value to display
        'default' => '<a href="https://wikipedia.org/">Wikipedia</a>',
        // If true, the above string won't be HTML escaped
        'raw' => true,
    ]
];

submit

A submit button called 'submit'. By default, there's already one at the end of the form, this is an additional button:

$formDescriptor = [
    'submit' => [
        'type' => 'submit',
        'buttonlabel' => 'submit',
    ]
];

hidden

A hidden text input called 'hidden':

$formDescriptor = [
    'hidden' => [
        'type' => 'hidden',
        'name' => 'hidden',
        // Value to send
        'default' => 'This Intel Is Hidden',
    ]
];

You can also use $form->addHiddenField( 'name', 'value' ) to accomplish the same goal.

tagfilter

Filter on Tags. See the list of Tags at Special:Tags.

$formDescriptor = [
    'tagFilter' => [
        'type' => 'tagfilter',
        'name' => 'tagfilter',
        'label-message' => 'tag-filter',
    ]
];

sizefilter

Filter on size. See the example on Special:NewPages.

$formDescriptor = [
    'size' => [
        'type' => 'sizefilter',
        'name' => 'size',
        'default' => '',
    ]
];

user

Textbox which takes locally existing username as input.

$formDescriptor = [
    'username' => [
        'type' => 'user',
        'label' => 'Username:',
        'exists' => true,
    ]
];

usersmultiselect

Select multiple users. See the example ⧼email-blacklist-label⧽ in the user preferences.

$formDescriptor = [
    'size' => [
        'type' => 'usersmultiselect',
        'name' => 'size',
        'label' => 'Publishers:',
        'exists' => true,
    ]
];

url

Textbox which takes a web URL (http:// or https://) as input.

$formDescriptor = [
    'urlinput' => [
        'type' => 'url',
        'name' => 'web-url',
        'label' => 'Url:',
    ]
];

title

Autocomplete textbox which takes a title of a wiki page as input.

$formDescriptor = [
    'titleinput' => [
        'type' => 'title',
        'name' => 'page-title',
        'label' => 'Title:',
    ]
];

date

Auto date selector which takes date as input.

$formDescriptor = [
    'dateSelector' => [
        'type' => 'date',
        'name' => 'date-input',
        'label' => 'Date:',
    ]
];

time

Auto time selector which takes time as input.

$formDescriptor = [
    'timeSelector' => [
        'type' => 'time',
        'name' => 'time-input',
        'label' => 'Time:',
    ]
];

datetime

Auto date and time selector which takes date and time as input.

$formDescriptor = [
    'datetimeSelector' => [
        'type' => 'datetime',
        'name' => 'datetime-input',
        'label' => 'Date and Time:',
        'min' => $min, // Set $min as minimum value
        'max' => $max, // Set $max as maximum value
    ]
];

email

Textbox which takes an email address (abc@g.com) as input.

$formDescriptor = [
    'myemail' => [
        'type' => 'email',
        'label' => 'Enter Your Email:',
        'autofocus' => true,
        'help' => 'This is the help message for myemail.',
    ]
];

limitselect

A drop-down menu selector for limit.

$lang = $this->getLanguage();
$formDescriptor = [
    'limit' => [
        'type' => 'limitselect',
        'name' => 'limit',
        'label' => 'Items per page',
        'options' => [
            $lang->formatNum( 20 ) => 20,
            $lang->formatNum( 50 ) => 50,
            $lang->formatNum( 70 ) => 70,
            $lang->formatNum( 100 ) => 100,
        ],
    ]
];