# Yahoo! UI Library

### node 3.3.0

Yahoo! UI Library > node > Node
Search:
Filters Show Private Show Protected Show Deprecated

## Class Node

The Node class provides a wrapper for manipulating DOM Nodes. Node properties can be accessed via the set/get methods. Use Y.get() to retrieve Node instances. NOTE: Node properties are accessed using the `set` and `get` methods.

### Constructor

Node `( node )`

Parameters:
  `node <DOMNode>` the DOM node to be mapped to the Node instance.

### Properties

#### _instances - `private static object`

A list of Node instances that have been created

#### _node - `private object`

The underlying DOM node bound to the Y.Node instance

#### ATTRS - `static object`

Static collection of configuration attributes for special handling

#### DOM_EVENTS - `static object`

List of events that route to DOM events

#### NAME - `static object`

The name of the component

### Methods

#### _get

`private any _get ( attr )`
Helper method for get.

Parameters:
  `attr <String>` The attribute

Returns: `any`
  The current value of the attribute

#### _hide

`protected void _hide ( )`
The implementation for hiding nodes. Default is to toggle the style.display property.
Chainable: This method is chainable.

#### _ioComplete

`protected void _ioComplete ( code , response , args )`
The default IO complete handler.

Parameters:
  `code <String>` The response code.
  `response <Object>` The response object.
  `args <Array>` An array containing the callback and selector

#### _show

`protected void _show ( )`
The implementation for showing nodes. Default is to toggle the style.display property.
Chainable: This method is chainable.

#### addClass

`void addClass ( className )`
Adds a class name to each node.

Parameters:
  `className <String>` the class name to add to the node's class attribute

Chainable: This method is chainable.

#### addMethod

`static any addMethod ( name , fn , context )`
Adds methods to the Y.Node prototype, routing through scrubVal.

Parameters:
  `name <String>` The name of the method to add
  `fn <Function>` The function that becomes the method
  `context <Object>` An optional context to call the method with (defaults to the Node instance)

Returns: `any`
  Depends on what is returned from the DOM node.

#### all

`NodeList all ( selector )`
Retrieves a nodeList based on the given CSS selector.

Parameters:
  `selector <string>` The CSS selector to test against.

Returns: `NodeList`
  A NodeList instance for the matching HTMLCollection/Array.

#### ancestor

`Node ancestor ( fn , testSelf )`
Returns the nearest ancestor that passes the test applied by supplied boolean method.

Parameters:
  `fn <String | Function>` A selector string or boolean method for testing elements.
  `testSelf <Boolean>` optional Whether or not to include the element in the scan If a function is used, it receives the current node being tested as the only argument.

Returns: `Node`
  The matching Node instance or null if not found

#### ancestors

`NodeList ancestors ( fn , testSelf )`
Returns the ancestors that pass the test applied by supplied boolean method.

Parameters:
  `fn <String | Function>` A selector string or boolean method for testing elements.
  `testSelf <Boolean>` optional Whether or not to include the element in the scan If a function is used, it receives the current node being tested as the only argument.

Returns: `NodeList`
  A NodeList instance containing the matching elements

#### append

`void append ( content )`
Inserts the content as the lastChild of the node.

Parameters:
  `content <String | Y.Node | HTMLElement>` The content to insert

Chainable: This method is chainable.

#### appendChild

`Node appendChild ( node )`

Parameters:
  `node <String | HTMLElement | Node>` Node to be appended

Returns: `Node`
  The appended node

#### appendTo

`void appendTo ( node )`
Appends the node to the given node.

Parameters:
  `node <Y.Node | HTMLElement>` The node to append to

Chainable: This method is chainable.

#### blur

`void blur ( )`
Passes through to DOM method.
Chainable: This method is chainable.

#### clearData

`void clearData ( name )`
Clears stored data.

Parameters:
  `name <string>` The name of the field to clear. If no name is given, all data is cleared.

Chainable: This method is chainable.

#### cloneNode

`Node cloneNode ( deep )`
Passes through to DOM method.

Parameters:
  `deep <Boolean>` Whether or not to perform a deep clone, which includes subtree and attributes

Returns: `Node`
  The clone

#### compareTo

`Boolean compareTo ( refNode )`
Compares nodes to determine if they match. Node instances can be compared to each other and/or HTMLElements.

Parameters:
  `refNode <HTMLElement | Node>` The reference node to compare to the node.

Returns: `Boolean`
  True if the nodes match, false if they do not.

#### contains

`Boolean contains ( needle )`
Determines whether the node is an ancestor of another HTML element in the DOM hierarchy.

Parameters:
  `needle <Node | HTMLElement>` The possible node or descendent

Returns: `Boolean`
  Whether or not this node is the needle its ancestor

#### create

`static Node create ( html , doc )`
Returns a new dom node using the provided markup string.

Parameters:
  `html <String>` The markup used to create the element
  `doc <HTMLDocument>` An optional document context

Returns: `Node`
  A Node instance bound to a DOM node or fragment

#### createCaption

`void createCaption ( )`
Passes through to DOM method. Only valid on TABLE elements
Chainable: This method is chainable.

#### DEFAULT_GETTER

`static any DEFAULT_GETTER ( name )`
The default getter for DOM properties Called with instance context (this === the Node instance)

Parameters:
  `name <String>` The attribute/property to look up

Returns: `any`
  The current value

#### DEFAULT_SETTER

`static any DEFAULT_SETTER ( name , val )`
The default setter for DOM properties Called with instance context (this === the Node instance)

Parameters:
  `name <String>` The attribute/property being set
  `val <any>` The value to be set

Returns: `any`
  The value

#### delegate

`EventHandle delegate ( type , fn , spec , context , args* )`

Sets up a delegation listener for an event occurring inside the Node. The delegated event will be verified against a supplied selector or filtering function to test if the event references at least one node that should trigger the subscription callback.

Selector string filters will trigger the callback if the event originated from a node that matches it or is contained in a node that matches it. Function filters are called for each Node up the parent axis to the subscribing container node, and receive at each level the Node and the event object. The function should return true (or a truthy value) if that Node should trigger the subscription callback. Note, it is possible for filters to match multiple Nodes for a single event. In this case, the delegate callback will be executed for each matching Node.

For each matching Node, the callback will be executed with its 'this' object set to the Node matched by the filter (unless a specific context was provided during subscription), and the provided event's `currentTarget` will also be set to the matching Node. The containing Node from which the subscription was originally made can be referenced as `e.container`.

Parameters:
  `type <String>` the event type to delegate
  `fn <Function>` the callback function to execute. This function will be provided the event object for the delegated event.
  `spec <String|Function>` a selector that must match the target of the event or a function to test target and its parents for a match
  `context <Object>` optional argument that specifies what 'this' refers to.
  `args* <any>` 0..n additional arguments to pass on to the callback function. These arguments will be added after the event object.

Returns: `EventHandle`
  the detach handle

#### destroy

`void destroy ( recursivePurge )`
Nulls internal node references, removes any plugins and event listeners

Parameters:
  `recursivePurge <Boolean>` (optional) Whether or not to remove listeners from the node's subtree (default is false)

#### empty

`void empty ( destroy )`
Removes all of the child nodes from the node.

Parameters:
  `destroy <Boolean>` Whether the nodes should also be destroyed.

Chainable: This method is chainable.

#### focus

`void focus ( )`
Passes through to DOM method.
Chainable: This method is chainable.

#### generateID

`String generateID ( )`
Applies a unique ID to the node if none exists

Returns: `String`
  The existing or generated ID

#### get

`any get ( attr )`
Returns an attribute value on the Node instance. Unless pre-configured (via Node.ATTRS), get hands off to the underlying DOM node. Only valid attributes/properties for the node will be set.

Parameters:
  `attr <String>` The attribute

Returns: `any`
  The current value of the attribute

#### getAttribute

`string getAttribute ( name )`
Allows getting attributes on DOM nodes, normalizing in some cases. This passes through to the DOM node, allowing for custom attributes.

Parameters:
  `name <string>` The attribute name

Returns: `string`
  The attribute value

#### getAttrs

`Object getAttrs ( attrs )`
Returns an object containing the values for the requested attributes.

Parameters:
  `attrs <Array>` an array of attributes to get values

Returns: `Object`
  An object with attribute name/value pairs.

#### getComputedStyle

`String getComputedStyle ( attr )`
Returns the computed value for the given style property.

Parameters:
  `attr <String>` The style attribute to retrieve.

Returns: `String`
  The computed value of the style property for the element.

#### getContent

`String getContent ( )`
Returns the node's current content (e.g. innerHTML)

Returns: `String`
  The current content

#### getData

`any | Object getData ( name )`
Retrieves arbitrary data stored on a Node instance. This is not stored with the DOM node.

Parameters:
  `name <string>` Optional name of the data field to retrieve. If no name is given, all data is returned.

Returns: `any | Object`
  Whatever is stored at the given field, or an object hash of all fields.

#### getDOMNode

`static HTMLNode getDOMNode ( node )`
Retrieves the DOM node bound to a Node instance

Parameters:
  `node <Y.Node || HTMLNode>` The Node instance or an HTMLNode

Returns: `HTMLNode`
  The DOM node bound to the Node instance. If a DOM node is passed as the node argument, it is simply returned.

#### getElementsByTagName

`NodeList getElementsByTagName ( tagName )`
Passes through to DOM method.

Parameters:
  `tagName <String>` The tagName to collect

Returns: `NodeList`
  A NodeList representing the HTMLCollection

#### getStyle

`String getStyle ( attr )`
Returns the style's current value.

Parameters:
  `attr <String>` The style attribute to retrieve.

Returns: `String`
  The current value of the style property for the element.

#### getX

`Int getX ( )`
Gets the current position of the node in page coordinates.

Returns: `Int`
  The X position of the node

#### getXY

`Array getXY ( )`
Gets the current position of the node in page coordinates.

Returns: `Array`
  The XY position of the node

#### getY

`Int getY ( )`
Gets the current position of the node in page coordinates.

Returns: `Int`
  The Y position of the node

#### hasAttribute

`Boolean hasAttribute ( attribute )`
Passes through to DOM method.

Parameters:
  `attribute <String>` The attribute to test for

Returns: `Boolean`
  Whether or not the attribute is present

#### hasChildNodes

`Boolean hasChildNodes ( )`
Passes through to DOM method.

Returns: `Boolean`
  Whether or not the node has any childNodes

#### hasClass

`Boolean hasClass ( className )`
Determines whether each node has the given className.

Parameters:
  `className <String>` the class name to search for

Returns: `Boolean`
  Whether or not the element has the specified class

#### hide

`void hide ( name , config , callback )`
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.

Parameters:
  `name <String>` A named Transition effect to use as the show effect.
  `config <Object>` Options to use with the transition.
  `callback <Function>` An optional function to run after the transition completes.

Chainable: This method is chainable.

#### importMethod

`static void importMethod ( host , name , altName , context )`
Imports utility methods to be added as Y.Node methods.

Parameters:
  `host <Object>` The object that contains the method to import.
  `name <String>` The name of the method to import
  `altName <String>` An optional name to use in place of the host name
  `context <Object>` An optional context to call the method with

#### inDoc

`Boolean inDoc ( doc )`
Determines whether the node is appended to the document.

Parameters:
  `doc <Node|HTMLElement>` optional An optional document to check against. Defaults to current document.

Returns: `Boolean`
  Whether or not this node is appended to the document.

#### inRegion

`Object inRegion ( node2 , all , altRegion )`
Determines whether or not the node is within the giving region.

Parameters:
  `node2 <Node|Object>` The node or region to compare with.
  `all <Boolean>` Whether or not all of the node must be in the region.
  `altRegion <Object>` An alternate region to use (rather than this node's).

Returns: `Object`
  An object representing the intersection of the regions.

#### insert

`void insert ( content , where )`
Inserts the content before the reference node.

Parameters:
  `content <String | Y.Node | HTMLElement | Y.NodeList | HTMLCollection>` The content to insert
  `where <Int | Y.Node | HTMLElement | String>` The position to insert at. Possible "where" arguments
  Y.Node
    The Node to insert before
  HTMLElement
    The element to insert before
  Int
    The index of the child element to insert before
  "replace"
    Replaces the existing HTML
  "before"
    Inserts before the existing HTML
  "before"
    Inserts content before the node
  "after"
    Inserts content after the node

Chainable: This method is chainable.

#### insertBefore

`Node insertBefore ( newNode , refNode )`

Parameters:
  `newNode <String | HTMLElement | Node>` Node to be appended
  `refNode <HTMLElement | Node>` Node to be inserted before

Returns: `Node`
  The inserted node

#### intersect

`Object intersect ( node2 , altRegion )`
Compares the intersection of the node with another node or region

Parameters:
  `node2 <Node|Object>` The node or region to compare with.
  `altRegion <Object>` An alternate region to use (rather than this node's).

Returns: `Object`
  An object representing the intersection of the regions.

#### invoke

`invoke ( method , a, )`
Invokes a method on the Node instance

Parameters:
  `method <String>` The name of the method to invoke
  `a, <Any>` b, c, etc. Arguments to invoke the method with.

Returns: ``
  Whatever the underly method returns. DOM Nodes and Collections return values are converted to Node/NodeList instances.

#### load

`void load ( html , selector , callback )`
Loads content from the given url and replaces the Node's existing content with it.

Parameters:
  `html <String>` The markup to wrap around the node.
  `selector <String>` An optional selector representing subset
  `callback <Function>` An optional function to run after the content has been loaded. of the content.

Chainable: This method is chainable.

#### next

`Node next ( fn )`
Returns the next matching sibling. Returns the nearest element node sibling if no method provided.

Parameters:
  `fn <String | Function>` A selector or boolean method for testing elements. If a function is used, it receives the current node being tested as the only argument.

Returns: `Node`
  Node instance or null if not found

#### Node.plug

`static void Node.plug ( plugin , config )`
Registers plugins to be instantiated at the class level (plugins which should be plugged into every instance of Node by default).

Parameters:
  `plugin <Function | Array>` Either the plugin class, an array of plugin classes or an array of objects (with fn and cfg properties defined)
  `config <Object>` (Optional) If plugin is the plugin class, the configuration for the plugin

#### Node.unplug

`static void Node.unplug ( plugin )`
Unregisters any class level plugins which have been registered by the Node

Parameters:
  `plugin <Function | Array>` The plugin class, or an array of plugin classes

#### one

`Node one ( selector )`
Retrieves a Node instance of nodes based on the given CSS selector.

Parameters:
  `selector <string>` The CSS selector to test against.

Returns: `Node`
  A Node instance for the matching HTMLElement.

#### prepend

`void prepend ( content )`
Inserts the content as the firstChild of the node.

Parameters:
  `content <String | Y.Node | HTMLElement>` The content to insert

Chainable: This method is chainable.

#### previous

`Node previous ( fn )`
Returns the previous matching sibling. Returns the nearest element node sibling if no method provided.

Parameters:
  `fn <String | Function>` A selector or boolean method for testing elements. If a function is used, it receives the current node being tested as the only argument.

Returns: `Node`
  Node instance or null if not found

#### purge

`void purge ( recurse , type )`
Removes event listeners from the node and (optionally) its subtree

Parameters:
  `recurse <Boolean>` (optional) Whether or not to remove listeners from the node's subtree
  `type <String>` (optional) Only remove listeners of the specified type

Chainable: This method is chainable.

#### remove

`void remove ( destroy )`
Removes the node from its parent. Shortcut for myNode.get('parentNode').removeChild(myNode);

Parameters:
  `destroy <Boolean>` whether or not to call destroy() on the node after removal.

Chainable: This method is chainable.

#### removeAttribute

`void removeAttribute ( attribute )`
Passes through to DOM method.

Parameters:
  `attribute <String>` The attribute to be removed

Chainable: This method is chainable.

#### removeChild

`Node removeChild ( node )`
Passes through to DOM method.

Parameters:
  `node <HTMLElement | Node>` Node to be removed

Returns: `Node`
  The removed node

#### removeClass

`void removeClass ( className )`
Removes a class name from each node.

Parameters:
  `className <String>` the class name to remove from the node's class attribute

Chainable: This method is chainable.

#### replace

`void replace ( newNode )`
Replace the node with the other node. This is a DOM update only and does not change the node bound to the Node instance. Shortcut for myNode.get('parentNode').replaceChild(newNode, myNode);

Parameters:
  `newNode <Y.Node || HTMLNode>` Node to be inserted

Chainable: This method is chainable.

#### replaceChild

`Node replaceChild ( node , refNode )`

Parameters:
  `node <String | HTMLElement | Node>` Node to be inserted
  `refNode <HTMLElement | Node>` Node to be replaced

Returns: `Node`
  The replaced node

#### replaceClass

`void replaceClass ( oldClassName , newClassName )`
Replace a class with another class for each node. If no oldClassName is present, the newClassName is simply added.

Parameters:
  `oldClassName <String>` the class name to be replaced
  `newClassName <String>` the class name that will be replacing the old class name

Chainable: This method is chainable.

#### reset

`void reset ( )`
Passes through to DOM method. Only valid on FORM elements
Chainable: This method is chainable.

#### scrollIntoView

`void scrollIntoView ( )`
Passes through to DOM method.
Chainable: This method is chainable.

#### scrubVal

`static Y.Node | Y.NodeList | any scrubVal ( node )`
Checks Node return values and wraps DOM Nodes as Y.Node instances and DOM Collections / Arrays as Y.NodeList instances. Other return values just pass thru. If undefined is returned (e.g. no return) then the Node instance is returned for chainability.

Parameters:
  `node <any>` The Node instance or an HTMLNode

Returns: `Y.Node | Y.NodeList | any`
  Depends on what is returned from the DOM node.

#### select

`void select ( )`
Passes through to DOM method.
Chainable: This method is chainable.

#### set

`void set ( attr , val )`
Sets an attribute on the Node instance. Unless pre-configured (via Node.ATTRS), set hands off to the underlying DOM node. Only valid attributes/properties for the node will be set. To set custom attributes use setAttribute.

Parameters:
  `attr <String>` The attribute to be set.
  `val <any>` The value to set the attribute to.

Chainable: This method is chainable.

#### setAttribute

`void setAttribute ( name , value )`
Allows setting attributes on DOM nodes, normalizing in some cases. This passes through to the DOM node, allowing for custom attributes.

Parameters:
  `name <string>` The attribute name
  `value <string>` The value to set

Chainable: This method is chainable.

#### setAttrs

`void setAttrs ( attrMap )`
Sets multiple attributes.

Parameters:
  `attrMap <Object>` an object of name/value pairs to set

Chainable: This method is chainable.

#### setContent

`void setContent ( content )`
Replaces the node's current content with the content.

Parameters:
  `content <String | Y.Node | HTMLElement | Y.NodeList | HTMLCollection>` The content to insert

Chainable: This method is chainable.

#### setData

`void setData ( name , val )`
Stores arbitrary data on a Node instance. This is not stored with the DOM node.

Parameters:
  `name <string>` The name of the field to set. If no name is given, name is treated as the data and overrides any existing data.
  `val <any>` The value to be assigned to the field.

Chainable: This method is chainable.

#### setStyle

`void setStyle ( attr , val )`
Sets a style property of the node.

Parameters:
  `attr <String>` The style attribute to set.
  `val <String|Number>` The value.

Chainable: This method is chainable.

#### setStyles

`void setStyles ( hash )`
Sets multiple style properties on the node.

Parameters:
  `hash <Object>` An object literal of property:value pairs.

Chainable: This method is chainable.

#### setX

`void setX ( x )`
Set the position of the node in page coordinates, regardless of how the node is positioned.

Parameters:
  `x <Int>` X value for new position (coordinates are page-based)

Chainable: This method is chainable.

#### setXY

`void setXY ( xy )`
Set the position of the node in page coordinates, regardless of how the node is positioned.

Parameters:
  `xy <Array>` Contains X & Y values for new position (coordinates are page-based)

Chainable: This method is chainable.

#### setY

`void setY ( y )`
Set the position of the node in page coordinates, regardless of how the node is positioned.

Parameters:
  `y <Int>` Y value for new position (coordinates are page-based)

Chainable: This method is chainable.

#### show

`void show ( name , config , callback )`
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.

Parameters:
  `name <String>` A named Transition effect to use as the show effect.
  `config <Object>` Options to use with the transition.
  `callback <Function>` An optional function to run after the transition completes.

Chainable: This method is chainable.

#### siblings

`NodeList siblings ( fn )`
Returns all matching siblings. Returns all siblings if no method provided.

Parameters:
  `fn <String | Function>` A selector or boolean method for testing elements. If a function is used, it receives the current node being tested as the only argument.

Returns: `NodeList`
  NodeList instance bound to found siblings

#### simulate

`void simulate ( type , options )`
Simulates an event on the node.

Parameters:
  `type <String>` The type of event to simulate (i.e., "click").
  `options <Object>` (Optional) Extra options to copy onto the event object.

#### submit

`void submit ( )`
Passes through to DOM method. Only valid on FORM elements
Chainable: This method is chainable.

#### swap

`void swap ( otherNode )`
Swap DOM locations with the given node. This does not change which DOM node each Node instance refers to.

Parameters:
  `otherNode <Node>` The node to swap with

Chainable: This method is chainable.

#### swapXY

`void swapXY ( otherNode )`
Swaps the XY position of this node with another node.

Parameters:
  `otherNode <Y.Node || HTMLElement>` The node to swap with.

Chainable: This method is chainable.

#### test

`boolean test ( selector )`
Test if the supplied node matches the supplied selector.

Parameters:
  `selector <string>` The CSS selector to test against.

Returns: `boolean`
  Whether or not the node matches the selector.

#### toggleClass

`void toggleClass ( className , force )`
If the className exists on the node it is removed, if it doesn't exist it is added.

Parameters:
  `className <String>` the class name to be toggled
  `force <Boolean>` Option to force adding or removing the class.

Chainable: This method is chainable.

#### toString

`String toString ( )`
The method called when outputting Node instances as strings

Returns: `String`
  A string representation of the Node instance

#### transition

`void transition ( config , callback )`
Animate one or more css properties to a given value. Requires the "transition" module.

    example usage:
    Y.one('#demo').transition({
    duration: 1, // in seconds, default is 0.5
    easing: 'ease-out', // default is 'ease'
    delay: '1', // delay start for 1 second, default is 0
    height: '10px',
    width: '10px',
    opacity: { // per property
    value: 0,
    duration: 2,
    delay: 2,
    easing: 'ease-in'
    }
    });

Parameters:
  `config <Object>` An object containing one or more style properties, a duration and an easing.
  `callback <Function>` A function to run after the transition has completed.

Chainable: This method is chainable.

#### unwrap

`void unwrap ( )`
Removes the node's parent node.
Chainable: This method is chainable.

#### wrap

`void wrap ( html )`
Wraps the given HTML around the node.

Parameters:
  `html <String>` The markup to wrap around the node.

Chainable: This method is chainable.

#### Y.one

`static Y.Node | null Y.one ( node )`
Returns a single Node instance bound to the node or the first element matching the given selector. Returns null if no match found. Note: For chaining purposes you may want to use `Y.all`, which returns a NodeList when no match is found.

Parameters:
  `node <String | HTMLElement>` a node or Selector

Returns: `Y.Node | null`
  a Node instance or null if no match found.

### Configuration Attributes

#### children `- NodeList`

Returns a NodeList instance of all HTMLElement children.

#### docHeight `- {Int}`

Document height

#### docScrollX `- {Int}`

Amount page has been scroll vertically

#### docScrollY `- {Int}`

Amount page has been scroll horizontally

#### region `- Node`

Returns a region object for the node

#### text `- String`

Allows for getting and setting the text of an element. Formatting is preserved and special characters are treated literally.

#### viewportRegion `- Node`

Returns a region object for the node's viewport

#### winHeight `- {Int}`

Returns the inner height of the viewport (exludes scrollbar).

#### winWidth `- {Int}`

Returns the inner width of the viewport (exludes scrollbar).

Copyright © 2011 Yahoo! Inc. All rights reserved.