WidgetButtons Class

• e

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

• e

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

• e

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

• e

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

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().

• button

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:

• section
• create

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:

• button

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:

• button

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:

• buttons

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:

• button
• section

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).

• buttons

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.

• config

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:

• srcNode

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:

• config

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:

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().

• button
• section
• index

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.

• button
• section
• [options]

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.

• buttons

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.

• newButton
• oldButton

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.

• visible

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.

• button
• section

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).

• section

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.

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.

• button
• [section="footer"]
• [index]

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.

• name
• [section="footer"]

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:

• button
• [section="footer"]

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.

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.

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.

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

Available since 3.5.0

Internal reference to this widget's default button.

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.

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".

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

Available since 3.5.0

CSS classes used by WidgetButtons.

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.

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().

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.

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.

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();
 }
 }
 }
 ]
}

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.

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.