#

API Docs for: 3.10.3
Show: Inherited Protected Private Deprecated

# WidgetButtons Class

Defined in: `widget-buttons/js/widget-buttons.js:29`
Module: widget-buttons

Available since 3.4.0

Provides header/body/footer button support for Widgets that use the `WidgetStdMod` extension.

This Widget extension makes it easy to declaratively configure a widget's buttons. It adds a `buttons` attribute along with button- accessor and mutator methods. All button nodes have the `Y.Plugin.Button` plugin applied.

This extension also includes `HTML_PARSER` support to seed a widget's `buttons` from those which already exist in its DOM.

- Index
- Methods
- Properties
- Attributes

## Item Index

### Methods

- _afterButtonsChange
- _afterContentChangeButtons
- _afterDefaultButtonChange
- _afterVisibleChangeButtons
- _bindUIButtons
- _createButton
- _getButtonContainer
- _getButtonDefault
- _getButtonName
- _getButtons
- _mapButton
- _mapButtons
- _mergeButtonConfig
- _parseButtons
- _setButtons
- _syncUIButtons
- _uiInsertButton
- _uiRemoveButton
- _uiSetButtons
- _uiSetDefaultButton
- _uiSetVisibleButtons
- _unMapButton
- _updateContentButtons
- _updateDefaultButton
- addButton
- getButton
- removeButton

### Properties

- _buttonsHandles
- _buttonsMap
- _defaultButton
- BUTTONS
- BUTTONS_TEMPLATE
- CLASS_NAMES static
- DEFAULT_BUTTONS_SECTION
- NON_BUTTON_NODE_CFG static

### Attributes

- buttons
- defaultButton

## Methods

### `_afterButtonsChange`

(

- `e`

)
protected

Defined in `widget-buttons/js/widget-buttons.js:1188`

Available since 3.4.0

Handles this widget's `buttonsChange` event which fires anytime the `buttons` attribute is modified.

Note: This method special-cases the `buttons` modifications caused by `addButton()` and `removeButton()`, both of which set the `src` property on the event facade to "add" and "remove" respectively.

#### Parameters:

- `e` EventFacade

### `_afterContentChangeButtons`

(

- `e`

)
protected

Defined in `widget-buttons/js/widget-buttons.js:1237`

Available since 3.5.0

Handles this widget's `headerContentChange`, `bodyContentChange`, `footerContentChange` events by making sure the `buttons` remain rendered after changes to the content areas.

These events are very chatty, so extra caution is taken to avoid doing extra work or getting into an infinite loop.

#### Parameters:

- `e` EventFacade

### `_afterDefaultButtonChange`

(

- `e`

)
protected

Defined in `widget-buttons/js/widget-buttons.js:1261`

Available since 3.5.0

Handles this widget's `defaultButtonChange` event by adding the "yui3-button-primary" CSS class to the new `defaultButton` and removing it from the old default button.

#### Parameters:

- `e` EventFacade

### `_afterVisibleChangeButtons`

(

- `e`

)
protected

Defined in `widget-buttons/js/widget-buttons.js:1275`

Available since 3.5.0

Handles this widget's `visibleChange` event by focusing the `defaultButton` if there is one.

#### Parameters:

- `e` EventFacade

### `_bindUIButtons`

() protected

Defined in `widget-buttons/js/widget-buttons.js:496`

Available since 3.4.0

Binds UI event listeners. This method is inserted via AOP, and will execute after `bindUI()`.

### `_createButton`

(

- `button`

)
Node protected

Defined in `widget-buttons/js/widget-buttons.js:516`

Available since 3.5.0

Returns a button node based on the specified `button` node or configuration.

The button node will either be created via `Y.Plugin.Button.createNode()`, or when `button` is specified as a node already, it will by `plug()`ed with `Y.Plugin.Button`.

#### Parameters:

- `button` Node | Object

  Button node or configuration object.

#### Returns:

Node: The button node.

### `_getButtonContainer`

(

- `section`
- `create`

)
Node protected

Defined in `widget-buttons/js/widget-buttons.js:581`

Available since 3.5.0

Returns the buttons container for the specified `section`, passing a truthy value for `create` will create the node if it does not already exist.

Note: It is up to the caller to properly insert the returned container node into the content section.

#### Parameters:

- `section` String

  The `WidgetStdMod` section (header/body/footer).

- `create` Boolean

  Whether the buttons container should be created if it does not already exist.

#### Returns:

Node: The buttons container node for the specified `section`.

