Jump to content

OOUI/Creating interfaces programmatically

From mediawiki.org
Translate this page
Languages:

The OOUI library[1] provides the building blocks for building an object-oriented user interface. It includes many widgets and layouts that are ready to use, as well as basic elements that can be composed to build something of your own. Complex systems, such as windowing and toolbars, are also provided, and can be extended and composed to fit your application’s needs.

User interfaces are created programmatically in OOUI, which abstracts away HTML markup entirely. This technique allows the markup to change, so long as the APIs that generate the markup remain stable. Markup may change when extending a class to support a new feature, or when fixing a bug to increase compatibility.

Everything in OOUI that the user can see is built using elements, which are composed together to form discrete parts of a user interface, and also to bring those parts together. By maximising element reuse, visual, behavioural, and API consistency is easier to maintain.

Getting started

If you are not yet familiar with how interfaces are created with OOUI, this section contains a quick tutorial on how to build a widget using the library.

Creating a widget involves two basic steps:

  1. The widget is created and configured
  2. The widget is added to the DOM[2]

Note that OOUI objects must be added to the DOM before they are visible to the user. Developers writing code should account for the fact that a widget may or may not be attached to the DOM, and will never be attached to the DOM during the execution of the constructor. Even after an element has been attached, it may later become detached. You can check if the element is currently attached using the .isElementAttached() method.

Remember to include the required libraries jQuery and Special:MyLanguage/OOjs as well as the relevant style information (one of the OOUI themes, currently WikimediaUI as default or Apex as alternative) and the OOUI library itself. 

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Things that must be included</title>
    <!-- Include the WikimediaUI theme stylesheet -->
    <link rel="stylesheet" href="resources/lib/ooui/oojs-ui-core-wikimediaui.css">
  </head>
  <body>

    <!-- jQuery -->
    <script src="resources/lib/jquery/jquery.js"></script>

    <!-- OOjs -->
    <script src="resources/lib/oojs/oojs.jquery.js"></script>

    <!-- OOUI -->
    <script src="resources/lib/ooui/oojs-ui-core.js"></script>
    <script src="resources/lib/ooui/oojs-ui-wikimediaui.js"></script>
  </body>
</html>

Creating and configuring a widget

Each widget is created and configured with either a configuration object that is passed to the widget constructor or by using methods to set the configurations (see example below). Many of the library’s methods are chainable, as illustrated in the example.

Once the widget has been created and configured, it must be attached to the DOM in order to be visible to the user. Use the jQuery .append() method to insert the new widget into the DOM using its $element property.

The following example demonstrates how to create and append a simple ButtonWidget that, when clicked, will open “https://www.mediawiki.org” in a new window. button1 is configured using a config object. button2 is configured using the widget’s methods: 

// Example: Creating and configuring a new ButtonWidget with a config object 
// (button1) or ButtonWidget methods (button2), and appending the buttons 
// to the DOM.

// Button 1: Create a new button using the OO.ui.ButtonWidget class.
// Configuration options (the label, href, and target in this example) 
// are specified with a configuration object.
var button1 = new OO.ui.ButtonWidget( { 
  label: 'Click me!', 
  href: 'https://www.mediawiki.org', 
  target: 'new'
} );
// Button 2: Use ButtonWidget methods to configure the button.
// Note that many methods are chainable.
var button2 = new OO.ui.ButtonWidget()
  .setLabel( 'Click me!' )
  .setHref( 'https://www.mediawiki.org' )
  .setTarget( 'new' );
// Append the buttons to the DOM using the $element property and jQuery's .append() method.
$( 'body' ).append( button1.$element, button2.$element );

Note that some get methods (e.g. getItemFromData() or getElementDocument() ) should not be chained. These methods may return ‘null’, and trying to call another method on ‘null’ will cause an error.

Connecting an event handler to a widget

Widgets emit events when they are interacted with or changed in an interesting way. These events can be listened to by connecting event handlers to the widget. The below example uses an event handler to display an alert when the button is clicked. When the button is clicked, its label will be reset to read ‘Do not click me!’ via the button’s setLabel() method. 

// Example: Connecting an event handler to a button.

// Create a new button.
var button3 = new OO.ui.ButtonWidget( { 
  label: 'I handle events' 
} );
// Set up event handlers.
// Use the ButtonWidget's on() method to specify an event (e.g., click) 
// and an event handler.
button3.on( 'click', function () {
  alert( 'I was clicked!' );
  button3.setLabel( 'Do not click me!' );
} );
// Append the button to the DOM.
$( 'body' ).append( button3.$element );

Event handling is provided by the EventEmitter class, which is “mixed in” to all widgets. For more information about EventEmitter, please see OOjs primer.

Understanding mixins

The concept of mixins[3] is fundamental to the library, and many of the library’s elements can be customised via mixin functionality. For example, one can easily add an icon to a button widget by taking advantage of the fact that the IconElement class is mixed in to the ButtonWidget class.

Example: . 

// Create a new button and add an icon using the configuration option provided 
// by the IconElement class.
var button4 = new OO.ui.ButtonWidget( { 
  label: 'Button with icon', 
  icon: 'alert'
} );

// Append the button to the DOM.
$( 'body' ).append( button4.$element );

Mixin classes can be used to create and add new elements to a widget (such as the icon in the above example) or to add new behaviours (such as new methods for handling styling flags or titles).

There are three kinds of element mixins, each identified with a naming convention:

  • Content — Content mixins generate elements by default (e.g., groups, icons, indicators and labels). The names of content mixins have no suffix (e.g., GroupElement, IconElement, etc.)
  • Attribute — Attribute mixins operate on $element by default (e.g., flags and titles). The names of attribute mixins have an "ed" suffix (e.g., FlaggedElement, TitledElement, etc.)
  • Behaviour — Behaviour mixins operate on $element by default (e.g., clippable). Behaviour mixins are identified with an ”able" suffix (e.g., ClippableElement, etc.)

Note that though a mixin class can create and initialise an object, it will not append it to the DOM. This must be done manually if you wish to manipulate the object directly.

It is not uncommon to see widgets composed of multiple mixins: for example, the ButtonWidget class utilises ButtonElement and IconElement mixins (and a few others). One can easily see which classes have been mixed and are available in the code-level documentation for each class. Mixin classes will always be displayed in the upper right of the documentation screen for each class. In addition, each configuration option notes the name of the class that defines it.

References

  1. ↑ OOUI (Object-Oriented User Interface)
  2. ↑ DOM (Document Object Model)
  3. ↑ mixin (en)


Retrieved from "https://www.mediawiki.org/w/index.php?title=OOUI/Creating_interfaces_programmatically/en&oldid=6734264"