node-create.js revision bc434ac650a27231efd02bc22efb6aa323286ab8
8346e283ad797ef549be70335d3961f4324901baRyan Grove * @module node
8346e283ad797ef549be70335d3961f4324901baRyan Grove * @submodule node-base
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * Returns a new dom node using the provided markup string.
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @method create
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @param {String} html The markup used to create the element
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @param {HTMLDocument} doc An optional document context
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @return {Node} A Node instance bound to a DOM node or fragment
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * Creates a new Node using the provided markup string.
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @method create
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @param {String} html The markup used to create the element
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @param {HTMLDocument} doc An optional document context
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @return {Node} A Node instance bound to a DOM node or fragment
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * Inserts the content before the reference node.
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @method insert
6eae5adc42f886ebacac1f714be3f0c9e4b205c1Luke Smith * @param {String | Node | HTMLElement | NodeList | HTMLCollection} content The content to insert
6eae5adc42f886ebacac1f714be3f0c9e4b205c1Luke Smith * @param {Int | Node | HTMLElement | String} where The position to insert at.
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * Possible "where" arguments
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * <dt>Y.Node</dt>
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * <dd>The Node to insert before</dd>
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * <dt>HTMLElement</dt>
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * <dd>The element to insert before</dd>
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * <dt>Int</dt>
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * <dd>The index of the child element to insert before</dd>
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * <dt>"replace"</dt>
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * <dd>Replaces the existing HTML</dd>
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * <dt>"before"</dt>
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * <dd>Inserts before the existing HTML</dd>
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * <dt>"before"</dt>
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * <dd>Inserts content before the node</dd>
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * <dt>"after"</dt>
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * <dd>Inserts content after the node</dd>
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @chainable
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney return this;
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney if (content && typeof content != 'string') { // allow Node or NodeList/Array instances
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney content = content._node || content._nodes || content;
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * Inserts the content as the firstChild of the node.
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @method prepend
6eae5adc42f886ebacac1f714be3f0c9e4b205c1Luke Smith * @param {String | Node | HTMLElement} content The content to insert
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @chainable
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * Inserts the content as the lastChild of the node.
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @method append
6eae5adc42f886ebacac1f714be3f0c9e4b205c1Luke Smith * @param {String | Node | HTMLElement} content The content to insert
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @chainable
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @method appendChild
8346e283ad797ef549be70335d3961f4324901baRyan Grove * @param {String | HTMLElement | Node} node Node to be appended
8346e283ad797ef549be70335d3961f4324901baRyan Grove * @return {Node} The appended node
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @method insertBefore
8346e283ad797ef549be70335d3961f4324901baRyan Grove * @param {String | HTMLElement | Node} newNode Node to be appended
8346e283ad797ef549be70335d3961f4324901baRyan Grove * @param {HTMLElement | Node} refNode Node to be inserted before
8346e283ad797ef549be70335d3961f4324901baRyan Grove * @return {Node} The inserted node
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney return Y.Node.scrubVal(this._insert(newNode, refNode));
8346e283ad797ef549be70335d3961f4324901baRyan Grove * Appends the node to the given node.
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @method appendTo
6eae5adc42f886ebacac1f714be3f0c9e4b205c1Luke Smith * @param {Node | HTMLElement} node The node to append to
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @chainable
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney return this;
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * Replaces the node's current content with the content.
bc434ac650a27231efd02bc22efb6aa323286ab8Matt Sweeney * Note that this passes to innerHTML and is not escaped.
bc434ac650a27231efd02bc22efb6aa323286ab8Matt Sweeney * Use Y.Ecape.html() to escape HTML, or use set('text') to add as text.
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @method setContent
db006be6df49e087e3df27f259256be08df7a1efMatt Sweeney * @deprecated Use setHTML
6eae5adc42f886ebacac1f714be3f0c9e4b205c1Luke Smith * @param {String | Node | HTMLElement | NodeList | HTMLCollection} content The content to insert
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @chainable
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney return this;
8346e283ad797ef549be70335d3961f4324901baRyan Grove * Returns the node's current content (e.g. innerHTML)
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @method getContent
db006be6df49e087e3df27f259256be08df7a1efMatt Sweeney * @deprecated Use getHTML
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @return {String} The current content
41483addf2a47df89e3a3056f22a16bf4cf87abeMatt Sweeney * Replaces the node's current html content with the content provided.
bc434ac650a27231efd02bc22efb6aa323286ab8Matt Sweeney * Note that this passes to innerHTML and is not escaped.
bc434ac650a27231efd02bc22efb6aa323286ab8Matt Sweeney * Use Y.Ecape.html() to escape HTML, or use set('text') to add as text.
41483addf2a47df89e3a3056f22a16bf4cf87abeMatt Sweeney * @method setHTML
41483addf2a47df89e3a3056f22a16bf4cf87abeMatt Sweeney * @param {String | HTML | Node | HTMLElement | NodeList | HTMLCollection} content The content to insert
41483addf2a47df89e3a3056f22a16bf4cf87abeMatt Sweeney * @chainable
41483addf2a47df89e3a3056f22a16bf4cf87abeMatt SweeneyY.Node.prototype.setHTML = Y.Node.prototype.setContent;
41483addf2a47df89e3a3056f22a16bf4cf87abeMatt Sweeney * Returns the node's current html content (e.g. innerHTML)
41483addf2a47df89e3a3056f22a16bf4cf87abeMatt Sweeney * @method getContent
41483addf2a47df89e3a3056f22a16bf4cf87abeMatt Sweeney * @return {String} The html content
41483addf2a47df89e3a3056f22a16bf4cf87abeMatt SweeneyY.Node.prototype.getHTML = Y.Node.prototype.getContent;
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * Called on each Node instance
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @for NodeList
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @method append
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @see Node.append
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney /** Called on each Node instance
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @method insert
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @see Node.insert
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * Called on each Node instance
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @for NodeList
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @method appendChild
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @see Node.appendChild
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney 'appendChild',
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney /** Called on each Node instance
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @method insertBefore
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @see Node.insertBefore
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney 'insertBefore',
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney /** Called on each Node instance
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @method prepend
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @see Node.prepend
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney /** Called on each Node instance
bc434ac650a27231efd02bc22efb6aa323286ab8Matt Sweeney * Note that this passes to innerHTML and is not escaped.
bc434ac650a27231efd02bc22efb6aa323286ab8Matt Sweeney * Use Y.Ecape.html() to escape HTML, or use set('text') to add as text.
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @method setContent
db006be6df49e087e3df27f259256be08df7a1efMatt Sweeney * @deprecated Use setHTML
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney 'setContent',
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney /** Called on each Node instance
8ff167b366d7ee96cfc801bb01cd93e3ce573cbfMatt Sweeney * @method getContent
db006be6df49e087e3df27f259256be08df7a1efMatt Sweeney * @deprecated Use getHTML
db006be6df49e087e3df27f259256be08df7a1efMatt Sweeney 'getContent',
db006be6df49e087e3df27f259256be08df7a1efMatt Sweeney /** Called on each Node instance
bc434ac650a27231efd02bc22efb6aa323286ab8Matt Sweeney * @method setHTML
bc434ac650a27231efd02bc22efb6aa323286ab8Matt Sweeney * Note that this passes to innerHTML and is not escaped.
bc434ac650a27231efd02bc22efb6aa323286ab8Matt Sweeney * Use Y.Ecape.html() to escape HTML, or use set('text') to add as text.
db006be6df49e087e3df27f259256be08df7a1efMatt Sweeney /** Called on each Node instance
db006be6df49e087e3df27f259256be08df7a1efMatt Sweeney * @method getHTML