### `_getButtonDefault`

(

- `button`

)
Boolean protected

Defined in `widget-buttons/js/widget-buttons.js:616`

Available since 3.5.0

Returns whether or not the specified `button` is configured to be the default button.

When a button node is specified, the button's `getData()` method will be used to determine if the button is configured to be the default. When a button config object is specified, the `isDefault` prop will determine whether the button is the default.

Note: `<button data-default="true"></button>` is supported via the `button.getData('default')` API call.

#### Parameters:

- `button` Node | Object

  The button node or configuration object.

#### Returns:

Boolean: Whether the button is configured to be the default button.

### `_getButtonName`

(

- `button`

)
String protected

Defined in `widget-buttons/js/widget-buttons.js:645`

Available since 3.5.0

Returns the name of the specified `button`.

When a button node is specified, the button's `getData('name')` method is preferred, but will fallback to `get('name')`, and the result will determine the button's name. When a button config object is specified, the `name` prop will determine the button's name.

Note: `<button data-name="foo"></button>` is supported via the `button.getData('name')` API call.

#### Parameters:

- `button` Node | Object

  The button node or configuration object.

#### Returns:

String: The name of the button.

### `_getButtons`

(

- `buttons`

)
Object protected

Defined in `widget-buttons/js/widget-buttons.js:674`

Available since 3.5.0

Getter for the `buttons` attribute. A copy of the `buttons` object is returned so the stored state cannot be modified by the callers of `get('buttons')`.

This will recreate a copy of the `buttons` object, and each section array (the button nodes are not copied/cloned.)

#### Parameters:

- `buttons` Object

  The widget's current `buttons` state.

#### Returns:

Object: A copy of the widget's current `buttons` state.

### `_mapButton`

(

- `button`
- `section`

)
protected

Defined in `widget-buttons/js/widget-buttons.js:700`

Available since 3.5.0

Adds the specified `button` to the buttons map (both name -> button and section:name -> button), and sets the button as the default if it is configured as the default button.

Note: If two or more buttons are configured with the same `name` and/or configured to be the default button, the last one wins.

#### Parameters:

- `button` Node

  The button node to map.

- `section` String

  The `WidgetStdMod` section (header/body/footer).

### `_mapButtons`

(

- `buttons`

)
protected

Defined in `widget-buttons/js/widget-buttons.js:730`

Available since 3.5.0

Adds the specified `buttons` to the buttons map (both name -> button and section:name -> button), and set the a button as the default if one is configured as the default button.

Note: This will clear all previous button mappings and null-out any previous default button! If two or more buttons are configured with the same `name` and/or configured to be the default button, the last one wins.

#### Parameters:

- `buttons` Node[]

  The button nodes to map.

### `_mergeButtonConfig`

(

- `config`

)
Object protected

Defined in `widget-buttons/js/widget-buttons.js:757`

Available since 3.5.0

Returns a copy of the specified `config` object merged with any defaults provided by a `srcNode` and/or a predefined configuration for a button with the same `name` on the `BUTTONS` property.

#### Parameters:

- `config` Object | String

  Button configuration object, or string name.

#### Returns:

Object: A copy of the button configuration object merged with any defaults.

### `_parseButtons`

(

- `srcNode`

)
Null | Object protected

Defined in `widget-buttons/js/widget-buttons.js:806`

Available since 3.5.0

`HTML_PARSER` implementation for the `buttons` attribute.

Note: To determine a button node's name its `data-name` and `name` attributes are examined. Whether the button should be the default is determined by its `data-default` attribute.

#### Parameters:

- `srcNode` Node

  This widget's srcNode to search for buttons.

#### Returns:

Null | Object: `buttons` Config object parsed from this widget's DOM.

### `_setButtons`

(

- `config`

)
Object protected

Defined in `widget-buttons/js/widget-buttons.js:847`

Available since 3.5.0

Setter for the `buttons` attribute. This processes the specified `config` and returns a new `buttons` object which is stored as the new state; leaving the original, specified `config` unmodified.

The button nodes will either be created via `Y.Plugin.Button.createNode()`, or when a button is already a Node already, it will by `plug()`ed with `Y.Plugin.Button`.

#### Parameters:

- `config` Array | Object

  The `buttons` configuration to process.

#### Returns:

Object: The processed `buttons` object which represents the new state.

### `_syncUIButtons`

() protected

Defined in `widget-buttons/js/widget-buttons.js:903`

Available since 3.4.0

Syncs this widget's current button-related state to its DOM. This method is inserted via AOP, and will execute after `syncUI()`.

