OOUI

OOjs UI (Object-Oriented JavaScript – User Interface) is a modern JavaScript UI toolkit for browsers. It provides a library of common widgets, layouts and windows that are ready to use, as well as many foundational classes for constructing custom user interfaces. The library was originally created for use by VisualEditor, which uses it for its entire user interface. More recently, the library has been made completely independent of VisualEditor and made more useful and convenient for other use cases, and is an important part of ongoing UX standardization work.

Dependencies
OOjs UI is a separate project which is available as a library in MediaWiki Core as of version 1.23. Its only dependencies are OOjs and jQuery, which are also available in MediaWiki core.

For development, there are some additional dependencies; such as Grunt, which is used to build the distributable library files. See the project's for more information about the build process.

To use the library within MediaWiki, add the provided  ResourceLoader module to your dependencies.

A basic theme called Apex is currently provided by default. An additional theme styled after Agora-styled is currently being developed, and upon completion will be the default theme when using OOjs UI within MediaWiki. It is possible to provide additional themes for a custom skin if you wish.

Compatibility
Browser compatibility is being increased, but currently only modern browsers are targeted. Generally, it is superset of VisualEditor's restricted browser compatibility, which is especially restricted due to VisualEditor's use of contentEditable.

Documentation
In addition to the high-level documentation below, the generated documentation provides a complete reference.

Elements
Anything that is visible to the user is an. Elements have an  property which is a jQuery selection of its rendered contents.

Widgets are compositions of one or more elements, and often also compose other widgets as well. Many common visual features are provided through mixed-in elements which provide such compositions. Examples include  or   which each provide a common API for configuration and modification while also providing a rendering which can be composed as needed. Elements which contain a list of other elements mixin, which provides a common API for adding and removing items. There are also mixins that add behavior to an element, such as OO.ui.ClippableElement, which automatically sizes an element to fit within the viewport and makes clipped areas accessible through scrolling.

Widgets
Widgets combine a view, in the form of DOM nodes, and a controller in the form of DOM event handling. They abstract rendering and user interaction by providing a configuration and modification API and emitting events when meaningful interactions occur.

Layouts
Layouts are similar to widgets, but are used specifically to arrange widgets on the screen. Forms can be created by combining,  , and. can be used to display one  at a time in the same region. provides a more advanced mutually-exclusive selection of, with an optional outline and controls for adding, removing and arranging pages.

Windows
Windows are encapsulated regions of the screen which contain information and controls. Dialogs are a specific kind of window, which provide an abstract mechanism for presenting actions to the user and responding to the user performing them. Depending on the kind of Dialog, the actions may be arranged and rendered differently, but the interface for managing them is the same.

Examples
There is a more extensive set of examples in the source code repository: First, clone the repo and make it (node.js required), then have a look at.

Creating a button
To create a button, use the  class. The first and only argument to a button's constructor is its configuration. The button is now created, and has a label which reads "Click me!", but is not yet visible to the user, as it must first be attached to the DOM. It can be attached by passing btn.$element to a jQuery DOM manipulation method.

Buttons, like all widgets, mixin EventEmitter. To respond to the button being clicked, attach an event handler to the button's  event. Once the button is attached, the label can be changed using the  method.

Showing a dialog
Dialogs, like all windows, require a window manager. The window manager controls how the window is presented, allowing windows be ignorant of the device being used or the location of the screen being rendered to. A complex application will usually share a window manager or have more than one window manger, each serving a unique purpose.

To create a window manager, use the OO.ui.WindowManager class. By default, a window manager displays windows as modal, overlaying the whole screen. The window manager now needs to be attached to the DOM.

Now the manager is ready for a window. For a simple confirmation dialog, use.

Next add the dialog to the window manager using the  method. Finally, we can show the window using the  method. The promise chain returned by the  method gives you access to every stage of execution throughout the window's lifecycle. See the documentation for OO.ui.WindowManager for more details on the lifecycle of a window.