OOUI/Using OOUI in MediaWiki

OOUI
Introduction
About the library OOjs primer
Getting started
Creating interfaces programmatically PHP examples Using OOUI in MediaWiki
Working with widgets
Elements GroupElements FlaggedElements LookupElements DraggableElements Widgets Icons, Indicators, and Labels Buttons and Switches Selects and Options Inputs Popups Progress bars Layouts Fields and Fieldsets Forms Stacks and Panels Menus Booklets and Pages Index and TabPanels Windows Simple messages Dialogs Process Dialogs Message Dialogs Window managers Toolbars Themes Other concepts
See also
Fixing scripts and gadgets

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

PHP

Before you start

To use OOUI elements, the OOUI PHP library has to be loaded and the necessary styles have to be set up per the correct skin (boring details).

The most convenient way to do this is using the following.

Special pages etc.

Whenever you have access to an OutputPage instance, call its enableOOUI() method. It is usually available as $this->getOutput() in most contexts, such as on special pages, or as $out in hook signatures.

Example:

function execute( $param ) {
	$out = $this->getOutput();
	$out->enableOOUI();
	// … More code here …
	$group = new OOUI\ButtonGroupWidget( [
		// … More widgets here …
	] );
	$out->addHTML( $group );
}

Another example, useful when you have no easy access to an OutputPage instance:

RequestContext::getMain()->getOutput()->enableOOUI();

Note that the method enableOOUI() (implemented by class OutputPage ) 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 OOUI\ or imported. Stringifying the widgets converts them to HTML, so you can add widgets to the page using $out->addHTML(). 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.

Example:

public function load() {
    $this->getOutput()->enableOOUI();
    $this->getOutput()->addModuleStyles( [ 'oojs-ui.styles.icons-moderation' ] );
    return ( new OOUI\IconWidget(
		[
			'icon' => 'block',
			'classes' => [ 'flaggedrevs-icon' ],
			'title' => 'Block',
		]
	) )->toString();
}

Parser functions and tags, content models

If you have access to a ParserOutput instance (usually as $parser->getOutput() or $pout), call its setEnableOOUI( true ) method, and also OutputPage::setupOOUI().

Example:

public static function myTagHook( $content, array $attributes, Parser $parser, PPFrame $frame ) {
	OutputPage::setupOOUI();
	$parser->getOutput()->setEnableOOUI( true );
	// … More code here …
	$group = new OOUI\ButtonGroupWidget( [
		// … More widgets here …
	] );
	return [ $group->toString(), 'markerType' => 'nowiki' ];
}

Otherwise

See OOUI/PHP examples#Before you start. (Instead of ‎<link> tags use the ResourceLoader style modules described below.)

Using OOUI widgets

Construct a widget:

$btn = new OOUI\ButtonWidget( [
    'label' => 'Click me!',
    'href' => 'https://example.com',
] );

Its properties can be changed using getter/setter methods:

$btn->setLabel( 'Still click me!' );

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

$this->getOutput()->addHTML( "<div>$btn</div>" );

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 oojs-ui-core, 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:

$this->getOutput()->addHTML( new OOUI\FormLayout( [
	'method' => 'POST',
	'action' => 'login.php',
	'items' => [
		new OOUI\FieldsetLayout( [
			'label' => 'Form layout',
			'items' => [
				new OOUI\FieldLayout(
					new OOUI\TextInputWidget( [
						'name' => 'username',
					] ),
					[
						'label' => 'User name',
						'align' => 'top',
					]
				),
				new OOUI\FieldLayout(
					new OOUI\TextInputWidget( [
						'name' => 'password',
						'type' => 'password',
					] ),
					[
						'label' => 'Password',
						'align' => 'top',
					]
				),
				new OOUI\FieldLayout(
					new OOUI\CheckboxInputWidget( [
						'name' => 'rememberme',
						'selected' => true,
					] ),
					[
						'label' => 'Remember me',
						'align' => 'inline',
					]
				),
				new OOUI\FieldLayout(
					new OOUI\ButtonInputWidget( [
						'name' => 'login',
						'label' => 'Log in',
						'type' => 'submit',
						'flags' => [ 'primary', 'progressive' ],
						'icon' => 'check',
					] ),
					[
						'label' => null,
						'align' => 'top',
					]
				),
			]
		] )
	]
] ) );

HTMLForm , FormSpecialPage

HTMLForm has OOUI support. You can use the ooui 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#Display formats.

$htmlForm = HTMLForm::factory( 'ooui', $formDescriptor, $this->getContext() );

On FormSpecialPage, use the getDisplayFormat() method:

protected function getDisplayFormat() {
	return 'ooui';
}

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.

JavaScript

Using OOUI widgets

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

• oojs-ui-core — 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.
• oojs-ui-widgets — Additional widgets and layouts.
• oojs-ui-toolbars — Toolbar and tools.
• oojs-ui-windows — Windows and dialogs.
• oojs-ui.styles.icons-* — Specific icon styles depending on what icons you may want to use, e.g. oojs-ui.styles.icons-interactions for check icon. Group names can be found in demo page or in code.

For example (extension.json ):

{
	"ResourceModules": {
		"ext.myExtension": {
			"dependencies": [
				"oojs-ui-core",
				"oojs-ui-windows"
			],
			"scripts": [
				...
			]
		}
	}
}

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:

$btn = new OOUI\ButtonWidget( [
    'infusable' => true,
    'id' => 'my-button',
    'label' => 'Click me!',
    'href' => 'https://example.com',
] );

It can be infused from JavaScript code:

var button = OO.ui.infuse( $( '#my-button' ) );
// Or, for self-documenting code:
var button = OO.ui.ButtonWidget.static.infuse( $( '#my-button' ) );

The widget can now be modified from JavaScript code:

button
	.setLabel( 'Really click me!' )
	.on( 'click', function () {
		alert( 'I was clicked!' );
	} );

Gadgets

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

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

For user scripts, wrap your code in a mw.loader.using( … ) call, as always when loading modules. See ResourceLoader documentation for instructions. Example:

mw.loader.using( 'oojs-ui-core' ).done( function () {
	$( function () {
		var button = new OO.ui.ButtonWidget( {
			label: 'Click me!'
		} );
		button.on( 'click', function () {
			alert( 'You clicked the button!' );
		} );
		$( '#mw-content-text' ).append( button.$element );
	} );
} );

MediaWiki-specific OOUI widgets

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

TODO: Write me.

• Manual:TitleInputWidget
• Manual:UserInputWidget
• Manual:SearchInputWidget
• Manual:NamespaceInputWidget
• Manual:DateInputWidget (example call)
• Manual:DateTimeInputWidget
• Manual:CategoryMultiselectSelector

Using themes

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