HTMLForm/tutorial3

From MediaWiki.org
Jump to navigation Jump to search

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[edit]

In $formDescriptor, there are two ways to declare a field type:

Class[edit]

First you can set the class attribute (do not mix 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 (what for?)
  • 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 anyway...)
  • HTMLHiddenField: Hidden field (data you need traveling, but not edited)
  • HTMLTagFilter: Tags filter
  • HTMLSizeFilterField: File's size filter
  • HTMLUsersMultiselectField: Select Multiple Users
  • HTMLTitleTextField: Textbox to take Page Name
  • HTMLDateTimeField: Date and Time Selector

Type[edit]

Before in this tutorial, we used class, now we're going to use type. type provides a shortcut to class.
Do 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 = 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[edit]

The following code builds this form:

HTMLFormTutorial.allfields.png

text[edit]

A simple text field called 'text':

$formDescriptor = [
    'text' => [
        'type' => 'text',
        'label' => 'text',
        'default' => 'Valeur par défaut', // Default String in field
        'size' => 10, // Display size of field
        'maxlength'=> 7, // Input maxlength of field
    ]
];

password[edit]

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

$formDescriptor = [
    'password' => [
        'type' => 'password',
        'label' => 'password',
        'default' => '', // Default String in field
        'size' => 16, // Display size of field
        'maxlength'=> 16, // Input maxlength of field
    ]
];

float[edit]

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

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

int[edit]

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

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

textarea[edit]

An extended text field called 'textarea':

$formDescriptor = [
    'textarea' => [
        'type' => 'textarea',
        'label' => 'textarea',
        'default' => 'Valeur par défaut', // Default string in field
        'rows' => 3, // Display height of field
        'cols' => 30, // Display width of field
    ]
]

select[edit]

A drop-down menu called 'select':

$formDescriptor = [
    'select' => [
        'type' => 'select',
        'label' => 'select',
        'options' => [ // The options available within the menu (displayed => value)
            '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[edit]

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

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

selectandother[edit]

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

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

multiselect[edit]

Checkboxes field called 'multiselect':

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

radio[edit]

Radio buttons field called 'radio':

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

check[edit]

A single checkbox field called 'mycheck':

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

checkmatrix[edit]

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 disabled (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[edit]

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

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

submit[edit]

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

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

hidden[edit]

A hidden text input called 'hidden':

$formDescriptor = [
    'hidden' => [
        'type' => 'hidden',
        'name' => 'hidden',
        'default' => 'This Intel Is Hidden', // String in field
    ]
];

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

tagfilter[edit]

HTMLForm Tagfilter.jpg

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

$formDescriptor = [
    'tagFilter' => [
        'type' => 'tagfilter',
        'name' => 'tagfilter',
        'label-raw' => $this->msg( 'tag-filter' )->parse(),
    ]
];

sizefilter[edit]

HTMLForm Sizefilter.jpg

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

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

user[edit]

HTMLForm User.jpg

Textbox which takes locally exist username as input.

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

usersmultiselect[edit]

HTMLForm Usersmultiselect.jpg

Select multiple users. See the example Prohibit these users from emailing me in the user preferences.

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

url[edit]

HTMLForm Url.jpg

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

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

title[edit]

HTMLForm Title.jpg

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

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

date[edit]

HTMLForm Date.jpg

Auto date selector which takes date as input.

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

time[edit]

HTMLForm Time.jpg

Auto time selector which takes date and time as input.

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

datetime[edit]

HTMLForm Datetime.jpg

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[edit]

HTMLForm Email.png

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

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

limitselect[edit]

HTMLForm Limitselect.jpg

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