OOUI/Elements/Groups

Any OOUI widget that contains other widgets (buttons, options, input fields, tools, etc.) mixes in GroupElement. Adding, removing, and clearing items is done through the interface GroupElement provides.

SelectWidgets, which contain mutually exclusive options, are a commonly used example of a class that mixes in GroupElement. ButtonGroupWidgets, which are used when buttons are grouped logically, but are not mutually exclusive, are another example. StackLayouts are yet another example.

All items in a group are addressed by a unique reference. If an item is added to a group that contains an item with the same reference, the existing item will be removed, and the new item will be added to the end of the array of items.

The following example illustrates a ButtonGroupWidget that contains two buttons. Note that the buttons are created, but not appended to the DOM. Instead, they are added to the button group using the widget’s items configuration option. For a full list of supported methods and configuration options, please see the code-level documentation for OO.ui.ButtonGroupWidget.

// Example: A ButtonGroupWidget, which mixes in GroupElement. Other classes
// that mix in GroupElement include SelectWidgets and StackLayouts.

// Create buttons. Note that the buttons will be appended to the DOM later,
// when the group is appended.
var button1 = new OO.ui.PopupButtonWidget( {
  label: 'Select a category',
  icon: 'menu',
  popup: {
    $content: $( '<p>List of categories...</p>' ),
    padded: true,
    align: 'left'
  }
} );
var button2 = new OO.ui.ButtonWidget( {
  label: 'Add item'
})

// Create a new button group and add the buttons to it via the
// ButtonGroupWidget 'items' config option.
var buttonGroup = new OO.ui.ButtonGroupWidget( {
  items: [ button1, button2 ]
} );

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

The GroupElement mixin class provides many methods that can be used to add, remove, or clear widgets from a group. For a full list of supported methods, please see OO.ui.mixin.GroupElement for GroupElement.

Aggregate events

You can invoke a GroupElement's aggregate method to tell it to listen to all its contained items for the event you specify, and in response emit a new event. For example, the ToolGroup uses this to disable itself when all its contained items are disabled. Also, a draggable group element listens to its items' drag and drop events (dragstart, dragend, drop) and emits a synthetic event to reorder its children.