node-base.js revision 1909339da3105dc509908ff39ecc298f2f94f446
YUI.add('node-base', function(Y) {
/**
* @module node
* @submodule node-base
*/
var methods = [
/**
* Determines whether each node has the given className.
* @method hasClass
* @for Node
* @param {String} className the class name to search for
* @return {Boolean} Whether or not the element has the specified class
*/
'hasClass',
/**
* Adds a class name to each node.
* @method addClass
* @param {String} className the class name to add to the node's class attribute
* @chainable
*/
'addClass',
/**
* Removes a class name from each node.
* @method removeClass
* @param {String} className the class name to remove from the node's class attribute
* @chainable
*/
'removeClass',
/**
* Replace a class with another class for each node.
* If no oldClassName is present, the newClassName is simply added.
* @method replaceClass
* @param {String} oldClassName the class name to be replaced
* @param {String} newClassName the class name that will be replacing the old class name
* @chainable
*/
'replaceClass',
/**
* If the className exists on the node it is removed, if it doesn't exist it is added.
* @method toggleClass
* @param {String} className the class name to be toggled
* @param {Boolean} force Option to force adding or removing the class.
* @chainable
*/
'toggleClass'
];
Y.Node.importMethod(Y.DOM, methods);
/**
* Determines whether each node has the given className.
* @method hasClass
* @see Node.hasClass
* @for NodeList
* @param {String} className the class name to search for
* @return {Array} An array of booleans for each node bound to the NodeList.
*/
/**
* Adds a class name to each node.
* @method addClass
* @see Node.addClass
* @param {String} className the class name to add to the node's class attribute
* @chainable
*/
/**
* Removes a class name from each node.
* @method removeClass
* @see Node.removeClass
* @param {String} className the class name to remove from the node's class attribute
* @chainable
*/
/**
* Replace a class with another class for each node.
* If no oldClassName is present, the newClassName is simply added.
* @method replaceClass
* @see Node.replaceClass
* @param {String} oldClassName the class name to be replaced
* @param {String} newClassName the class name that will be replacing the old class name
* @chainable
*/
/**
* If the className exists on the node it is removed, if it doesn't exist it is added.
* @method toggleClass
* @see Node.toggleClass
* @param {String} className the class name to be toggled
* @chainable
*/
Y.NodeList.importMethod(Y.Node.prototype, methods);
/**
* @module node
* @submodule node-base
*/
var Y_Node = Y.Node,
Y_DOM = Y.DOM;
/**
* Returns a new dom node using the provided markup string.
* @method create
* @static
* @param {String} html The markup used to create the element
* @param {HTMLDocument} doc An optional document context
* @return {Node} A Node instance bound to a DOM node or fragment
* @for Node
*/
Y_Node.create = function(html, doc) {
if (doc && doc._node) {
doc = doc._node;
}
return Y.one(Y_DOM.create(html, doc));
};
Y.mix(Y_Node.prototype, {
/**
* Creates a new Node using the provided markup string.
* @method create
* @param {String} html The markup used to create the element
* @param {HTMLDocument} doc An optional document context
* @return {Node} A Node instance bound to a DOM node or fragment
*/
create: Y_Node.create,
/**
* Inserts the content before the reference node.
* @method insert
* @param {String | Y.Node | HTMLElement | Y.NodeList | HTMLCollection} content The content to insert
* @param {Int | Y.Node | HTMLElement | String} where The position to insert at.
* Possible "where" arguments
* <dl>
* <dt>Y.Node</dt>
* <dd>The Node to insert before</dd>
* <dt>HTMLElement</dt>
* <dd>The element to insert before</dd>
* <dt>Int</dt>
* <dd>The index of the child element to insert before</dd>
* <dt>"replace"</dt>
* <dd>Replaces the existing HTML</dd>
* <dt>"before"</dt>
* <dd>Inserts before the existing HTML</dd>
* <dt>"before"</dt>
* <dd>Inserts content before the node</dd>
* <dt>"after"</dt>
* <dd>Inserts content after the node</dd>
* </dl>
* @chainable
*/
insert: function(content, where) {
this._insert(content, where);
return this;
},
_insert: function(content, where) {
var node = this._node,
ret = null;
if (typeof where == 'number') { // allow index
where = this._node.childNodes[where];
} else if (where && where._node) { // Node
where = where._node;
}
if (content && typeof content != 'string') { // allow Node or NodeList/Array instances
content = content._node || content._nodes || content;
}
ret = Y_DOM.addHTML(node, content, where);
return ret;
},
/**
* Inserts the content as the firstChild of the node.
* @method prepend
* @param {String | Y.Node | HTMLElement} content The content to insert
* @chainable
*/
prepend: function(content) {
return this.insert(content, 0);
},
/**
* Inserts the content as the lastChild of the node.
* @method append
* @param {String | Y.Node | HTMLElement} content The content to insert
* @chainable
*/
append: function(content) {
return this.insert(content, null);
},
/**
* @method appendChild
* @param {String | HTMLElement | Node} node Node to be appended
* @return {Node} The appended node
*/
appendChild: function(node) {
return Y_Node.scrubVal(this._insert(node));
},
/**
* @method insertBefore
* @param {String | HTMLElement | Node} newNode Node to be appended
* @param {HTMLElement | Node} refNode Node to be inserted before
* @return {Node} The inserted node
*/
insertBefore: function(newNode, refNode) {
return Y.Node.scrubVal(this._insert(newNode, refNode));
},
/**
* Appends the node to the given node.
* @method appendTo
* @param {Y.Node | HTMLElement} node The node to append to
* @chainable
*/
appendTo: function(node) {
Y.one(node).append(this);
return this;
},
/**
* Replaces the node's current content with the content.
* @method setContent
* @param {String | Y.Node | HTMLElement | Y.NodeList | HTMLCollection} content The content to insert
* @chainable
*/
setContent: function(content) {
this._insert(content, 'replace');
return this;
},
/**
* Returns the node's current content (e.g. innerHTML)
* @method getContent
* @return {String} The current content
*/
getContent: function(content) {
return this.get('innerHTML');
}
});
Y.NodeList.importMethod(Y.Node.prototype, [
/**
* Called on each Node instance
* @for NodeList
* @method append
* @see Node.append
*/
'append',
/** Called on each Node instance
* @method insert
* @see Node.insert
*/
'insert',
/**
* Called on each Node instance
* @for NodeList
* @method appendChild
* @see Node.appendChild
*/
'appendChild',
/** Called on each Node instance
* @method insertBefore
* @see Node.insertBefore
*/
'insertBefore',
/** Called on each Node instance
* @method prepend
* @see Node.prepend
*/
'prepend',
/** Called on each Node instance
* @method setContent
* @see Node.setContent
*/
'setContent',
/** Called on each Node instance
* @method getContent
* @see Node.getContent
*/
'getContent'
]);
/**
* @module node
* @submodule node-base
*/
var Y_Node = Y.Node,
Y_DOM = Y.DOM;
/**
* Static collection of configuration attributes for special handling
* @property ATTRS
* @static
* @type object
*/
Y_Node.ATTRS = {
/**
* Allows for getting and setting the text of an element.
* Formatting is preserved and special characters are treated literally.
* @config text
* @type String
*/
text: {
getter: function() {
return Y_DOM.getText(this._node);
},
setter: function(content) {
Y_DOM.setText(this._node, content);
return content;
}
},
/**
* Allows for getting and setting the text of an element.
* Formatting is preserved and special characters are treated literally.
* @config for
* @type String
*/
'for': {
getter: function() {
return Y_DOM.getAttribute(this._node, 'for');
},
setter: function(val) {
Y_DOM.setAttribute(this._node, 'for', val);
return val;
}
},
'options': {
getter: function() {
return this._node.getElementsByTagName('option');
}
},
/**
* Returns a NodeList instance of all HTMLElement children.
* @readOnly
* @config children
* @type NodeList
*/
'children': {
getter: function() {
var node = this._node,
children = node.children,
childNodes, i, len;
if (!children) {
childNodes = node.childNodes;
children = [];
for (i = 0, len = childNodes.length; i < len; ++i) {
if (childNodes[i][TAG_NAME]) {
children[children.length] = childNodes[i];
}
}
}
return Y.all(children);
}
},
value: {
getter: function() {
return Y_DOM.getValue(this._node);
},
setter: function(val) {
Y_DOM.setValue(this._node, val);
return val;
}
}
};
Y.Node.importMethod(Y.DOM, [
/**
* Allows setting attributes on DOM nodes, normalizing in some cases.
* This passes through to the DOM node, allowing for custom attributes.
* @method setAttribute
* @for Node
* @for NodeList
* @chainable
* @param {string} name The attribute name
* @param {string} value The value to set
*/
'setAttribute',
/**
* Allows getting attributes on DOM nodes, normalizing in some cases.
* This passes through to the DOM node, allowing for custom attributes.
* @method getAttribute
* @for Node
* @for NodeList
* @param {string} name The attribute name
* @return {string} The attribute value
*/
'getAttribute'
]);
/**
* @module node
* @submodule node-base
*/
var Y_Node = Y.Node;
var Y_NodeList = Y.NodeList;
/**
* List of events that route to DOM events
* @static
* @property DOM_EVENTS
* @for Node
*/
Y_Node.DOM_EVENTS = {
abort: 1,
beforeunload: 1,
blur: 1,
change: 1,
click: 1,
close: 1,
command: 1,
contextmenu: 1,
dblclick: 1,
DOMMouseScroll: 1,
drag: 1,
dragstart: 1,
dragenter: 1,
dragover: 1,
dragleave: 1,
dragend: 1,
drop: 1,
error: 1,
focus: 1,
key: 1,
keydown: 1,
keypress: 1,
keyup: 1,
load: 1,
message: 1,
mousedown: 1,
mouseenter: 1,
mouseleave: 1,
mousemove: 1,
mousemultiwheel: 1,
mouseout: 1,
mouseover: 1,
mouseup: 1,
mousewheel: 1,
orientationchange: 1,
reset: 1,
resize: 1,
select: 1,
selectstart: 1,
submit: 1,
scroll: 1,
textInput: 1,
unload: 1
};
// Add custom event adaptors to this list. This will make it so
// that delegate, key, available, contentready, etc all will
// be available through Node.on
Y.mix(Y_Node.DOM_EVENTS, Y.Env.evt.plugins);
Y.augment(Y_Node, Y.EventTarget);
Y.mix(Y_Node.prototype, {
/**
* Removes event listeners from the node and (optionally) its subtree
* @method purge
* @param {Boolean} recurse (optional) Whether or not to remove listeners from the
* node's subtree
* @param {String} type (optional) Only remove listeners of the specified type
* @chainable
*
*/
purge: function(recurse, type) {
Y.Event.purgeElement(this._node, recurse, type);
return this;
}
});
Y.mix(Y.NodeList.prototype, {
_prepEvtArgs: function(type, fn, context) {
// map to Y.on/after signature (type, fn, nodes, context, arg1, arg2, etc)
var args = Y.Array(arguments, 0, true);
if (args.length < 2) { // type only (event hash) just add nodes
args[2] = this._nodes;
} else {
args.splice(2, 0, this._nodes);
}
args[3] = context || this; // default to NodeList instance as context
return args;
},
/**
* Applies an event listener to each Node bound to the NodeList.
* @method on
* @param {String} type The event being listened for
* @param {Function} fn The handler to call when the event fires
* @param {Object} context The context to call the handler with.
* Default is the NodeList instance.
* @param {Object} context The context to call the handler with.
* param {mixed} arg* 0..n additional arguments to supply to the subscriber
* when the event fires.
* @return {Object} Returns an event handle that can later be use to detach().
* @see Event.on
* @for NodeList
*/
on: function(type, fn, context) {
return Y.on.apply(Y, this._prepEvtArgs.apply(this, arguments));
},
/**
* Applies an one-time event listener to each Node bound to the NodeList.
* @method once
* @param {String} type The event being listened for
* @param {Function} fn The handler to call when the event fires
* @param {Object} context The context to call the handler with.
* Default is the NodeList instance.
* @return {Object} Returns an event handle that can later be use to detach().
* @see Event.on
*/
once: function(type, fn, context) {
return Y.once.apply(Y, this._prepEvtArgs.apply(this, arguments));
},
/**
* Applies an event listener to each Node bound to the NodeList.
* The handler is called only after all on() handlers are called
* and the event is not prevented.
* @method after
* @param {String} type The event being listened for
* @param {Function} fn The handler to call when the event fires
* @param {Object} context The context to call the handler with.
* Default is the NodeList instance.
* @return {Object} Returns an event handle that can later be use to detach().
* @see Event.on
*/
after: function(type, fn, context) {
return Y.after.apply(Y, this._prepEvtArgs.apply(this, arguments));
},
/**
* Applies an one-time event listener to each Node bound to the NodeList
* that will be called only after all on() handlers are called and the
* event is not prevented.
*
* @method onceAfter
* @param {String} type The event being listened for
* @param {Function} fn The handler to call when the event fires
* @param {Object} context The context to call the handler with.
* Default is the NodeList instance.
* @return {Object} Returns an event handle that can later be use to detach().
* @see Event.on
*/
onceAfter: function(type, fn, context) {
return Y.onceAfter.apply(Y, this._prepEvtArgs.apply(this, arguments));
}
});
Y_NodeList.importMethod(Y.Node.prototype, [
/**
* Called on each Node instance
* @method detach
* @see Node.detach
*/
'detach',
/** Called on each Node instance
* @method detachAll
* @see Node.detachAll
*/
'detachAll'
]);
Y.mix(Y.Node.ATTRS, {
offsetHeight: {
setter: function(h) {
Y.DOM.setHeight(this._node, h);
return h;
},
getter: function() {
return this._node.offsetHeight;
}
},
offsetWidth: {
setter: function(w) {
Y.DOM.setWidth(this._node, w);
return w;
},
getter: function() {
return this._node.offsetWidth;
}
}
});
Y.mix(Y.Node.prototype, {
sizeTo: function(w, h) {
var node;
if (arguments.length < 2) {
node = Y.one(w);
w = node.get('offsetWidth');
h = node.get('offsetHeight');
}
this.setAttrs({
offsetWidth: w,
offsetHeight: h
});
}
});
/**
* @module node
* @submodule node-base
*/
var Y_Node = Y.Node;
Y.mix(Y_Node.prototype, {
/**
* Makes the node visible.
* If the "transition" module is loaded, show optionally
* animates the showing of the node using either the default
* transition effect ('fadeIn'), or the given named effect.
* @method show
* @for Node
* @param {String} name A named Transition effect to use as the show effect.
* @param {Object} config Options to use with the transition.
* @param {Function} callback An optional function to run after the transition completes.
* @chainable
*/
show: function(callback) {
callback = arguments[arguments.length - 1];
this.toggleView(true, callback);
return this;
},
/**
* The implementation for showing nodes.
* Default is to toggle the style.display property.
* @method _show
* @protected
* @chainable
*/
_show: function() {
this.setStyle('display', '');
},
_isHidden: function() {
return Y.DOM.getStyle(this._node, 'display') === 'none';
},
toggleView: function(on, callback) {
this._toggleView.apply(this, arguments);
},
_toggleView: function(on, callback) {
callback = arguments[arguments.length - 1];
// base on current state if not forcing
if (typeof on != 'boolean') {
on = (this._isHidden()) ? 1 : 0;
}
if (on) {
this._show();
} else {
this._hide();
}
if (typeof callback == 'function') {
callback.call(this);
}
return this;
},
/**
* Hides the node.
* If the "transition" module is loaded, hide optionally
* animates the hiding of the node using either the default
* transition effect ('fadeOut'), or the given named effect.
* @method hide
* @param {String} name A named Transition effect to use as the show effect.
* @param {Object} config Options to use with the transition.
* @param {Function} callback An optional function to run after the transition completes.
* @chainable
*/
hide: function(callback) {
callback = arguments[arguments.length - 1];
this.toggleView(false, callback);
return this;
},
/**
* The implementation for hiding nodes.
* Default is to toggle the style.display property.
* @method _hide
* @protected
* @chainable
*/
_hide: function() {
this.setStyle('display', 'none');
}
});
Y.NodeList.importMethod(Y.Node.prototype, [
/**
* Makes each node visible.
* If the "transition" module is loaded, show optionally
* animates the showing of the node using either the default
* transition effect ('fadeIn'), or the given named effect.
* @method show
* @param {String} name A named Transition effect to use as the show effect.
* @param {Object} config Options to use with the transition.
* @param {Function} callback An optional function to run after the transition completes.
* @for NodeList
* @chainable
*/
'show',
/**
* Hides each node.
* If the "transition" module is loaded, hide optionally
* animates the hiding of the node using either the default
* transition effect ('fadeOut'), or the given named effect.
* @method hide
* @param {String} name A named Transition effect to use as the show effect.
* @param {Object} config Options to use with the transition.
* @param {Function} callback An optional function to run after the transition completes.
* @chainable
*/
'hide',
'toggleView'
]);
if (!Y.config.doc.documentElement.hasAttribute) { // IE < 8
Y.Node.prototype.hasAttribute = function(attr) {
if (attr === 'value') {
if (this.get('value') !== "") { // IE < 8 fails to populate specified when set in HTML
return true;
}
}
return !!(this._node.attributes[attr] &&
this._node.attributes[attr].specified);
};
}
// IE throws an error when calling focus() on an element that's invisible, not
// displayed, or disabled.
Y.Node.prototype.focus = function () {
try {
this._node.focus();
} catch (e) {
}
return this;
};
// IE throws error when setting input.type = 'hidden',
// input.setAttribute('type', 'hidden') and input.attributes.type.value = 'hidden'
Y.Node.ATTRS.type = {
setter: function(val) {
if (val === 'hidden') {
try {
this._node.type = 'hidden';
} catch(e) {
this.setStyle('display', 'none');
this._inputType = 'hidden';
}
} else {
try { // IE errors when changing the type from "hidden'
this._node.type = val;
} catch (e) {
}
}
return val;
},
getter: function() {
return this._inputType || this._node.type;
},
_bypassProxy: true // don't update DOM when using with Attribute
};
if (Y.config.doc.createElement('form').elements.nodeType) {
// IE: elements collection is also FORM node which trips up scrubVal.
Y.Node.ATTRS.elements = {
getter: function() {
return this.all('input, textarea, button, select');
}
};
}
}, '@VERSION@' ,{requires:['dom-base', 'node-core', 'event-base']});