OOUI/Using OOUI in MediaWiki

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

Before you start
To use OOjs UI elements, you have to load the necessary styles and set up the OOjs UI 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 OOjs UI styles. The OOjs UI widgets are namespaced, so they must be prefixed with. Stringifying the widgets converts them to HTML, so you can add widgets to the page using.

Parser functions and tags, 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 OOjs UI/PHP examples. (Instead of  tags use the ResourceLoader style modules described below.)

Using OOjs UI widgets
Construct a widget: Its properties can be changed using getter/setter methods: When you're done creating the widget, you can treat is like a string to display it. (You can explicitly convert to string by calling the  method.)

List of available elements
See also: As of OOjs UI v0.17.9 (released 2016-09-13), the elements available in PHP are:
 * Automatically updated list: https://doc.wikimedia.org/oojs-ui/master/php/annotated.html
 * Demo with examples: https://phabricator.wikimedia.org/diffusion/GOJU/browse/master/demos/pages/widgets.php (live)

Widgets: Layouts:
 * ButtonWidget
 * ButtonGroupWidget
 * ButtonInputWidget
 * CheckboxInputWidget
 * CheckboxMultiselectInputWidget
 * RadioInputWidget
 * RadioSelectInputWidget
 * TextInputWidget
 * DropdownInputWidget
 * ComboBoxInputWidget
 * LabelWidget
 * IconWidget
 * IndicatorWidget
 * ProgressBarWidget
 * FieldLayout
 * ActionFieldLayout
 * FieldsetLayout
 * FormLayout
 * PanelLayout
 * HorizontalLayout

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

HTMLForm, FormSpecialPage
HTMLForm has OOjs UI support. You can use the  display format for HTMLForm forms to render them using OOjs UI. This is usually more convenient, as HTMLForm provides functionality for validation and handling form submission. See HTMLForm. On FormSpecialPage, use the  method: Examples: Widgets used in the form will be automatically infused (see below) if the JS widget offers additional capabilities over the PHP one.
 * 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)

JavaScript
From JavaScript code, you just need to list the  module as a dependency of your modules that use OOjs UI. For example:

See 187079 for some more ideas.

Infusion
TODO Write me.

Gadgets
OOjs UI can be used in on-wiki gadgets or user scripts. As above, you just need to ensure the  module 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: If you're using OOUI widgets that aren't in PHP, it's likely that they aren't in -core, which is kept as small as possible. To use those, you need to also depend on. If you're using windows (including message alerts), you should also depend on. If you're using toolbars, you should also depend on.

MediaWiki-specific OOjs UI widgets
Several MediaWiki-specific OOjs UI 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