OOUI/Using OOUI in MediaWiki

 is included in MediaWiki core, available to be used by both PHP and JavaScript code.

Before you start
To use OOUI elements, you have to load the necessary styles and set up the OOUI PHP library to use the correct skin (boring details).

The most convenient way to do this is:

Special pages etc.
Whenever you have access to an OutputPage instance, call its  method. It is usually available as  in most contexts, such as on special pages, or as   in hook signatures.

Example:

(implemented by class ) ensures that the proper theme and directionality is configured, and that the page loads the OOUI styles. The OOUI widgets are namespaced, so they must be prefixed with  or imported. Stringifying the widgets converts them to HTML, so you can add widgets to the page using. Also note that in some cases, just enabling OOUI is not enough. For example, if you need a certain icon added, you need to explicitly add the related icon pack. For example:

Parser functions and tags, 1>Special:MyLanguage/Manual:ContentHandler|content models
If you have access to a ParserOutput instance (usually as  or  ), call its   method, and also.

If you have access to a Parser instance, instead just call its  method.

Example:

Otherwise
See OOUI/PHP examples. (Instead of tags use the ResourceLoader style modules described below.)

Using OOUI widgets
Construct a widget:

Its properties can be changed using getter/setter methods:

When you're done creating the widget, you can treat it like a string to display it. (You can explicitly convert to string by calling the  method.)

List of available elements
See also:


 * Automatically updated list: https://doc.wikimedia.org/oojs-ui/master/php/annotated.html
 * Live demo with examples (demo page in master branch)

As of OOUI v0.34.0, released 2019-09-04, these elements available in PHP (or in JS via, see below) are:

Widgets:


 * ButtonWidget
 * ButtonInputWidget
 * ButtonGroupWidget
 * CheckboxInputWidget
 * CheckboxMultiselectInputWidget
 * RadioInputWidget
 * RadioSelectInputWidget
 * TextInputWidget
 * MultilineTextInputWidget
 * NumberInputWidget
 * SearchInputWidget
 * DropdownInputWidget
 * ComboBoxInputWidget
 * LabelWidget
 * IconWidget
 * IndicatorWidget
 * ProgressBarWidget
 * SelectFileInputWidget
 * SelectWidget
 * TabSelectWidget
 * TabOptionWidget

Layouts:


 * ActionFieldLayout
 * FieldLayout
 * FieldsetLayout
 * FormLayout
 * HorizontalLayout
 * IndexLayout
 * MenuLayout
 * PanelLayout
 * TabPanelLayout
 * StackLayout

Example
Large structures can be created and displayed in a single call:

, FormSpecialPage
HTMLForm has OOUI support. You can use the  display format for HTMLForm forms to render them using OOUI. This is usually more convenient, as HTMLForm provides functionality for validation and handling form submission. See HTMLForm.

On FormSpecialPage, use the  method:

Examples:


 * https://phabricator.wikimedia.org/diffusion/MW/browse/master/includes/specials/SpecialMIMESearch.php (Special:MIMESearch)
 * https://phabricator.wikimedia.org/diffusion/MW/browse/master/includes/specials/SpecialResetTokens.php (Special:ResetTokens)

Widgets used in the form will be automatically infused (see below) if the JS widget offers additional capabilities over the PHP one.

Using OOUI widgets
Depending on which of the features you're going to use, you should list one or more of the following modules as dependencies of your modules that use OOUI:


 * : OOUI's core JavaScript library. Contains the basic widgets and layouts that are also available in PHP (see exact list above) and the ability to infuse them.
 * : Additional widgets and layouts.
 * : Toolbar and tools.
 * : Windows and dialogs.

For example (extension.json):

Code in modules depending on OOUI can use the elements, as described in this OOUI documentation. Start reading it here.

Infusion
To provide progressive enhancement and avoid code duplication between PHP and JS, OOUI PHP widgets present on a page can be infused into OOUI widgets.

Assuming that a PHP widget has been made infusable when it was created:

It can be infused from JavaScript code:

The widget can now be modified from JavaScript code:

Gadgets
OOUI can be used in on-wiki gadgets or user scripts. As above, you just need to ensure the  module (or a different one, as described above) is loaded before your code runs.

For gadgets, you should add an entry in the  field of gadget description. See Gadgets' documentation for instructions and examples.

For user scripts, wrap your code in a  call, as always when loading modules. See ResourceLoader documentation for instructions. Example:

MediaWiki-specific OOUI widgets
Several MediaWiki-specific OOUI widgets are available under the  (JavaScript) or   (PHP) namespace, implementing interface elements common in MediaWiki.

TODO Write me.


 * Manual:TitleInputWidget
 * Manual:UserInputWidget
 * Manual:SearchInputWidget
 * Manual:NamespaceInputWidget
 * Manual:DateInputWidget (example: https://gerrit.wikimedia.org/r/#/c/226647/)
 * Manual:DateTimeInputWidget
 * Manual:CategorySelector

Using themes
OOUI comes with two themes, and every widget you create will use the theme defined by the current skin using  in extension.json. Custom themes can also be provided by the skin. See OOUI/Themes for details.