OOUI/OOjs primer

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

The OOUI library is based on the event model provided by OOjs . If you are not familiar with OOjs, you may wish to take a moment to familiarize yourself with its EventEmitter, as it is a convenient and powerful tool that will often be used in examples.

EventEmitter allows event handlers to be connected to an object, called when events occur, and disconnected when no longer needed. Events are tied to their context. For example, when a toggle button changes state, the event is not simply ‘change,’ but ‘change’ and the value of the toggle button’s state ( ‘on’ or ‘off’).

The most basic way to connect and disconnect an event handler is with the EventEmitter’s on() and off() methods. In the following example, the on() method is used to connect an onChange event handler to a toggle button, which is defined in the example as well.

// The following example uses the on() method to connect an event handler 
// to a toggle button widget. The off() method is later used to disconnect
// the event handler.

// Create a new toggle button
var button = new OO.ui.ToggleButtonWidget( { 
  label: 'I handle events' 
} );
// Set up the event handler. In this example, the event handler is a 
// function that will change the button label to 'All done!' when the 
// state of the button changes. The off() method is then used to 
// disconnect the event handler from the toggle button so that the 
// function will no longer be called.
button.onChange = function () {
  button.setLabel( 'All done!' );
  button.off( 'change', button.onChange );
} 
// Use the ButtonWidget's on() method to connect an event handler 
// ('button.onChange', defined above) to the button for the specified 
// type of event ('change'). 
button.on( 'change', button.onChange );
// Append the button to the DOM.
$( 'body' ).append( button.$element );

Often, the connect() and disconnect() methods are used to connect and disconnect multiple event handlers to objects. The following example illustrates these methods.

// This example illustrates the connect() and disconnect() methods.
// Here, the 'onChange' function, which changes the label of the toggle button
// labeled 'try me!' to match the button's state ('on' or 'off') will be
// executed whenever the state of the toggle button changes. The 'onToggleClick'
// function, which writes 'Click!' each time the toggle button is clicked, is
// also connected to the toggle button via the connect() method. The
// disconnect() method, connected to the 'Disconnect EventHandlers' button,
// is used to remove both event handlers from the toggle button.

// Create buttons and add them to a button group.
var toggle = new OO.ui.ToggleButtonWidget( {
  label: 'try me!'
} );

var button = new OO.ui.ButtonWidget( {
  label: 'Disconnect EventHandlers'
} );

var buttonGroup = new OO.ui.ButtonGroupWidget( {
  items: [ toggle, button ]
} );

// Define the functions to connect (toggle.onChange, toggle.onToggleClick, and
// button.onClick, in this example)

toggle.onChange = function () {
  if ( toggle.getValue() === false ) {
    toggle.setLabel( 'off' );
  } else {
    toggle.setLabel( 'on' );
  }
};

toggle.onToggleClick = function () {
  $( 'body' ).append( '<p>Click!</p>' );
};

button.onClick = function () {
  toggle.disconnect( toggle, {
    change: 'onChange',
    click: 'onToggleClick'
  } );
};

// Bind the functions to the widgets for the specified events.

toggle.connect( toggle, {
  change: 'onChange',
  click: 'onToggleClick'
} );

button.connect( button, {
  click: 'onClick'
} );

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

A convention of OOjs is that any method that begins with "on" (e.g., onClick() and onKeyPress()) is private, except for the on() method itself.

For more details about EventEmitter, please see OOjs/Events.