The Node class provides a wrapper for manipulating DOM Nodes.
Node properties can be accessed via the set/get methods.
Use Y.one() to retrieve Node instances.
NOTE: Node properties are accessed using
the set and get methods.
Nodenode
node
DOMNode
the DOM node to be mapped to the Node instance.
_getattr
Helper method for get.
attr
String
The attribute
_getFullTypetype
Returns the fully qualified type, given a short type string. That is, returns "foo:bar" when given "bar" if "foo" is the configured prefix.
NOTE: This method, unlike _getType, does no checking of the value passed in, and is designed to be used with the low level _publish() method, for critical path implementations which need to fast-track publish for performance reasons.
type
String
The short type to prefix
_getTypeIf the instance has a prefix attribute and the event type is not prefixed, the instance prefix is applied to the supplied type.
_hideThe implementation for hiding nodes. Default is to set the hidden attribute to true and set the CSS style.display to 'none'.
_ioCompletecode
response
args
The default IO complete handler.
_monitorwhat
eventType
o
This is the entry point for the event monitoring system. You can monitor 'attach', 'detach', 'fire', and 'publish'. When configured, these events generate an event. click -> clickattach, clickdetach, click_publish -- these can be subscribed to like other events to monitor the event system. Inividual published events can have monitoring turned on or off (publish can't be turned off before it it published) by setting the events 'monitor' config.
what
String
'attach', 'detach', 'fire', or 'publish'
eventType
String | CustomEvent
The prefixed name of the event being monitored, or the CustomEvent object.
o
Object
Information about the event interaction, such as fire() args, subscription category, publish config
_parseTypeReturns an array with the detach key (if provided), and the prefixed event name from _getType Y.on('detachcategory| menu:click', fn)
_publishfullType
etOpts
ceOpts
The low level event publish implementation. It expects all the massaging to have been done
outside of this method. e.g. the type to fullType conversion. It's designed to be a fast
path publish, which can be used by critical code paths to improve performance.
etOpts or ceOpts, this will
be the default CustomEvent instance, and can be configured independently.
_showThe implementation for showing nodes. Default is to remove the hidden attribute and reset the CSS style.display property.
addClassclassName
Adds a class name to each node.
className
String
the class name to add to the node's class attribute
addMethodname
fn
context
Adds methods to the Y.Node prototype, routing through scrubVal.
addTargeto
Registers another EventTarget as a bubble target. Bubble order is determined by the order registered. Multiple targets can be specified.
Events can only bubble if emitFacade is true.
Included in the event-custom-complex submodule.
o
EventTarget
the target to add
aftertype
fn
[context]
[arg*]
Subscribe to a custom event hosted by this object. The supplied callback will execute after any listeners add via the subscribe method, and after the default function, if configured for the event, has executed.
allselector
Retrieves a NodeList based on the given CSS selector.
selector
String
The CSS selector to test against.
ancestorfn
testSelf
stopFn
Returns the nearest ancestor that passes the test applied by supplied boolean method.
fn
String | Function
A selector string or boolean method for testing elements. If a function is used, it receives the current node being tested as the only argument. If fn is not passed as an argument, the parent node will be returned.
testSelf
Boolean
optional Whether or not to include the element in the scan
stopFn
String | Function
optional A selector string or boolean method to indicate when the search should stop. The search bails when the function returns true or the selector matches. If a function is used, it receives the current node being tested as the only argument.
ancestorsfn
testSelf
Returns the ancestors that pass the test applied by supplied boolean method.
appendcontent
Inserts the content as the lastChild of the node.
content
String | Node | HTMLElement
The content to insert
Use Y.Escape.html()
to escape html content.
appendChildnode
node
String | HTMLElement | Node
Node to be appended
Use Y.Escape.html()
to escape html content.
appendTonode
Appends the node to the given node.
node
Node | HTMLElement
The node to append to
beforeExecutes the callback before a DOM event, custom event or method. If the first argument is a function, it is assumed the target is a method. For DOM and custom events, this is an alias for Y.on.
For DOM and custom events: type, callback, context, 0-n arguments
For methods: callback, object (method host), methodName, context, 0-n arguments
blurPasses through to DOM method.
bubbleevt
Propagate an event. Requires the event-custom-complex module.
evt
CustomEvent
the custom event to propagate
clearDataname
Clears internally stored data.
name
String
The name of the field to clear. If no name is given, all data is cleared.
cloneNodedeep
Passes through to DOM method.
deep
Boolean
Whether or not to perform a deep clone, which includes subtree and attributes
compareTorefNode
Compares nodes to determine if they match. Node instances can be compared to each other and/or HTMLElements.
refNode
HTMLElement | Node
The reference node to compare to the node.
containsneedle
Determines whether the node is an ancestor of another HTML element in the DOM hierarchy.
needle
Node | HTMLElement
The possible node or descendent
createhtml
doc
Creates a new Node using the provided markup string.
html
String
The markup used to create the element.
Use Y.Escape.html()
to escape html content.
doc
HTMLDocument
An optional document context
createhtml
doc
Returns a new dom node using the provided markup string.
html
String
The markup used to create the element
Use Y.Escape.html()
to escape html content.
doc
HTMLDocument
An optional document context
createCaptionPasses through to DOM method. Only valid on TABLE elements
DEFAULT_GETTERname
The default getter for DOM properties Called with instance context (this === the Node instance)
name
String
The attribute/property to look up
DEFAULT_SETTERname
val
The default setter for DOM properties Called with instance context (this === the Node instance)
name
String
The attribute/property being set
val
Any
The value to be set
delegatetype
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.
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
multiple
0..n additional arguments to pass on to the callback function. These arguments will be added after the event object.
destroyrecursivePurge
Nulls internal node references, removes any plugins and event listeners. Note that destroy() will not remove the node from its parent or from the DOM. For that functionality, call remove(true).
recursivePurge
Boolean
(optional) Whether or not to remove listeners from the node's subtree (default is false)
detachtype
fn
context
Detach one or more listeners the from the specified event
type
String | Object
Either the handle to the subscriber or the type of event. If the type is not specified, it will attempt to remove the listener from all hosted events.
fn
Function
The subscribed function to unsubscribe, if not supplied, all subscribers will be removed.
context
Object
The custom object passed to subscribe. This is optional, but if supplied will be used to disambiguate multiple listeners that are the same (e.g., you subscribe many object using a function that lives on the prototype)
detachAlltype
Removes all listeners from the specified event. If the event type is not specified, all listeners from all hosted custom events will be removed.
type
String
The type, or name of the event
emptyRemoves and destroys all of the nodes within the node.
firetype
arguments
Fire a custom event by name. The callback functions will be executed from the context specified when the event was created, and with the following parameters.
If the custom event object hasn't been created, then the event hasn't been published and it has no subscribers. For performance sake, we immediate exit in this case. This means the event won't bubble, so if the intention is that a bubble target be notified, the event must be published on this object first.
The first argument is the event type, and any additional arguments are passed to the listeners as parameters. If the first of these is an object literal, and the event is configured to emit an event facade, that object is mixed into the event facade and the facade is provided in place of the original object.
type
String | Object
The type of the event, or an object that contains a 'type' property.
arguments
Object*
an arbitrary set of parameters to pass to the handler. If the first of these is an object literal and the event is configured to emit an event facade, the event facade will replace that parameter after the properties the object literal contains are copied to the event facade.
focusPasses through to DOM method.
generateIDApplies a unique ID to the node if none exists
getattr
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 queried.
attr
String
The attribute
getAttributename
Allows getting attributes on DOM nodes, normalizing in some cases. This passes through to the DOM node, allowing for custom attributes.
name
String
The attribute name
getAttrsattrs
Returns an object containing the values for the requested attributes.
attrs
Array
an array of attributes to get values
getComputedStyleattr
Returns the computed value for the given style property. Use camelCase (e.g. 'backgroundColor') for multi-word properties.
attr
String
The style attribute to retrieve.
getContentReturns the node's current content (e.g. innerHTML)
getDataname
Retrieves arbitrary data stored on a Node instance. If no data is associated with the Node, it will attempt to retrieve a value from the corresponding HTML data attribute. (e.g. node.getData('foo') will check node.getAttribute('data-foo')).
name
String
Optional name of the data field to retrieve. If no name is given, all data is returned.
getDOMNodenode
Retrieves the DOM node bound to a Node instance
node
Node | HTMLNode
The Node instance or an HTMLNode
getDOMNodeReturns the DOM node bound to the Node instance
getElementsByTagNametagName
Passes through to DOM method.
tagName
String
The tagName to collect
getEventtype
prefixed
Returns the custom event of the provided type has been created, a falsy value otherwise
getHTMLReturns the node's current html content (e.g. innerHTML)
getStyleattr
Returns the style's current value. Use camelCase (e.g. 'backgroundColor') for multi-word properties.
attr
String
The style attribute to retrieve.
getTargetsReturns an array of bubble targets for this object.
getXGets the current position of the node in page coordinates.
getXYGets the current position of the node in page coordinates.
getYGets the current position of the node in page coordinates.
hasAttributeattribute
Passes through to DOM method.
attribute
String
The attribute to test for
hasChildNodesPasses through to DOM method.
hasClassclassName
Determines whether each node has the given className.
className
String
the class name to search for
hidename
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.
importMethodhost
name
altName
context
Imports utility methods to be added as Y.Node methods.
inDocdoc
Determines whether the node is appended to the document.
doc
Node | HTMLElement
optional An optional document to check against. Defaults to current document.
inRegionnode2
all
altRegion
Determines whether or not the node is within the giving region.
insertcontent
where
Inserts the content before the reference node.
content
String | Node | HTMLElement | NodeList | HTMLCollection
The content to insert
Use Y.Escape.html()
to escape html content.
where
Int | Node | HTMLElement | String
The position to insert at. Possible "where" arguments
insertBeforenewNode
refNode
newNode
String | HTMLElement | Node
Node to be appended
refNode
HTMLElement | Node
Node to be inserted before
Use Y.Escape.html()
to escape html content.
intersectnode2
altRegion
Compares the intersection of the node with another node or region
invokemethod
a,
Invokes a method on the Node instance
method
String
The name of the method to invoke
a,
Any
b, c, etc. Arguments to invoke the method with.
loadurl
selector
callback
Loads content from the given url and replaces the Node's existing content with the remote content.
nextfn
Returns the next matching sibling. Returns the nearest element node sibling if no method provided.
ontype
fn
[context]
[arg*]
Subscribe a callback function to execute in response to a DOM event or custom event.
Most DOM events are associated with a preventable default behavior such as
link clicks navigating to a new page. Callbacks are passed a DOMEventFacade
object as their first argument (usually called e) that can be used to
prevent this default behavior with e.preventDefault(). See the
DOMEventFacade API for all available properties and methods on the object.
If the event name passed as the first parameter is not a whitelisted DOM event,
it will be treated as a custom event subscriptions, allowing
node.fire('customEventName') later in the code. Refer to the Event user guide
for the full DOM event whitelist.
By default, the this object in the callback will refer to the subscribed
Node.
Returning false from a callback is supported as an alternative to calling
e.preventDefault(); e.stopPropagation();. However, it is recommended to use
the event methods.
Y.one("#my-form").on("submit", function (e) {
e.preventDefault();
// proceed with ajax form submission instead...
});
oncetype
fn
[context]
[arg*]
Listen to a custom event hosted by this object one time.
This is the equivalent to on except the
listener is immediatelly detached when it is executed.
onceAftertype
fn
[context]
[arg*]
Listen to a custom event hosted by this object one time.
This is the equivalent to after except the
listener is immediatelly detached when it is executed.
oneselector
Retrieves a single Node instance, the first element matching the given CSS selector. Returns null if no match found.
selector
String
The CSS selector to test against.
onenode
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.
node
String | HTMLElement
a node or Selector
parseTypetype
[pre=this._yuievt.config.prefix]
Takes the type parameter passed to 'on' and parses out the various pieces that could be included in the type. If the event type is passed without a prefix, it will be expanded to include the prefix one is supplied or the event target is configured with a default prefix.
plugplugin
config
Registers plugins to be instantiated at the class level (plugins which should be plugged into every instance of Node by default).
prependcontent
Inserts the content as the firstChild of the node.
content
String | Node | HTMLElement
The content to insert
Use Y.Escape.html()
to escape html content.
previousfn
Returns the previous matching sibling. Returns the nearest element node sibling if no method provided.
publishtype
opts
Creates a new custom event of the specified type. If a custom event by that name already exists, it will not be re-created. In either case the custom event is returned.
type
String
the type, or name of the event
opts
Object
optional config params. Valid properties are:
purgerecurse
type
Removes event listeners from the node and (optionally) its subtree
removedestroy
Removes the node from its parent. Shortcut for myNode.get('parentNode').removeChild(myNode);
destroy
Boolean
whether or not to call destroy() on the node after removal.
removeAttributeattribute
Passes through to DOM method.
attribute
String
The attribute to be removed
removeChildnode
Passes through to DOM method.
node
HTMLElement | Node
Node to be removed
removeClassclassName
Removes a class name from each node.
className
String
the class name to remove from the node's class attribute
replacenewNode
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);
newNode
Node | HTMLNode
Node to be inserted
replaceChildnode
refNode
node
String | HTMLElement | Node
Node to be inserted
refNode
HTMLElement | Node
Node to be replaced
replaceClassoldClassName
newClassName
Replace a class with another class for each node. If no oldClassName is present, the newClassName is simply added.
resetPasses through to DOM method. Only valid on FORM elements
scrollIntoViewPasses through to DOM method.
scrubValnode
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.
node
Any
The Node instance or an HTMLNode
selectPasses through to DOM method.
setattr
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.
attr
String
The attribute to be set.
val
Any
The value to set the attribute to.
setAttributename
value
Allows setting attributes on DOM nodes, normalizing in some cases. This passes through to the DOM node, allowing for custom attributes.
setAttrsattrMap
Sets multiple attributes.
attrMap
Object
an object of name/value pairs to set
setContentcontent
Replaces the node's current content with the content.
Note that this passes to innerHTML and is not escaped.
Use Y.Escape.html()
to escape html content or set('text') to add as text.
content
String | Node | HTMLElement | NodeList | HTMLCollection
The content to insert
setDataname
val
Stores arbitrary data on a Node instance. This is not stored with the DOM node.
name
String
The name of the field to set. If no val is given, name is treated as the data and overrides any existing data.
val
Any
The value to be assigned to the field.
setHTMLcontent
Replaces the node's current html content with the content provided.
Note that this passes to innerHTML and is not escaped.
Use Y.Escape.html() to escape HTML, or set('text') to add as text.
content
String | HTML | Node | HTMLElement | NodeList | HTMLCollection
The content to insert
setStyleattr
val
Sets a style property of the node. Use camelCase (e.g. 'backgroundColor') for multi-word properties.
setStyleshash
Sets multiple style properties on the node. Use camelCase (e.g. 'backgroundColor') for multi-word properties.
hash
Object
An object literal of property:value pairs.
setXx
Set the position of the node in page coordinates, regardless of how the node is positioned.
x
Int
X value for new position (coordinates are page-based)
setXYxy
Set the position of the node in page coordinates, regardless of how the node is positioned.
xy
Array
Contains X & Y values for new position (coordinates are page-based)
setYy
Set the position of the node in page coordinates, regardless of how the node is positioned.
y
Int
Y value for new position (coordinates are page-based)
showname
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.
siblingsfn
Returns all matching siblings. Returns all siblings if no method provided.
simulatetype
options
Simulates an event on the node.
simulateGesturename
[options]
[cb]
Simulates the higher user level gesture of the given name on this node.
This method generates a set of low level touch events(Apple specific gesture
events as well for the iOS platforms) asynchronously. Note that gesture
simulation is relying on Y.Event.simulate() method to generate
the touch events under the hood. The Y.Event.simulate() method
itself is a synchronous method.
Supported gestures are tap, doubletap, press, move, flick, pinch
and rotate.
The pinch gesture is used to simulate the pinching and spreading of two
fingers. During a pinch simulation, rotation is also possible. Essentially
pinch and rotate simulations share the same base implementation to allow
both pinching and rotation at the same time. The only difference is pinch
requires start and end option properties while rotate requires rotation
option property.
The pinch and rotate gestures can be described as placing 2 fingers along a
circle. Pinching and spreading can be described by start and end circles while
rotation occurs on a single circle. If the radius of the start circle is greater
than the end circle, the gesture becomes a pinch, otherwise it is a spread spread.
name
String
The name of the supported gesture to simulate. The supported gesture name is one of "tap", "doubletap", "press", "move", "flick", "pinch" and "rotate".
[options]
Object
optional
Extra options used to define the gesture behavior:
Valid options properties for the tap gesture:
[point]
Array
optional
(Optional) Indicates the [x,y] coordinates where the tap should be simulated. Default is the center of the node element.
[hold=10]
Number
optional
(Optional) The hold time in milliseconds.
This is the time between touchstart and touchend event generation.
[times=1]
Number
optional
(Optional) Indicates the number of taps.
[delay=10]
Number
optional
(Optional) The number of milliseconds
before the next tap simulation happens. This is valid only when times
is more than 1.
Valid options properties for the doubletap gesture:
[point]
Array
optional
(Optional) Indicates the [x,y] coordinates where the doubletap should be simulated. Default is the center of the node element.
Valid options properties for the press gesture:
[point]
Array
optional
(Optional) Indicates the [x,y] coordinates where the press should be simulated. Default is the center of the node element.
[hold=3000]
Number
optional
(Optional) The hold time in milliseconds.
This is the time between touchstart and touchend event generation.
Default is 3000ms (3 seconds).
Valid options properties for the move gesture:
[path]
Object
optional
(Optional) Indicates the path of the finger
movement. It's an object with three optional properties: point,
xdist and ydist.
[point]
Array
optional
[xdist=200]
Number
optional
[ydist=0]
Number
optional
[duration=1000]
Number
optional
(Optional) The duration of the gesture in milliseconds.
Valid options properties for the flick gesture:
[point]
Array
optional
(Optional) Indicates the [x, y] coordinates where the flick should be simulated. Default is the center of the node element.
[axis='x']
String
optional
(Optional) Valid values are either "x" or "y". Indicates axis to move along. The flick can move to one of 4 directions(left, right, up and down).
[distance=200]
Number
optional
(Optional) Distance to move in pixels
[duration=1000]
Number
optional
(Optional) The duration of the gesture in milliseconds. User given value could be automatically adjusted by the framework if it is below the minimum velocity to be a flick gesture.
Valid options properties for the pinch gesture:
[center]
Array
optional
(Optional) The center of the circle where two fingers are placed. Default is the center of the node element.
[r1]
Number
optional
(Required) Pixel radius of the start circle where 2 fingers will be on when the gesture starts. The circles are centered at the center of the element.
[r2]
Number
optional
(Required) Pixel radius of the end circle when this gesture ends.
[duration=1000]
Number
optional
(Optional) The duration of the gesture in milliseconds.
[start=0]
Number
optional
(Optional) Starting degree of the first finger. The value is relative to the path of the north. Default is 0 (i.e., 12:00 on a clock).
[rotation=0]
Number
optional
(Optional) Degrees to rotate from the starting degree. A negative value means rotation to the counter-clockwise direction.
Valid options properties for the rotate gesture:
[center]
Array
optional
(Optional) The center of the circle where two fingers are placed. Default is the center of the node element.
[r1]
Number
optional
(Optional) Pixel radius of the start circle where 2 fingers will be on when the gesture starts. The circles are centered at the center of the element. Default is a fourth of the node element width or height, whichever is smaller.
[r2]
Number
optional
(Optional) Pixel radius of the end circle when this gesture ends. Default is a fourth of the node element width or height, whichever is smaller.
[duration=1000]
Number
optional
(Optional) The duration of the gesture in milliseconds.
[start=0]
Number
optional
(Optional) Starting degree of the first finger. The value is relative to the path of the north. Default is 0 (i.e., 12:00 on a clock).
[rotation]
Number
optional
(Required) Degrees to rotate from the starting degree. A negative value means rotation to the counter-clockwise direction.
[cb]
Function
optional
The callback to execute when the asynchronouse gesture
simulation is completed.
err
Error
An error object if the simulation is failed.
var node = Y.one("#target");
// double tap example
node.simulateGesture("doubletap", function() {
// my callback function
});
// flick example from the center of the node, move 50 pixels down for 50ms)
node.simulateGesture("flick", {
axis: y,
distance: -100
duration: 50
}, function() {
// my callback function
});
// simulate rotating a node 75 degrees counter-clockwise
node.simulateGesture("rotate", {
rotation: -75
});
// simulate a pinch and a rotation at the same time.
// fingers start on a circle of radius 100 px, placed at top/bottom
// fingers end on a circle of radius 50px, placed at right/left
node.simulateGesture("pinch", {
r1: 100,
r2: 50,
start: 0
rotation: 90
});
submitPasses through to DOM method. Only valid on FORM elements
subscribesubscribe to an event
swapotherNode
Swap DOM locations with the given node. This does not change which DOM node each Node instance refers to.
otherNode
Node
The node to swap with
swapXYotherNode
Swaps the XY position of this node with another node.
otherNode
Node | HTMLElement
The node to swap with.
testselector
Test if the supplied node matches the supplied selector.
selector
String
The CSS selector to test against.
toggleClassclassName
force
If the className exists on the node it is removed, if it doesn't exist it is added.
toggleView[name]
[on]
[callback]
Displays or hides the node. If the "transition" module is loaded, toggleView optionally animates the toggling of the node using given named effect.
toStringThe method called when outputting Node instances as strings
transitionconfig
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'
}
});
unplugplugin
Unregisters any class level plugins which have been registered by the Node
unsubscribedetach a listener
unsubscribeAlltype
Removes all listeners from the specified event. If the event type is not specified, all listeners from all hosted custom events will be removed.
type
String
The type, or name of the event
unwrapRemoves the node's parent node.
wraphtml
Wraps the given HTML around the node.
html
String
The markup to wrap around the node.
_nodeThe underlying DOM node bound to the Y.Node instance
DOM_EVENTSList of events that route to DOM events