Modules (181)

DropdownButton

Description

Button that opens a dropdown list when clicked. More akin to a popup menu than a combobox. Compared to a simple <select> element:

  • There's no "selected" state
  • The button's label is not automatically changed when an item in the list is clicked
  • Its width is not the max of all the dropdown items' labels
  • The button & dropdown's appearance can be customized far more Events
  • listRendered -- This event is dispatched after the entire list is rendered so that custom event handlers can be
                set up for any custom UI in the list.
    

TODO: merge DropdownEventHandler into this? Are there any other widgets that might want to use it separately?

Dependencies

Functions

Public API

DropdownButton

Creates a single dropdown-button instance. The DOM node is created but not attached to the document anywhere - clients should append this.$button to the appropriate location.

DropdownButton dispatches the following events:

  • "select" - when an option in the dropdown is clicked. Passed item object and index.
label
non-nullable
string
Label to display on the button
items
non-nullable
Array.<*>
Items in the dropdown list. It generally doesn't matter what type/value the items have, except that any item === "---" will be treated as a divider. Such items are not clickable and itemRenderer() will not be called for them.
itemRenderer
nullable
function(*, number):!string, {html:string, enabled:boolean
Optional function to convert a single item to HTML (see itemRenderer() docs below). If not provided, items are assumed to be plain text strings.
    function DropdownButton(label, items, itemRenderer) {
        this.items = items;

        this.itemRenderer = itemRenderer || this.itemRenderer;

        this._onClick        = this._onClick.bind(this);
        this.closeDropdown   = this.closeDropdown.bind(this);
        this._onClickOutside = this._onClickOutside.bind(this);

        this.$button = $("<button class='btn btn-dropdown'/>")
            .text(label)
            .on("click", this._onClick);
    }
    EventDispatcher.makeEventDispatcher(DropdownButton.prototype);