### `_uiInsertButton`

(

- `button`
- `section`
- `index`

)
protected

Defined in `widget-buttons/js/widget-buttons.js:917`

Available since 3.5.0

Inserts the specified `button` node into this widget's DOM at the specified `section` and `index` and updates the section content.

The section and button container nodes will be created if they do not already exist.

#### Parameters:

- `button` Node

  The button node to insert into this widget's DOM.

- `section` String

  The `WidgetStdMod` section (header/body/footer).

- `index` Number

  Index at which the `button` should be positioned.

### `_uiRemoveButton`

(

- `button`
- `section`
- `[options]`

)
protected

Defined in `widget-buttons/js/widget-buttons.js:943`

Available since 3.5.0

Removes the button node from this widget's DOM and detaches any event subscriptions on the button that were created by this widget. The section content will be updated unless `{preserveContent: true}` is passed in the `options`.

By default the button container node will be removed when this removes the last button of the specified `section`; and if no other content remains in the section node, it will also be removed.

#### Parameters:

- `button` Node

  The button to remove and destroy.

- `section` String

  The `WidgetStdMod` section (header/body/footer).

- `[options]` Object optional

  Additional options.

  - `[preserveContent=false]` Boolean optional

    Whether the section content should be updated.

### `_uiSetButtons`

(

- `buttons`

)
protected

Defined in `widget-buttons/js/widget-buttons.js:993`

Available since 3.5.0

Sets the current `buttons` state to this widget's DOM by rendering the specified collection of `buttons` and updates the contents of each section as needed.

Button nodes which already exist in the DOM will remain intact, or will be moved if they should be in a new position. Old button nodes which are no longer represented in the specified `buttons` collection will be removed, and any event subscriptions on the button which were created by this widget will be detached.

If the button nodes in this widget's DOM actually change, then each content section will be updated (or removed) appropriately.

#### Parameters:

- `buttons` Object

  The current `buttons` state to visually represent.

### `_uiSetDefaultButton`

(

- `newButton`
- `oldButton`

)
protected

Defined in `widget-buttons/js/widget-buttons.js:1077`

Available since 3.5.0

Adds the "yui3-button-primary" CSS class to the new `defaultButton` and removes it from the old default button.

#### Parameters:

- `newButton` Node

  The new `defaultButton`.

- `oldButton` Node

  The old `defaultButton`.

### `_uiSetVisibleButtons`

(

- `visible`

)
protected

Defined in `widget-buttons/js/widget-buttons.js:1094`

Available since 3.5.0

Focuses this widget's `defaultButton` if there is one and this widget is visible.

#### Parameters:

- `visible` Boolean

  Whether this widget is visible.

### `_unMapButton`

(

- `button`
- `section`

)
protected

Defined in `widget-buttons/js/widget-buttons.js:1112`

Available since 3.5.0

Removes the specified `button` from the buttons map (both name -> button and section:name -> button), and nulls-out the `defaultButton` if it is currently the default button.

#### Parameters:

- `button` Node

  The button node to remove from the buttons map.

- `section` String

  The `WidgetStdMod` section (header/body/footer).

### `_updateContentButtons`

(

- `section`

)
protected

Defined in `widget-buttons/js/widget-buttons.js:1164`

Available since 3.5.0

Updates the content attribute which corresponds to the specified `section`.

The method updates the section's content to its current `childNodes` (text and/or HTMLElement), or will null-out its contents if the section is empty. It also specifies a `src` of `buttons` on the change event facade.

#### Parameters:

- `section` String

  The `WidgetStdMod` section (header/body/footer) to update.

### `_updateDefaultButton`

() protected

Defined in `widget-buttons/js/widget-buttons.js:1148`

Available since 3.5.0

Updates the `defaultButton` attribute if it needs to be updated by comparing its current value with the protected `_defaultButton` property.

### `addButton`

(

- `button`
- `[section="footer"]`
- `[index]`

)
chainable

Defined in `widget-buttons/js/widget-buttons.js:284`

Available since 3.4.0

Adds a button to this widget.

The new button node will have the `Y.Plugin.Button` plugin applied, be added to this widget's `buttons`, and rendered in the specified `section` at the specified `index` (or end of the section when no `index` is provided). If the section does not exist, it will be created.

This fires the `buttonsChange` event and adds the following properties to the event facade:

- `button`: The button node or config object to add.

- `section`: The `WidgetStdMod` section (header/body/footer) where the button will be added.

