API Docs for: 3.18.1
Show:

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.

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:

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

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

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

_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:220

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

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

Available since 3.5.0

Internal reference to this widget's default button.

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.