OOUI/OOjs primer

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.