- `index`: The index at which the button will be in the section.

- `src`: "add"

Note: The `index` argument will be passed to the Array `splice()` method, therefore a negative value will insert the `button` that many items from the end. The `index` property on the `buttonsChange` event facade is the index at which the `button` was added.

#### Parameters:

- `button` Node | Object | String

  The button to add. This can be a `Y.Node` instance, config Object, or String name for a predefined button on the `BUTTONS` prototype property. When a config Object is provided, it will be merged with any defaults provided by any `srcNode` and/or a button with the same `name` defined on the `BUTTONS` property. The following are the possible configuration properties beyond what Node plugins accept by default:

  - `[action]` Function | String optional

    The default handler that should be called when the button is clicked. A String name of a Function that exists on the `context` object can also be provided. Note: Specifying a set of `events` will override this setting.

  - `[classNames]` String | String[] optional

    Additional CSS classes to add to the button node.

  - `[context=this]` Object optional

    Context which any `events` or `action` should be called with. Defaults to `this`, the widget. Note: `e.target` will access the button node in the event handlers.

  - `[disabled=false]` Boolean optional

    Whether the button should be disabled.

  - `[events="click"]` String | Object optional

    Event name, or set of events and handlers to bind to the button node. See: `Y.Node.on()`, this value is passed as the first argument to `on()`.

  - `[isDefault=false]` Boolean optional

    Whether the button is the default button.

  - `[label]` String optional

    The visible text/value displayed in the button.

  - `[name]` String optional

    A name which can later be used to reference this button. If a button is defined on the `BUTTONS` property with this same name, its configuration properties will be merged in as defaults.

  - `[section]` String optional

    The `WidgetStdMod` section (header, body, footer) where the button should be added.

  - `[srcNode]` Node optional

    An existing Node to use for the button, default values will be seeded from this node, but are overriden by any values specified in the config object. By default a new <button> node will be created.

  - `[template]` String optional

    A specific template to use when creating a new button node (e.g. "<a />"). Note: Specifying a `srcNode` will overide this.

- `[section="footer"]` String optional

  The `WidgetStdMod` section (header/body/footer) where the button should be added. This takes precedence over the `button.section` configuration property.

- `[index]` Number optional

  The index at which the button should be inserted. If not specified, the button will be added to the end of the section. This value is passed to the Array `splice()` method, therefore a negative value will insert the `button` that many items from the end.

### `getButton`

(

- `name`
- `[section="footer"]`

)
Node

Defined in `widget-buttons/js/widget-buttons.js:388`

Available since 3.5.0

Returns a button node from this widget's `buttons`.

#### Parameters:

- `name` Number | String

  The string name or index of the button.

- `[section="footer"]` String optional

  The `WidgetStdMod` section (header/body/footer) where the button exists. Only applicable when looking for a button by numerical index, or by name but scoped to a particular section.

#### Returns:

Node: The button node.

### `removeButton`

(

- `button`
- `[section="footer"]`

)
chainable

Defined in `widget-buttons/js/widget-buttons.js:418`

Available since 3.5.0

Removes a button from this widget.

The button will be removed from this widget's `buttons` and its DOM. Any event subscriptions on the button which were created by this widget will be detached. If the content section becomes empty after removing the button node, then the section will also be removed.

This fires the `buttonsChange` event and adds the following properties to the event facade:

- `button`: The button node to remove.

- `section`: The `WidgetStdMod` section (header/body/footer) where the button should be removed from.

- `index`: The index at which the button exists in the section.

- `src`: "remove"

#### Parameters:

- `button` Node | Number | String

  The button to remove. This can be a `Y.Node` instance, index, or String name of a button.

- `[section="footer"]` String optional

  The `WidgetStdMod` section (header/body/footer) where the button exists. Only applicable when removing a button by numerical index, or by name but scoped to a particular section.

## Properties

### `_buttonsHandles`

Object protected

Defined in `widget-buttons/js/widget-buttons.js:225`

Available since 3.5.0

A map of button node `_yuid` -> event-handle for all button nodes which were created by this widget.

### `_buttonsMap`

Object protected

Defined in `widget-buttons/js/widget-buttons.js:235`

Available since 3.5.0

A map of this widget's `buttons`, both name -> button and section:name -> button.

### `_defaultButton`

Node protected

Defined in `widget-buttons/js/widget-buttons.js:245`

Available since 3.5.0

Internal reference to this widget's default button.

### `BUTTONS`

Object

Defined in `widget-buttons/js/widget-buttons.js:186`

