Module

ui/dropdown/utils

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

module

Filtering

Type Definitions

Functions

  • addListToDropdown( dropdownView, items )

    Adds an instance of ListView to a dropdown.

    const items = new Collection();
    
    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.

    See createDropdown and List.

    Parameters

    dropdownView : DropdownView

    A dropdown instance to which ListVIew will be added.

    items : Iterable.<ListDropdownItemDefinition>

    A collection of the list item definitions to populate the list.

  • addToolbarToDropdown( dropdownView, buttons )

    Adds an instance of ToolbarView to a dropdown.

    const buttons = [];
    
    // Either create a new ButtonView instance or create existing.
    buttons.push( new ButtonView() );
    buttons.push( editor.ui.componentFactory.get( 'someButton' ) );
    
    const dropdown = createDropdown( locale );
    
    addToolbarToDropdown( dropdown, buttons );
    
    dropdown.toolbarView.isVertical = true;
    
    // Will render a vertical button dropdown labeled "A button dropdown"
    // with a button group in the panel containing two buttons.
    dropdown.render()
    document.body.appendChild( dropdown.element );
    

    See createDropdown and ToolbarView.

    Parameters

    dropdownView : DropdownView

    A dropdown instance to which ToolbarView will be added.

    buttons : Iterable.<ButtonView>
  • createDropdown( locale, ButtonClass ) → 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( model, 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 : Locale

    The locale instance.

    ButtonClass : function

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

    Returns

    DropdownView

    The dropdown view instance.