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.

Creating a dialog
Dialogs can be used to communicate a message or facilitate a process. In the former case, it is possible but usually not necessary to subclass. In the latter case it is always necessary to create a subclass of. Dialogs usually provide a set of actions the user may take at any time. These actions are specified statically, but which actions are visible and enabled dynamically controlled, as seen later. When a dialog is instantiated, it is not yet ready for it's contents to be populated. Just before it is opened for the first time, the contents are populated when the initialize method is called by the window manager. This is the appropriate time to add content to the dialog's, initialize widgets and setup event handlers. Each time the dialog is opened, the data passed into the window manager's openWindow method is used to allow the dialog to setup its contents based on that data. The  method is used to assemble a chain of callbacks which will be executed in order. See the documentation for OO.ui.Process for more details on how they can be used to assemble and execute both synchronous and asynchronous sequences of callbacks. Setting the mode of the actions object will only show items which are configured to be visible in that mode. See the documentation for OO.ui.ActionSet for more details on how actions can be dynamically controlled. When an action is taken by the user, the dialog generates a process to handle the action. The default handler closes the dialog when the empty action is taken, in this case the cancel button which did not define an action property, and does nothing in all other cases. To handle a specific action, override the  method and provide an alternative process when appropriate. To perform actions whenever the dialog is closed, the  method can be overridden. It works similarly to the getSetupProcess method, but provides access to data passed into the  method of the dialog or the   method of its window manager.

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. You can also instantiate your own dialogs, or use the generic  class for communicating simple messages.

Next add the dialogs to the window manager using the  method. Finally, we can show one of our dialogs using the  method of the window manager. For a generic message dialog, which generally doesn't need to be subclassed, the configuration is provided at the time of opening the dialog. The promise chain returned by  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.