ui/dropdown/utils

Adds an instance of ListView to a dropdown.

const items = new Collection<ListDropdownItemDefinition>();

items.add( {
	type: 'button',
	model: new Model( {
		withText: true,
		label: 'First item',
		labelStyle: 'color: red'
	} )
} );

items.add( {
	 type: 'button',
	 model: new Model( {
		withText: true,
		label: 'Second item',
		labelStyle: 'color: green',
		class: 'foo'
	} )
} );

const dropdown = createDropdown( locale );

addListToDropdown( dropdown, items );

// Will render a dropdown with a list in the panel containing two items.
dropdown.render()
document.body.appendChild( dropdown.element );

The items collection passed to this methods controls the presence and attributes of respective list items.

Note: To improve the accessibility, when a list is added to the dropdown using this helper the dropdown will automatically attempt to focus the first active item (a host to a ButtonView with isOn set true) or the very first item when none are active.

Note: List view will be created on first open of the dropdown.

See createDropdown and List.

Parameters

dropdownView : DropdownView

A dropdown instance to which ListVIew will be added.

itemsOrCallback : Collection<ListDropdownItemDefinition> | () => Collection<ListDropdownItemDefinition>

A collection of the list item definitions or a callback returning a list item definitions to populate the list.

options : object

Properties

[ options.ariaLabel ] : string

Label used by assistive technologies to describe list element.

[ options.role ] : string

Will be reflected by the role DOM attribute in ListVIew and used by assistive technologies.

Defaults to {}

Returns

void

Adds a menu UI component to a dropdown and sets all common behaviors and interactions between the dropdown and the menu.

Use this helper to create multi-level dropdown menus that are displayed in a toolbar.

Internally, it creates an instance of DropdownMenuRootListView.

Example:

const definitions = [
	{
		id: 'menu_1',
		menu: 'Menu 1',
		children: [
			{
				id: 'menu_1_a',
				label: 'Item A'
			},
			{
				id: 'menu_1_b',
				label: 'Item B'
			}
		]
	},
	{
		id: 'top_a',
		label: 'Top Item A'
	},
	{
		id: 'top_b',
		label: 'Top Item B'
	}
];

const dropdownView = createDropdown( editor.locale );

addMenuToDropdown( dropdownView, editor.ui.view.body, definitions );

After using this helper, the dropdown will fire execute event when a nested menu button is pressed.

The helper will make sure that the dropdownMenuRootListView is lazy loaded, i.e., the menu component structure will be initialized and rendered only after the dropdown is opened for the first time.

Parameters

dropdownView : DropdownView

A dropdown instance to which the menu component will be added.

body : BodyCollection

Body collection to which floating menu panels will be added.

definition : DropdownMenuDefinition

The menu component definition.

options : object

Properties

[ options.ariaLabel ] : string

Label used by assistive technologies to describe the top-level menu.

Defaults to {}

Returns

void

Adds an instance of ToolbarView to a dropdown.

const buttonsCreator = () => {
	const buttons = [];

	// Either create a new ButtonView instance or create existing.
	buttons.push( new ButtonView() );
	buttons.push( editor.ui.componentFactory.create( 'someButton' ) );
};

const dropdown = createDropdown( locale );

addToolbarToDropdown( dropdown, buttonsCreator, { isVertical: true } );

// Will render a vertical button dropdown labeled "A button dropdown"
// with a button group in the panel containing two buttons.
// Buttons inside the dropdown will be created on first dropdown panel open.
dropdown.render()
document.body.appendChild( dropdown.element );

Note: To improve the accessibility, you can tell the dropdown to focus the first active button of the toolbar when the dropdown gets open. See the documentation of options to learn more.

Note: Toolbar view will be created on first open of the dropdown.

See createDropdown and ToolbarView.

Parameters

dropdownView : DropdownView

A dropdown instance to which ToolbarView will be added.

buttonsOrCallback : ViewCollection<View<HTMLElement>> | Array<View<HTMLElement>> | () => ( ViewCollection<View<HTMLElement>> | Array<View<HTMLElement>> )

options : object

Properties

[ options.ariaLabel ] : string

Label used by assistive technologies to describe toolbar element.

[ options.class ] : string

An additional CSS class added to the toolbar element.

[ options.enableActiveItemFocusOnDropdownOpen ] : boolean

When set true, the focus will automatically move to the first active item of the toolbar upon opening the dropdown. Active items are those with the isOn property set true (for instance buttons). If no active items is found, the toolbar will be focused as a whole resulting in the focus moving to its first focusable item (default behavior of DropdownView).

[ options.isCompact ] : boolean

When set true, makes the toolbar look compact with toolbar element.

[ options.isVertical ] : boolean

Controls the orientation of toolbar items.

[ options.maxWidth ] : string

The maximum width of the toolbar element. Details: maxWidth.

Defaults to {}

Returns

void

A helper for creating dropdowns. It creates an instance of a dropdown, with a button, panel and all standard dropdown's behaviors.

Creating dropdowns

By default, the default DropdownButtonView class is used as definition of the button:

const dropdown = createDropdown( model );

// Configure dropdown's button properties:
dropdown.buttonView.set( {
	label: 'A dropdown',
	withText: true
} );

dropdown.render();

// Will render a dropdown labeled "A dropdown" with an empty panel.
document.body.appendChild( dropdown.element );

You can also provide other button views (they need to implement the DropdownButton interface). For instance, you can use SplitButtonView to create a dropdown with a split button.

const dropdown = createDropdown( locale, SplitButtonView );

// Configure dropdown's button properties:
dropdown.buttonView.set( {
	label: 'A dropdown',
	withText: true
} );

dropdown.buttonView.on( 'execute', () => {
	// Add the behavior of the "action part" of the split button.
	// Split button consists of the "action part" and "arrow part".
	// The arrow opens the dropdown while the action part can have some other behavior.
} );

dropdown.render();

// Will render a dropdown labeled "A dropdown" with an empty panel.
document.body.appendChild( dropdown.element );

Adding content to the dropdown's panel

The content of the panel can be inserted directly into the dropdown.panelView.element:

dropdown.panelView.element.textContent = 'Content of the panel';

However, most of the time you will want to add there either a list of options or a list of buttons (i.e. a toolbar). To simplify the task, you can use, respectively, addListToDropdown or addToolbarToDropdown utils.

Parameters

locale : undefined | Locale

The locale instance.

ButtonClassOrInstance : object | new ( locale: Locale ) => object

The dropdown button view class. Needs to implement the DropdownButton interface.

Defaults to DropdownButtonView

Returns

DropdownView

The dropdown view instance.

A helper to be used on an existing DropdownView that focuses a specific child in DOM when the dropdown gets open.

Parameters

dropdownView : DropdownView

A dropdown instance to which the focus behavior will be added.

childSelectorCallback : () => ( View<HTMLElement> | FalsyValue )

A callback executed when the dropdown gets open. It should return a View instance (child of panelView) that will get focused or a falsy value. If falsy value is returned, a default behavior of the dropdown will engage focusing the first focusable child in the panelView.

Returns

void