Module

ui/dropdown/utils

@ckeditor/ckeditor5-ui/src/dropdown/utils

module

Filtering

Type Definitions

Functions

  • addListToDropdown( dropdownView, itemsOrCallback, options = { [options.ariaLabel], [options.role] } ) → void

    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 : default

    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
  • addToolbarToDropdown( dropdownView, buttonsOrCallback, options = { [options.ariaLabel], [options.class], [options.enableActiveItemFocusOnDropdownOpen], [options.isCompact], [options.isVertical], [options.maxWidth] } ) → 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 : default

    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
  • createDropdown( locale, ButtonClassOrInstance ) → DropdownView

    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 ) => object

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

    Defaults to DropdownButtonView

    Returns

    DropdownView

    The dropdown view instance.

  • focusChildOnDropdownOpen( dropdownView, childSelectorCallback ) → void

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

    Parameters

    dropdownView : default

    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