Yahoo! UI Library

node  3.3.0pr1

Yahoo! UI Library > node > Node
Search:
 
Filters

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.

_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 )
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: 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.

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

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.

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.

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

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 ( )
Removes the node from its parent. Shortcut for myNode.get('parentNode').removeChild(myNode);
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 )
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
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).

Classes

Copyright © 2010 Yahoo! Inc. All rights reserved.