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

`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

`BUTTONS`

Object

Defined in widget-buttons/js/widget-buttons.js:181

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

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

Available since 3.5.0

CSS classes used by WidgetButtons.

`DEFAULT_BUTTONS_SECTION`

String

Defined in widget-buttons/js/widget-buttons.js:208

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

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

Available since 3.4.0

Collection containing a widget's buttons.

The collection is an Object which contains an Array of Y.Nodes 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:116

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.

WidgetButtons Class

Item Index

Methods

Properties

Attributes

Methods

addButton

Parameters:

getButton

Parameters:

Returns:

removeButton

Parameters:

Properties

BUTTONS

BUTTONS_TEMPLATE

CLASS_NAMES

DEFAULT_BUTTONS_SECTION

NON_BUTTON_NODE_CFG

Attributes

buttons

Fires event buttonsChange

Parameters:

Example:

defaultButton

Fires event defaultButtonChange

Parameters:

`addButton`

`getButton`

`removeButton`

`BUTTONS`

`BUTTONS_TEMPLATE`

`CLASS_NAMES`

`DEFAULT_BUTTONS_SECTION`

`NON_BUTTON_NODE_CFG`

`buttons`

Fires event `buttonsChange`

`defaultButton`

Fires event `defaultButtonChange`