OOUI/Widgets/Inputs

OOjs UI Input widgets, which include text, checkbox, radio, and button inputs, are a subset of HTML form elements (they are, in fact, wrappers around HTML inputs). They can be configured (to use an icon, for example) and have been designed to work reliably across browsers. Events, such as changes to the value of an input, are handled by the library, which takes care of the (often tedious) work of extracting a meaningful value.

Optionally, input widgets can be configured with an input filter, which modifies the value of an input before it is accepted. An input widget that collects phone numbers might use an input filter to ignore values that contain non-numerical characters, for example. If the input value must be a MediaWiki page title, an input filter could also be used to convert values to start with an upper-case letter. Input filters are written by the developer and are assigned to an input widget via the inputFilter config option, which takes the name of the filter function.

InputWidgets support a number of methods, including setRTL, which can be used to set the direction of the input (left-to-right or right-to-left) and setValue and getValue, which set and get the value of the input, respectively. For a complete list of supported methods and configuration options, please see the code-level documentation.

Text inputs
TextInputWidgets can be configured with options that customize the size of the input field as well as its presentation. Text inputs can be set to be multiline or autosized, or assigned placeholder text or an initial value. Text inputs also be configured with an optional validation-pattern, which is used to determine if a value is valid or not. (This is distinct from the input filters, which modify incoming values rather than validate them.)

Create a text input with the TextInputWidget class:

Create a multiline input with the multiline option:

Create an autosized input with the  autosize and maxRows options:

Add placeholder copy with the placeholder option:

Make the value read-only with the readOnly option:

Change the type of the input with the type config:

Specify a validation pattern with the validate config:

Use icon, indicator, and disabled config options:

TextInputWidgets support a number of methods that can be used to adjust the size of the text input, check validity, and handle events. For a complete list for supported methods and configuration options, please see the code-level documentation.

Checkbox inputs
CheckboxInputWidgets, like HTML checkboxes, can be selected and/or configured with a value. Use the setSelected and getSelected methods to set or get the checked state of the box. A checkbox can also be selected via its selected configuration option.

A checkbox value, which is useful when the checkbox is part of an HTML element, can be assigned or gotten with the setValue and getValue methods. A value can also be configured with the value configuration option (by default, the value is an empty string).

Note that CheckboxInputWidgets are best laid out in FieldLayouts that use the ‘inline’ alignment, as in the below example.

The getSelected and setSelected methods can be used to get or set the state of the checkbox. For a complete list of supported methods and configuration options, please see the code-level documentation.

Radio inputs
Radio inputs are usually used as a set, and in most cases you will want to use a RadioSelectWidget with RadioOptionWidgets instead of the RadioInputWidget itself. However, if you have need for a single radio input, the RadioInputWidget works much as a CheckboxInputWidget does. The selected state can be set with either the setSelected method or via the widget’s selected configuration option.

For more information about RadioInputWidgets, please see the code-level documentation.

Button inputs
ButtonInputWidgets, together with FormLayouts, are used to submit HTML forms. By default, ButtonInputWidgets are rendered as an HTML   and can be configured with options such as icons, indicators, and a value.

If you don’t need the button to work with HTML forms, you probably want to use a ButtonWidget instead.

ButtonInputWidgets can also be rendered as an HTML using the useInputTag configuration. Widgets configured to be an do not support config options such as icons, indicators, and values, and can only use plaintext labels. In general, ButtonInputsWidgets should only be configured as an   when there’s need for IE6 support in a form with multiple buttons.

Create an input button with the ButtonInputWidget class:

For a complete list of supported methods and configuration options, please see the code-level documentation.