Available since 3.5.0

Collection of predefined buttons mapped by name -> config.

These button configurations will serve as defaults for any button added to a widget's buttons which have the same `name`.

See `addButton()` for a list of possible configuration values.

Default: {}

### `BUTTONS_TEMPLATE`

String

Defined in `widget-buttons/js/widget-buttons.js:202`

Available since 3.5.0

The HTML template to use when creating the node which wraps all buttons of a section. By default it will have the CSS class: "yui3-widget-buttons".

Default: "<span />"

### `CLASS_NAMES`

Object static

Defined in `widget-buttons/js/widget-buttons.js:150`

Available since 3.5.0

CSS classes used by `WidgetButtons`.

### `DEFAULT_BUTTONS_SECTION`

String

Defined in `widget-buttons/js/widget-buttons.js:213`

Available since 3.5.0

The default section to render buttons in when no section is specified.

Default: Y.WidgetStdMod.FOOTER

### `NON_BUTTON_NODE_CFG`

Array static

Defined in `widget-buttons/js/widget-buttons.js:170`

Available since 3.5.0

The list of button configuration properties which are specific to `WidgetButtons` and should not be passed to `Y.Plugin.Button.createNode()`.

## Attributes

### `buttons`

Object

Defined in `widget-buttons/js/widget-buttons.js:55`

Available since 3.4.0

Collection containing a widget's buttons.

The collection is an Object which contains an Array of `Y.Node`s for every `WidgetStdMod` section (header, body, footer) which has one or more buttons. All button nodes have the `Y.Plugin.Button` plugin applied.

This attribute is very flexible in the values it will accept. `buttons` can be specified as a single Array, or an Object of Arrays keyed to a particular section.

All specified values will be normalized to this type of structure:

    {
        header: [...],
        footer: [...]
    }

A button can be specified as a `Y.Node`, config Object, or String name for a predefined button on the `BUTTONS` prototype property. When a config Object is provided, it will be merged with any defaults provided by a button with the same `name` defined on the `BUTTONS` property.

See `addButton()` for the detailed list of configuration properties.

For convenience, a widget's buttons will always persist and remain rendered after header/body/footer content updates. Buttons should be removed by updating this attribute or using the `removeButton()` method.

Default: {}

#### Fires event `buttonsChange`

Fires when the value for the configuration attribute `buttons` is changed. You can listen for the event using the `on` method if you wish to be notified before the attribute's value has changed, or using the `after` method if you wish to be notified after the attribute's value has changed.

#### Parameters:

- `e` EventFacade
  An Event Facade object with the following attribute-specific properties added:
  - `prevVal` Any
    The value of the attribute, prior to it being set.
  - `newVal` Any
    The value the attribute is to be set to.
  - `attrName` String
    The name of the attribute being set.
  - `subAttrName` String
    If setting a property within the attribute's value, the name of the sub-attribute property being set.

#### Example:

    {
        // Uses predefined "close" button by string name.
        header: ['close'],

        footer: [
            {
                name  : 'cancel',
                label : 'Cancel',
                action: 'hide'
            },

            {
                name     : 'okay',
                label    : 'Okay',
                isDefault: true,

                events: {
                    click: function (e) {
                        this.hide();
                    }
                }
            }
        ]
    }

### `defaultButton`

Node readonly

Defined in `widget-buttons/js/widget-buttons.js:121`

Available since 3.5.0

The current default button as configured through this widget's `buttons`.

A button can be configured as the default button in the following ways:

- As a config Object with an `isDefault` property: `{label: 'Okay', isDefault: true}`.

- As a Node with a `data-default` attribute: `<button data-default="true">Okay</button>`.

This attribute is read-only; anytime there are changes to this widget's `buttons`, the `defaultButton` will be updated if needed.

Note: If two or more buttons are configured to be the default button, the last one wins.

Default: null

#### Fires event `defaultButtonChange`

Fires when the value for the configuration attribute `defaultButton` is changed. You can listen for the event using the `on` method if you wish to be notified before the attribute's value has changed, or using the `after` method if you wish to be notified after the attribute's value has changed.

#### Parameters:

- `e` EventFacade
  An Event Facade object with the following attribute-specific properties added:
  - `prevVal` Any
    The value of the attribute, prior to it being set.
  - `newVal` Any
    The value the attribute is to be set to.
  - `attrName` String
    The name of the attribute being set.
  - `subAttrName` String
    If setting a property within the attribute's value, the name of the sub-attribute property being set.