WidgetButtons Class
+ + + + +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+ +
+
+
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+ +
+
+
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+ +
+
+
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+ +
+
+
Handles this widget's visibleChange event by focusing the defaultButton
+if there is one.
Parameters:
+ +-
+
+
-
+
+
e+ EventFacade + + + + ++ ++ + +
+
+
_bindUIButtons
+
+
+ ()
+
+
+
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+
+
+
+
+ Binds UI event listeners. This method is inserted via AOP, and will execute
+after bindUI().
_createButton
+
+
+ -
+
+
-
+
+
button+ +
+
+
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:
+ + +Returns:
+ +_getButtonContainer
+
+
+ -
+
+
-
+
+
section+ +
+
+ -
+
+
create+ +
+
+
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:
+ + +Returns:
+ +section.
+
+ _getButtonDefault
+
+
+ -
+
+
-
+
+
button+ +
+
+
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:
+ + +Returns:
+ +_getButtonName
+
+
+ -
+
+
-
+
+
button+ +
+
+
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:
+ + +Returns:
+ +_getButtons
+
+
+ -
+
+
-
+
+
buttons+ +
+
+
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
+buttonsstate.
+
+
Returns:
+ +buttons state.
+
+ _mapButton
+
+
+ -
+
+
-
+
+
button+ +
+
+ -
+
+
section+ +
+
+
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.
_mapButtons
+
+
+ -
+
+
-
+
+
buttons+ +
+
+
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+ +
+
+
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:
+ + +Returns:
+ +_parseButtons
+
+
+ -
+
+
-
+
+
srcNode+ +
+
+
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:
+ +buttons Config object parsed from this widget's DOM.
+
+ _setButtons
+
+
+ -
+
+
-
+
+
config+ +
+
+
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:
+ + +Returns:
+ +buttons object which represents the new
+ state.
+
+ _syncUIButtons
+
+
+ ()
+
+
+
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+
+
+
+
+ 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+ +
+
+
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.
+_uiRemoveButton
+
+
+ -
+
+
-
+
+
button+ +
+
+ -
+
+
section+ +
+
+ -
+
+
[options]+ +
+
+
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
+WidgetStdModsection (header/body/footer).
+
+ -
+
+
[options]+ Object + optional + + + + +++ + +Additional options.
+-
+
+
-
+
+
[preserveContent=false]+ Boolean + optional + + +++ + +Whether the section + content should be updated.
+
+
+
+
+ -
+
+
_uiSetButtons
+
+
+ -
+
+
-
+
+
buttons+ +
+
+
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
+buttonsstate to visually represent.
+
+
_uiSetDefaultButton
+
+
+ -
+
+
-
+
+
newButton+ +
+
+ -
+
+
oldButton+ +
+
+
Adds the "yui3-button-primary" CSS class to the new defaultButton and
+removes it from the old default button.
_uiSetVisibleButtons
+
+
+ -
+
+
-
+
+
visible+ +
+
+
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+ +
+
+
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.
_updateContentButtons
+
+
+ -
+
+
-
+
+
section+ +
+
+
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
+WidgetStdModsection (header/body/footer) to + update.
+
+
_updateDefaultButton
+
+
+ ()
+
+
+
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+
+
+
+
+ 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]+ +
+
+
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: TheWidgetStdModsection (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 +BUTTONSprototype property. When a config Object is provided, it will + be merged with any defaults provided by anysrcNodeand/or a button + with the samenamedefined on theBUTTONSproperty. 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
+contextobject can also be provided. Note: + Specifying a set ofeventswill override this setting.
+
+ -
+
+
[classNames]+ String | String[] + optional + + +++ + +Additional CSS classes to add + to the button node.
+
+
+ -
+
+
[context=this]+ Object + optional + + +++ + +Context which any
+eventsor +actionshould be called with. Defaults tothis, the widget. + Note:e.targetwill 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 toon().
+
+ -
+
+
[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
+BUTTONSproperty with this + same name, its configuration properties will be merged in as defaults.
+
+ -
+
+
[section]+ String + optional + + +++ + +The
+WidgetStdModsection (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
+WidgetStdModsection + (header/body/footer) where the button should be added. This takes + precedence over thebutton.sectionconfiguration 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 thebuttonthat many items from the end.
+
+
getButton
+
+
+ -
+
+
-
+
+
name+ +
+
+ -
+
+
[section="footer"]+ +
+
+
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
+WidgetStdModsection + (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:
+ +removeButton
+
+
+ -
+
+
-
+
+
button+ +
+
+ -
+
+
[section="footer"]+ +
+
+
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: TheWidgetStdModsection (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.Nodeinstance, index, or String name of a button.
+
+ -
+
+
[section="footer"]+ String + optional + + + + +++ + +The
+WidgetStdModsection + (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
+ + + + + + + + +_defaultButton
+ Node
+
+
+
+
+ protected
+
+
+
+
+
+
+
+
+ Internal reference to this widget's default button.
+BUTTONS
+ Object
+
+
+
+
+
+
+
+
+
+
+
+ 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
+
+
+
+
+
+
+
+
+
+
+
+ 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
+
+
+
+
+ CSS classes used by WidgetButtons.
DEFAULT_BUTTONS_SECTION
+ String
+
+
+
+
+
+
+
+
+
+
+
+ The default section to render buttons in when no section is specified.
+Default: Y.WidgetStdMod.FOOTER
+ + + + + +NON_BUTTON_NODE_CFG
+ Array
+
+
+
+
+
+
+
+
+ static
+
+
+
+
+ The list of button configuration properties which are specific to
+WidgetButtons and should not be passed to Y.Plugin.Button.createNode().
Attributes
+ + + + + +defaultButton
+ Node
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ readonly
+
+
+
+
+ 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
isDefaultproperty: +{label: 'Okay', isDefault: true}.
+As a Node with a
data-defaultattribute: +<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.+
+
+ -
+