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'

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'

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: HTMLCheckFieldsimilar to check, but through use of 'invert' => true default state can be set to checked
edittools: HTMLEditToolsinserts 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,
    ]
];

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,
        ],
    ]
];