/**
`WidgetStdMod` extension.
@module widget-buttons
@since 3.4.0
**/
var YArray = Y.Array,
YObject = Y.Object,
WidgetStdMod = Y.WidgetStdMod,
/**
`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.
@class WidgetButtons
@extensionfor Widget
@since 3.4.0
**/
function WidgetButtons() {
// Require `Y.WidgetStdMod`.
if (!this._stdModNode) {
Y.error('WidgetStdMod must be added to a Widget before WidgetButtons.');
}
// Has to be setup before the `initializer()`.
this._buttonsHandles = {};
}
WidgetButtons.ATTRS = {
/**
Collection containing a widget's buttons.
The collection is an Object which contains an Array of `Y.Node`s 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
updating this attribute or using the `removeButton()` method.
@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();
}
}
}
]
}
@attribute buttons
@type Object
@default {}
@since 3.4.0
**/
buttons: {
getter: '_getButtons',
setter: '_setButtons',
value : {}
},
/**
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.
@attribute defaultButton
@type Node
@default null
@readOnly
@since 3.5.0
**/
readOnly: true,
value : null
}
};
/**
CSS classes used by `WidgetButtons`.
@property CLASS_NAMES
@type Object
@static
@since 3.5.0
**/
};
return this._parseButtons(srcNode);
}
};
/**
The list of button configuration properties which are specific to
`WidgetButtons` and should not be passed to `Y.Plugin.Button.createNode()`.
@property NON_BUTTON_NODE_CFG
@type Array
@static
@since 3.5.0
**/
'action', 'classNames', 'context', 'events', 'isDefault', 'section'
];
// -- Public Properties ----------------------------------------------------
/**
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.
@property BUTTONS
@type Object
@default {}
@see addButton()
@since 3.5.0
**/
BUTTONS: {},
/**
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".
@property BUTTONS_TEMPLATE
@type String
@default "<span />"
@since 3.5.0
**/
BUTTONS_TEMPLATE: '<span />',
/**
The default section to render buttons in when no section is specified.
@property DEFAULT_BUTTONS_SECTION
@type String
@default Y.WidgetStdMod.FOOTER
@since 3.5.0
**/
// -- Protected Properties -------------------------------------------------
/**
A map of button node `_yuid` -> event-handle for all button nodes which were
created by this widget.
@property _buttonsHandles
@type Object
@protected
@since 3.5.0
**/
/**
A map of this widget's `buttons`, both name -> button and
section:name -> button.
@property _buttonsMap
@type Object
@protected
@since 3.5.0
**/
/**
Internal reference to this widget's default button.
@property _defaultButton
@type Node
@protected
@since 3.5.0
**/
// -- Lifecycle Methods ----------------------------------------------------
initializer: function () {
// Creates button mappings and sets the `defaultButton`.
this._updateDefaultButton();
// Bound with `Y.bind()` to make more extensible.
},
destructor: function () {
// Detach all event subscriptions this widget added to its `buttons`.
});
delete this._buttonsHandles;
delete this._buttonsMap;
delete this._defaultButton;
},
// -- Public Methods -------------------------------------------------------
/**
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). 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.
button should be added.
* `index`: The index at which to add the button to the section.
* `src`: "add"
@method addButton
@param {Node|Object|String} button 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
with the same `name` defined on the `BUTTONS` property. The following
are the possible configuration properties beyond what Node plugins
accept by default:
@param {Function|String} [button.action] 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.
@param {String|String[]} [button.classNames] Additional CSS classes to add
to the button node.
@param {Object} [button.context=this] 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.
@param {Boolean} [button.disabled=false] Whether the button should be
disabled.
@param {String|Object} [button.events="click"] 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()`.
@param {Boolean} [button.isDefault=false] Whether the button is the
default button.
button.
@param {String} [button.name] 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.
@param {String} [button.section] The `WidgetStdMod` section (header, body,
footer) where the button should be added.
@param {Node} [button.srcNode] 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.
@param {String} [button.template] A specific template to use when creating
a new button node (e.g. "<a />"). **Note:** Specifying a `srcNode`
will overide this.
@param {String} [section="footer"] The `WidgetStdMod` section
precedence over the `button.section` configuration property.
@param {Number} [index] The index at which the button should be inserted. If
not specified, the button will be added to the end of the section.
@chainable
@see Plugin.Button.createNode()
@since 3.4.0
**/
// Makes sure we have the full config object.
}
// Insert new button at the correct position.
src : 'add'
});
return this;
},
/**
Returns a button node from this widget's `buttons`.
@method getButton
@param {Number|String} name The string name or index of the button.
@param {String} [section="footer"] The `WidgetStdMod` section
looking for a button by numerical index, or by name but scoped to a
particular section.
@return {Node} The button node.
@since 3.5.0
**/
var map = this._buttonsMap,
// Supports `getButton(1, 'header')` signature.
}
// Looks up button by name or section:name.
},
/**
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.
button should be removed from.
* `index`: The index at which at which the button exists in the section.
* `src`: "remove"
@method removeButton
@param {Node|Number|String} button The button to remove. This can be a
`Y.Node` instance, index, or String name of a button.
@param {String} [section="footer"] The `WidgetStdMod` section
removing a button by numerical index, or by name but scoped to a
particular section.
@chainable
@since 3.5.0
**/
// Shortcut if `button` is already an index which is needed for slicing.
} else {
// Supports `button` being the string name.
}
// Determines the `section` and `index` at which the button exists.
if (index > -1) {
return true;
}
});
}
// Button was found at an appropriate index.
// Remove button from `section` array.
src : 'remove'
});
}
return this;
},
// -- Protected Methods ----------------------------------------------------
/**
Binds UI event listeners. This method is inserted via AOP, and will execute
after `bindUI()`.
@method _bindUIButtons
@protected
@since 3.4.0
**/
_bindUIButtons: function () {
// Event handlers are bound with `bind()` to make them more extensible.
this.after({
});
},
/**
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`.
@method _createButton
@param {Node|Object} button Button node or configuration object.
@return {Node} The button node.
@protected
@since 3.5.0
**/
_createButton: function (button) {
// Plug and return an existing Y.Node instance.
}
// Merge `button` config with defaults and back-compat.
context: this,
events : 'click',
}, button);
// Remove all non-button Node config props.
delete buttonConfig[nonButtonNodeCfg[i]];
}
// Create the button node using the button Node-only config.
// Supports `action` as a String name of a Function on the `context`
// object.
}
// Supports all types of crazy configs for event subscriptions and
// stores a reference to the returned `EventHandle`.
// Tags the button with the configured `name` and `isDefault` settings.
// Add any CSS classnames to the button node.
return button;
},
/**
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.
@method _getButtonContainer
@param {Boolean} create Whether the buttons container should be created if
it does not already exist.
@return {Node} The buttons container node for the specified `section`.
@protected
@see BUTTONS_TEMPLATE
@since 3.5.0
**/
// Search for an existing buttons container within the section.
// Create the `container` if it doesn't already exist.
}
return container;
},
/**
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.
@method _getButtonDefault
@param {Node|Object} button The button node or configuration object.
@return {Boolean} Whether the button is configured to be the default button.
@protected
@since 3.5.0
**/
_getButtonDefault: function (button) {
}
return !!isDefault;
},
/**
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.
@method _getButtonName
@param {Node|Object} button The button node or configuration object.
@return {String} The name of the button.
@protected
@since 3.5.0
**/
_getButtonName: function (button) {
var name;
} else {
}
return name;
},
/**
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
@method _getButtons
@param {Object} buttons The widget's current `buttons` state.
@return {Object} A copy of the widget's current `buttons` state.
@protected
@since 3.5.0
**/
_getButtons: function (buttons) {
var buttonsCopy = {};
// Creates a new copy of the `buttons` object.
// Creates of copy of the array of button nodes.
});
return buttonsCopy;
},
/**
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.
configured to be the default button, the last one wins.
@method _mapButton
@param {Node} button The button node to map.
@param {String} section The `WidgetStdMod` section.
@protected
@since 3.5.0
**/
var map = this._buttonsMap,
if (name) {
// name -> button
// section:name -> button
}
},
/**
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
@method _mapButtons
@param {Node[]} buttons The button nodes to map.
@protected
@since 3.5.0
**/
_mapButtons: function (buttons) {
this._buttonsMap = {};
this._defaultButton = null;
var i, len;
}
}, this);
},
/**
Returns a copy of the specified `config` object merged with any defaults
with the same `name` on the `BUTTONS` property.
@method _mergeButtonConfig
@param {Object|String} config Button configuration object, or string name.
@return {Object} A copy of the button configuration object merged with any
defaults.
@protected
@since 3.5.0
**/
_mergeButtonConfig: function (config) {
// Makes sure `config` is an Object and a copy of the specified value.
// Seeds default values from the button node, if there is one.
// Makes sure the button's current values override any defaults.
buttonConfig = {
};
// Label should only be considered when not an empty string.
// Merge `config` with `buttonConfig` values.
}
// Merge `config` with predefined default values.
if (defConfig) {
}
return config;
},
/**
`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.
@method _parseButtons
@param {Node} srcNode This widget's srcNode to search for buttons.
@return {null|Object} `buttons` Config object parsed from this widget's DOM.
@protected
@since 3.5.0
**/
_parseButtons: function (srcNode) {
buttonsConfig = null;
sectionButtons = [];
// Creates a button config object for every button node found and
// adds it to the section. This way each button configuration can be
// merged with any defaults provided by predefined `BUTTONS`.
});
buttonsConfig || (buttonsConfig = {});
}, this);
return buttonsConfig;
},
/**
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`.
@method _setButtons
@param {Array|Object} config The `buttons` configuration to process.
@return {Object} The processed `buttons` object which represents the new
state.
@protected
@since 3.5.0
**/
_setButtons: function (config) {
var defSection = this.DEFAULT_BUTTONS_SECTION,
buttons = {};
if (!isArray(buttonConfigs)) { return; }
button = buttonConfigs[i];
}
// Always passes through `_createButton()` to make sure the node
// is decorated as a button.
// Use provided `section` or fallback to the default section.
// Add button to the array of buttons for the specified section.
}
}
// Handle `config` being either an Array or Object of Arrays.
} else {
}
return buttons;
},
/**
Syncs this widget's current button-related state to its DOM. This method is
inserted via AOP, and will execute after `syncUI()`.
@method _syncUIButtons
@protected
@since 3.4.0
**/
_syncUIButtons: function () {
},
/**
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.
@method _uiInsertButton
@param {Node} button The button node to insert into this widget's DOM.
@param {Number} index Index at which the `button` should be positioned.
@protected
@since 3.5.0
**/
// Inserts the button node at the correct index.
// Adds the button container to the section content.
},
/**
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.
@method _uiRemoveButton
@param {Node} button The button to remove and destroy.
@param {Object} [options] Additional options.
@param {Boolean} [options.preserveContent=false] Whether the section
content should be updated.
@protected
@since 3.5.0
**/
handles = this._buttonsHandles,
// Remove the button container and section nodes if needed.
if (!options.preserveContent) {
// Only matters if we have a button container which is empty.
if (buttonContainer &&
this._updateContentButtons(section);
}
}
},
/**
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.
@method _uiSetButtons
@param {Object} buttons The current `buttons` state to visually represent.
@protected
@since 3.5.0
**/
_uiSetButtons: function (buttons) {
buttonsUpdated = false,
// When there's no button container, there are no new buttons or old
// buttons that we have to deal with for this section.
if (!buttonContainer) { return; }
button = sectionButtons[i];
// Buttons already rendered in the Widget should remain there or
// moved to their new index. New buttons will be added to the
// current `buttonContainer`.
if (buttonIndex > -1) {
// Remove button from existing buttons nodeList since its in
// the DOM already.
// Check that the button is at the right position, if not,
// move it to its new position.
if (buttonIndex !== i) {
// Using `i + 1` because the button should be at index
// `i`; it's inserted before the node which comes after.
buttonsUpdated = true;
}
} else {
buttonsUpdated = true;
}
}
// Safely removes the old button nodes which are no longer part of
// this widget's `buttons`.
buttonsUpdated = true;
}, this);
// Remove leftover empty button containers and updated the StdMod
// content area.
if (numButtons === 0) {
this._updateContentButtons(section);
return;
}
// Adds the button container to the section content.
if (buttonsUpdated) {
}
}, this);
},
/**
Adds the "yui3-button-primary" CSS class to the new `defaultButton` and
removes it from the old default button.
@method _uiSetDefaultButton
@param {Node} newButton The new `defaultButton`.
@param {Node} oldButton The old `defaultButton`.
@protected
@since 3.5.0
**/
},
/**
Focuses this widget's `defaultButton` if there is one and this widget is
visible.
@method _uiSetVisibleButtons
@param {Boolean} visible Whether this widget is visible.
@protected
@since 3.5.0
**/
_uiSetVisibleButtons: function (visible) {
if (!visible) { return; }
if (defaultButton) {
}
},
/**
Removes the specified `button` to the buttons map, and nulls-out the
`defaultButton` if it is currently the default button.
@method _unMapButton
@param {Node} button The button node to remove from the buttons map.
@protected
@since 3.5.0
**/
var map = this._buttonsMap,
// Only delete the map entry if the specified `button` is mapped to it.
if (name) {
// name -> button
}
// section:name -> button
delete map[sectionName];
}
}
// Clear the default button if its the specified `button`.
if (this._defaultButton === button) {
this._defaultButton = null;
}
},
/**
Updates the `defaultButton` attribute if it needs to be updated by comparing
its current value with the protected `_defaultButton` property.
@method _updateDefaultButton
@protected
@since 3.5.0
**/
_updateDefaultButton: function () {
var defaultButton = this._defaultButton;
}
},
/**
Updates the content attribute which corresponds to the specified `section`.
The method updates the section's content to its current `childNodes`
empty. It also specifies a `src` of `buttons` on the change event facade.
@method _updateContentButtons
update.
@protected
@since 3.5.0
**/
_updateContentButtons: function (section) {
// `childNodes` return text nodes and HTMLElements.
// Updates the section to its current contents, or null if it is empty.
},
// -- Protected Event Handlers ---------------------------------------------
/**
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.
@method _afterButtonsChange
@param {EventFacade} e
@protected
@since 3.4.0
**/
_afterButtonsChange: function (e) {
// Special cases `addButton()` to only set and insert the new button.
if (src === 'add') {
// Make sure we have the button node.
this._updateDefaultButton();
return;
}
// Special cases `removeButton()` to only remove the specified button.
if (src === 'remove') {
// Button node already exists on the event facade.
this._updateDefaultButton();
return;
}
this._mapButtons(buttons);
this._updateDefaultButton();
this._uiSetButtons(buttons);
},
/**
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.
@method _afterContentChangeButtons
@param {EventFacade} e
@protected
@since 3.5.0
**/
_afterContentChangeButtons: function (e) {
pos = e.stdModPosition,
// Only do work when absolutely necessary.
}
},
/**
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.
@method _afterDefaultButtonChange
@param {EventFacade} e
@protected
@since 3.5.0
**/
_afterDefaultButtonChange: function (e) {
},
/**
Handles this widget's `visibleChange` event by focusing the `defaultButton`
if there is one.
@method _afterVisibleChangeButtons
@param {EventFacade} e
@protected
@since 3.5.0
**/
_afterVisibleChangeButtons: function (e) {
this._uiSetVisibleButtons(e.newVal);
}
};