OOUI/Elements/Groups

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

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.