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.
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
Attributes
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:
_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:
_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:
_afterVisibleChangeButtons
-
e
Handles this widget's visibleChange event by focusing the defaultButton
if there is one.
Parameters:
_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.
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.
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.
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:
-
buttonsObjectThe 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:
-
buttonsNode[]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.
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:
-
srcNodeNodeThis 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.
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.
_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:
-
buttonsObjectThe 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:
-
visibleBooleanWhether 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:
-
sectionStringThe
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:
-
buttonNode | Object | StringThe button to add. This can be a
Y.Nodeinstance, config Object, or String name for a predefined button on theBUTTONSprototype 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 optionalThe 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[] optionalAdditional CSS classes to add to the button node.
-
[context=this]Object optionalContext which any
eventsoractionshould be called with. Defaults tothis, the widget. Note:e.targetwill access the button node in the event handlers. -
[disabled=false]Boolean optionalWhether the button should be disabled.
-
[events="click"]String | Object optionalEvent 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 optionalWhether the button is the default button.
-
[label]String optionalThe visible text/value displayed in the button.
-
[name]String optionalA 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 optionalThe
WidgetStdModsection (header, body, footer) where the button should be added. -
[srcNode]Node optionalAn 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 optionalA specific template to use when creating a new button node (e.g. "<a />"). Note: Specifying a
srcNodewill overide this.
-
-
[section="footer"]String optionalThe
WidgetStdModsection (header/body/footer) where the button should be added. This takes precedence over thebutton.sectionconfiguration property. -
[index]Number optionalThe 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:
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:
-
buttonNode | Number | StringThe button to remove. This can be a
Y.Nodeinstance, index, or String name of a button. -
[section="footer"]String optionalThe
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
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 />"
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
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:
-
eEventFacadeAn Event Facade object with the following attribute-specific properties added:
