# Yahoo! UI Library

### node 3.0.0b1

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 `( )`

### Methods

#### 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

Returns: `void`

Chainable: This method is chainable.

#### ancestor

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

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`
  The matching Node instance or null if not found

#### append

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

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

Returns: `void`

Chainable: This method is chainable.

#### appendChild

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

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

Returns: `Node`
  The appended node

#### blur

`void blur ( )`
Passes through to DOM method.

Returns: `void`

Chainable: This method is chainable.

#### cloneNode

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

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

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 ndoe 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 void create ( html , doc )`
Creates 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: `void`

#### delegate

`Event.Handle delegate ( type , fn , selector )`
Functionality to make the node a delegated event container

Parameters:
  `type <String>` the event type to delegate
  `fn <Function>` the function to execute
  `selector <String>` a selector that must match the target of the event.

Returns: `Event.Handle`
  the detach handle

#### each

`void each ( fn , context )`
Applies the given function to each Node in the NodeList.

Parameters:
  `fn <Function>` The function to apply
  `context <Object>` optional An optional context to apply the function with Default context is the NodeList instance

Returns: `void`

Chainable: This method is chainable.
Deprecated Use NodeList

#### focus

`void focus ( )`
Passes through to DOM method.

Returns: `void`

Chainable: This method is chainable.

#### 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

#### 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.

#### 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

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

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

Returns: `Array`
  An array of booleans for each node bound to the NodeList.

#### 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>` The content to insert
  `where <Int | Y.Node | HTMLElement | String>` The position to insert at.

Returns: `void`

Chainable: This method is chainable.

#### insertBefore

`Node insertBefore ( newNode , refNode )`
Passes through to DOM method.

Parameters:
  `newNode <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.

#### item

`Node item ( index )`
Retrieves the Node instance at the given index.

Parameters:
  `index <Number>` The index of the target Node.

Returns: `Node`
  The Node instance at the given index.

Deprecated Use NodeList

#### 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.getDOMNode

`static HTMLNode Node.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.

#### 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

Returns: `void`

#### 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

Returns: `void`

#### prepend

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

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

Returns: `void`

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

#### query

`Node query ( 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.

#### queryAll

`NodeList queryAll ( 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.

#### remove

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

Returns: `void`

Chainable: This method is chainable.

#### removeAttribute

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

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

Returns: `void`

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

Returns: `void`

Chainable: This method is chainable.

#### replaceChild

`Node replaceChild ( node , refNode )`
Passes through to DOM method.

Parameters:
  `node <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

Returns: `void`

Chainable: This method is chainable.

#### reset

`void reset ( )`
Passes through to DOM method. Only valid on FORM elements

Returns: `void`

Chainable: This method is chainable.

#### scrollIntoView

`void scrollIntoView ( )`
Passes through to DOM method.

Returns: `void`

Chainable: This method is chainable.

#### select

`void select ( )`
Passes through to DOM method.

Returns: `void`

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

Returns: `void`

Chainable: This method is chainable.

#### setContent

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

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

Returns: `void`

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.

Returns: `void`

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.

Returns: `void`

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)

Returns: `void`

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)

Returns: `void`

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)

Returns: `void`

Chainable: This method is chainable.

#### simulate

`static 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.

Returns: `void`

#### size

`Int size ( )`
Returns the current number of items in the Node.

Returns: `Int`
  The number of items in the Node.

Deprecated Use NodeList

#### submit

`void submit ( )`
Passes through to DOM method. Only valid on FORM elements

Returns: `void`

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 )`
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

Returns: `void`

Chainable: This method is chainable.

#### Y.get

`static void Y.get ( node , doc , restrict )`
Returns a single Node instance bound to the node or the first element matching the given selector.

Parameters:
  `node <String | HTMLElement>` a node or Selector
  `doc <Y.Node || HTMLElement>` an optional document to scan. Defaults to Y.config.doc.
  `restrict <Boolean>` Whether or not the Node instance should be restricted to accessing its subtree only.

Returns: `void`

### 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

#### restricted `- writeonce Boolean`

Whether or not this Node can traverse outside of its subtree.

#### 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 © 2009 Yahoo! Inc. All rights reserved.