AlloyUI - API Docs

  • API Docs for Version: 3.1.0-deprecated.60

    • Show:

    WidgetButtons Class

    Defined in: yui3/src/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 yui3/src/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 yui3/src/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 yui3/src/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 yui3/src/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 yui3/src/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 yui3/src/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

      <p>Button node or configuration object.</p>

    Returns:

    Node:

    <p>The button node.</p>

    _getButtonContainer

    (
    • section
    • create
    )
    Node protected

    Defined in yui3/src/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

      <p>The <code>WidgetStdMod</code> section (header/body/footer).</p>

    • create Boolean

      <p>Whether the buttons container should be created if it does not already exist.</p>

    Returns:

    Node:

    <p>The buttons container node for the specified <code>section</code>.</p>

    _getButtonDefault

    (
    • button
    )
    Boolean protected

    Defined in yui3/src/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

      <p>The button node or configuration object.</p>

    Returns:

    Boolean:

    <p>Whether the button is configured to be the default button.</p>

    _getButtonName

    (
    • button
    )
    String protected

    Defined in yui3/src/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

      <p>The button node or configuration object.</p>

    Returns:

    String:

    <p>The name of the button.</p>

    _getButtons

    (
    • buttons
    )
    Object protected

    Defined in yui3/src/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

      <p>The widget's current <code>buttons</code> state.</p>

    Returns:

    Object:

    <p>A copy of the widget's current <code>buttons</code> state.</p>

    _mapButton

    (
    • button
    • section
    )
    protected

    Defined in yui3/src/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

      <p>The button node to map.</p>

    • section String

      <p>The <code>WidgetStdMod</code> section (header/body/footer).</p>

    _mapButtons

    (
    • buttons
    )
    protected

    Defined in yui3/src/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[]

      <p>The button nodes to map.</p>

    _mergeButtonConfig

    (
    • config
    )
    Object protected

    Defined in yui3/src/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

      <p>Button configuration object, or string name.</p>

    Returns:

    Object:

    <p>A copy of the button configuration object merged with any defaults.</p>

    _parseButtons

    (
    • srcNode
    )
    Null | Object protected

    Defined in yui3/src/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

      <p>This widget's srcNode to search for buttons.</p>

    Returns:

    Null | Object:

    <p><code>buttons</code> Config object parsed from this widget's DOM.</p>

    _setButtons

    (
    • config
    )
    Object protected

    Defined in yui3/src/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

      <p>The <code>buttons</code> configuration to process.</p>

    Returns:

    Object:

    <p>The processed <code>buttons</code> object which represents the new state.</p>

    _syncUIButtons

    () protected

    Defined in yui3/src/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 yui3/src/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

      <p>The button node to insert into this widget's DOM.</p>

    • section String

      <p>The <code>WidgetStdMod</code> section (header/body/footer).</p>

    • index Number

      <p>Index at which the <code>button</code> should be positioned.</p>

    _uiRemoveButton

    (
    • button
    • section
    • [options]
    )
    protected

    Defined in yui3/src/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

      <p>The button to remove and destroy.</p>

    • section String

      <p>The <code>WidgetStdMod</code> section (header/body/footer).</p>

    • [options] Object optional

      <p>Additional options.</p>

      • [preserveContent=false] Boolean optional

        <p>Whether the section content should be updated.</p>

    _uiSetButtons

    (
    • buttons
    )
    protected

    Defined in yui3/src/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

      <p>The current <code>buttons</code> state to visually represent.</p>

    _uiSetDefaultButton

    (
    • newButton
    • oldButton
    )
    protected

    Defined in yui3/src/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

      <p>The new <code>defaultButton</code>.</p>

    • oldButton Node

      <p>The old <code>defaultButton</code>.</p>

    _uiSetVisibleButtons

    (
    • visible
    )
    protected

    Defined in yui3/src/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

      <p>Whether this widget is visible.</p>

    _unMapButton

    (
    • button
    • section
    )
    protected

    Defined in yui3/src/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

      <p>The button node to remove from the buttons map.</p>

    • section String

      <p>The <code>WidgetStdMod</code> section (header/body/footer).</p>

    _updateContentButtons

    (
    • section
    )
    protected

    Defined in yui3/src/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

      <p>The <code>WidgetStdMod</code> section (header/body/footer) to update.</p>

    _updateDefaultButton

    () protected

    Defined in yui3/src/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 yui3/src/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

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

      • [action] Function | String optional

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

      • [classNames] String | String optional

        <p>Additional CSS classes to add to the button node.</p>

      • [context=this] Object optional

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

      • [disabled=false] Boolean optional

        <p>Whether the button should be disabled.</p>

      • [events="click"] String | Object optional

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

      • [isDefault=false] Boolean optional

        <p>Whether the button is the default button.</p>

      • [label] String optional

        <p>The visible text/value displayed in the button.</p>

      • [name] String optional

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

      • [section] String optional

        <p>The <code>WidgetStdMod</code> section (header, body, footer) where the button should be added.</p>

      • [srcNode] Node optional

        <p>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.</p>

      • [template] String optional

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

    • [section="footer"] String optional

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

    • [index] Number optional

      <p>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 <code>splice()</code> method, therefore a negative value will insert the <code>button</code> that many items from the end.</p>

    getButton

    (
    • name
    • [section="footer"]
    )
    Node

    Defined in yui3/src/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

      <p>The string name or index of the button.</p>

    • [section="footer"] String optional

      <p>The <code>WidgetStdMod</code> 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.</p>

    Returns:

    Node:

    <p>The button node.</p>

    removeButton

    (
    • button
    • [section="footer"]
    )
    chainable

    Defined in yui3/src/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

      <p>The button to remove. This can be a <code>Y.Node</code> instance, index, or String name of a button.</p>

    • [section="footer"] String optional

      <p>The <code>WidgetStdMod</code> 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.</p>

    Properties

    _buttonsHandles

    Object protected

    Defined in yui3/src/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 yui3/src/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 yui3/src/widget-buttons/js/widget-buttons.js:240

    Available since 3.5.0

    Internal reference to this widget's default button.

    BUTTONS

    Object

    Defined in yui3/src/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 yui3/src/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 yui3/src/widget-buttons/js/widget-buttons.js:145

    Available since 3.5.0

    CSS classes used by WidgetButtons.

    DEFAULT_BUTTONS_SECTION

    String

    Defined in yui3/src/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 yui3/src/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 yui3/src/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: {}

    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 yui3/src/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