NodeList Class
The NodeList class provides a wrapper for manipulating DOM NodeLists. NodeList properties can be accessed via the set/get methods. Use Y.all() to retrieve NodeList instances.
Constructor
NodeList
-
nodes
Parameters:
-
nodesString | Element | Node | ArrayA selector, DOM element, Node, list of DOM elements, or list of Nodes with which to populate this NodeList.
Index
Methods
- addClass
- after
- append
- appendChild
- clearData
- concat
- destroy
- detach
- detachAll
- each
- empty
- even
- filter
- generateID
- get
- getAttribute
- getAttribute
- getComputedStyle
- getData
- getDOMNodes
- getDOMNodes static
- getHTML
- getStyle
- hasClass
- hide
- importMethod static
- indexOf
- insert
- insertBefore
- isEmpty
- item
- modulus
- odd
- on
- once
- onceAfter
- plug
- pop
- prepend
- push
- refresh
- remove
- removeAttribute
- removeClass
- replaceClass
- set
- setAttribute
- setAttribute
- setData
- setHTML
- setStyle
- setStyles
- shift
- show
- size
- slice
- some
- splice
- toFrag
- toggleClass
- toggleView
- transition
- unplug
- unshift
- unwrap
- wrap
Properties
Methods
addClass
-
className
Adds a class name to each node.
Parameters:
-
classNameStringthe class name to add to each node's class attribute
after
-
type -
fn -
context
Applies an event listener to each Node bound to the NodeList. The handler is called only after all on() handlers are called and the event is not prevented.
Parameters:
-
typeStringThe event being listened for
-
fnFunctionThe handler to call when the event fires
-
contextObjectThe context to call the handler with. Default is the NodeList instance.
Returns:
A subscription handle capable of detaching that subscription
append
()
Called on each Node instance
appendChild
()
Called on each Node instance
clearData
-
name
Clears data on all Node instances bound to the NodeList.
Parameters:
-
nameStringThe name of the field to clear. If no name is given, all data is cleared.
concat
-
valueN
Parameters:
-
valueNNodeList | ArrayArrays/NodeLists and/or values to concatenate to the resulting NodeList
Returns:
A new NodeList comprised of this NodeList joined with the input.
destroy
-
recursivePurge
Called on each Node instance. Nulls internal node references, removes any plugins and event listeners
Parameters:
-
recursivePurgeBoolean(optional) Whether or not to remove listeners from the node's subtree (default is false)
detach
()
Called on each Node instance
detachAll
()
each
-
fn -
context
Applies the given function to each Node in the NodeList.
Parameters:
-
fnFunctionThe function to apply. It receives 3 arguments: the current node instance, the node's index, and the NodeList instance
-
contextObjectoptional An optional context to apply the function with Default context is the current Node instance
empty
()
chainable
Called on each Node instance. Removes and destroys all of the nodes within the node
even
()
NodeList
Creates a new NodeList containing all nodes at even indices (zero-based index), including zero.
Returns:
NodeList containing the updated collection
filter
-
selector
Filters the NodeList instance down to only nodes matching the given selector.
Parameters:
-
selectorStringThe selector to filter against
Returns:
NodeList containing the updated collection
generateID
()
String
Applies a unique ID to each node if none exists
Returns:
The existing or generated ID
get
()
getAttribute
-
name
Allows getting attributes on DOM nodes, normalizing in some cases. This passes through to the DOM node, allowing for custom attributes.
Parameters:
-
nameStringThe attribute name
Returns:
The attribute value
getAttribute
-
name
Allows getting attributes on DOM nodes, normalizing in some cases. This passes through to the DOM node, allowing for custom attributes.
Parameters:
-
nameStringThe attribute name
Returns:
The attribute value
getComputedStyle
-
attr
Returns an array of the computed value for each node. Use camelCase (e.g. 'backgroundColor') for multi-word properties.
Parameters:
-
attrStringThe style attribute to retrieve.
Returns:
The computed values for each node.
getData
-
name
Retrieves arbitrary data stored on each Node instance bound to the NodeList.
Parameters:
-
nameStringOptional name of the data field to retrieve. If no name is given, all data is returned.
Returns:
An array containing all of the data for each Node instance. or an object hash of all fields.
getDOMNodes
()
Array
Returns the DOM node bound to the Node instance
Returns:
getDOMNodes
-
nodelist
Retrieves the DOM nodes bound to a NodeList instance
Parameters:
-
nodelistNodeListThe NodeList instance
Returns:
The array of DOM nodes bound to the NodeList
getHTML
()
Called on each Node instance
getStyle
-
attr
Returns an array of values for each node. Use camelCase (e.g. 'backgroundColor') for multi-word properties.
Parameters:
-
attrStringThe style attribute to retrieve.
Returns:
The current values of the style property for the element.
hasClass
-
className
Determines whether each node has the given className.
Parameters:
-
classNameStringthe class name to search for
Returns:
An array of booleans for each node bound to the NodeList.
hide
-
name -
config -
callback
Hides each 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:
-
nameStringA named Transition effect to use as the show effect.
-
configObjectOptions to use with the transition.
-
callbackFunctionAn optional function to run after the transition completes.
importMethod
-
host -
name -
[altName]
Import the named method, or methods from the host onto NodeList.
Parameters:
-
hostObjectThe object containing the methods to copy. Typically a prototype.
-
nameString | StringThe name, or an Array of names of the methods to import onto NodeList.
-
[altName]String optionalAn alternative name to use for the method added to NodeList, which may differ from the name of the original host object. Has no effect if <em>name</em> is an array of method names.
indexOf
-
node
Returns the index of the node in the NodeList instance or -1 if the node isn't found.
Parameters:
-
nodeNode | HTMLElementthe node to search for
Returns:
the index of the node value or -1 if not found
insert
()
Called on each Node instance
insertBefore
()
Called on each Node instance
isEmpty
()
Boolean
Determines if the instance is bound to any nodes
Returns:
Whether or not the NodeList is bound to any nodes
item
-
index
Retrieves the Node instance at the given index.
Parameters:
-
indexNumberThe index of the target Node.
Returns:
The Node instance at the given index.
modulus
-
n -
r
Creates a new NodeList containing all nodes at every n indices, where remainder n % index equals r. (zero-based index).
Parameters:
Returns:
NodeList containing the updated collection
odd
()
NodeList
Creates a new NodeList containing all nodes at odd indices (zero-based index).
Returns:
NodeList containing the updated collection
on
-
type -
fn -
[context] -
[arg*]
Subscribe a callback function for each Node in the collection to execute
in response to a DOM event.
NOTE: Generally, the on() method should be avoided on NodeLists, in
favor of using event delegation from a parent Node. See the Event user
guide for details.
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.
By default, the this object will be the NodeList that the subscription
came from, <em>not the Node that received the event</em>. Use
e.currentTarget to refer to the 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.
Parameters:
-
typeStringThe name of the event
-
fnFunctionThe callback to execute in response to the event
-
[context]Object optionalOverride
thisobject in callback -
[arg*]Any optional0..n additional arguments to supply to the subscriber
Returns:
A subscription handle capable of detaching that subscription
Example:
Y.all(".sku").on("keydown", function (e) {
if (e.keyCode === 13) {
e.preventDefault();
// Use e.currentTarget to refer to the individual Node
var item = Y.MyApp.searchInventory( e.currentTarget.get('value') );
// etc ...
}
});once
-
type -
fn -
context
Applies an one-time event listener to each Node bound to the NodeList.
Parameters:
-
typeStringThe event being listened for
-
fnFunctionThe handler to call when the event fires
-
contextObjectThe context to call the handler with. Default is the NodeList instance.
Returns:
A subscription handle capable of detaching that subscription
onceAfter
-
type -
fn -
context
Applies an one-time event listener to each Node bound to the NodeList that will be called only after all on() handlers are called and the event is not prevented.
Parameters:
-
typeStringThe event being listened for
-
fnFunctionThe handler to call when the event fires
-
contextObjectThe context to call the handler with. Default is the NodeList instance.
Returns:
A subscription handle capable of detaching that subscription
plug
-
P -
config
Adds a plugin to each node in the NodeList. This will instantiate the plugin and attach it to the configured namespace on each node
Parameters:
-
PFunction | Object | ArrayAccepts the plugin class, or an object with a "fn" property specifying the plugin class and a "cfg" property specifying the configuration for the Plugin. <p> Additionally an Array can also be passed in, with the above function or object values, allowing the user to add multiple plugins in a single call. </p>
-
configObject(Optional) If the first argument is the plugin class, the second argument can be the configuration for the plugin.
pop
()
Node | null
Returns:
The last item in the NodeList, or null if the list is empty.
prepend
()
Called on each Node instance
push
-
nodes
Parameters:
-
nodesNode | HTMLElementOne or more nodes to add to the end of the NodeList.
refresh
()
chainable
Reruns the initial query, when created using a selector query
remove
-
destroy
Called on each Node instance. Removes the node from its parent. Shortcut for myNode.get('parentNode').removeChild(myNode);
Parameters:
-
destroyBooleanwhether or not to call destroy() on the node after removal.
removeAttribute
-
name
Allows for removing attributes on DOM nodes. This passes through to the DOM node, allowing for custom attributes.
Parameters:
-
nameStringThe attribute to remove
removeClass
-
className
Removes a class name from each node.
Parameters:
-
classNameStringthe class name to remove from each node's class attribute
replaceClass
-
oldClassName -
newClassName
Replace a class with another class for each node. If no oldClassName is present, the newClassName is simply added.
Parameters:
-
oldClassNameStringthe class name to be replaced
-
newClassNameStringthe class name that will be replacing the old class name
set
-
attr -
val
Called on each Node instance. 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:
-
attrStringThe attribute to be set.
-
valAnyThe value to set the attribute to.
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:
-
nameStringThe attribute name
-
valueStringThe value to set
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:
-
nameStringThe attribute name
-
valueStringThe value to set
setData
-
name -
val
Stores arbitrary data on each Node instance bound to the NodeList. This is not stored with the DOM node.
Parameters:
-
nameStringThe name of the field to set. If no name is given, name is treated as the data and overrides any existing data.
-
valAnyThe value to be assigned to the field.
setHTML
()
Called on each Node instance
Note that this passes to innerHTML and is not escaped.
Use <a href="../classes/Escape.html#method_html">Y.Escape.html()</a>
to escape html content or set('text') to add as text.
setStyle
-
attr -
val
Sets a style property on each node. Use camelCase (e.g. 'backgroundColor') for multi-word properties.
Parameters:
-
attrStringThe style attribute to set.
-
valString | NumberThe value.
setStyles
-
hash
Sets multiple style properties on each node. Use camelCase (e.g. 'backgroundColor') for multi-word properties.
Parameters:
-
hashObjectAn object literal of property:value pairs.
shift
()
Node | null
Returns:
The first item in the NodeList, or null if the NodeList is empty.
show
-
name -
config -
callback
Makes each 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:
-
nameStringA named Transition effect to use as the show effect.
-
configObjectOptions to use with the transition.
-
callbackFunctionAn optional function to run after the transition completes.
size
()
Number
Returns the current number of items in the NodeList.
Returns:
The number of items in the NodeList.
slice
-
begin -
end
Parameters:
-
beginNumberZero-based index at which to begin extraction. As a negative index, start indicates an offset from the end of the sequence. slice(-2) extracts the second-to-last element and the last element in the sequence.
-
endNumberZero-based index at which to end extraction. slice extracts up to but not including end. slice(1,4) extracts the second element through the fourth element (elements indexed 1, 2, and 3). As a negative index, end indicates an offset from the end of the sequence. slice(2,-1) extracts the third element through the second-to-last element in the sequence. If end is omitted, slice extracts to the end of the sequence.
Returns:
A new NodeList comprised of this NodeList joined with the input.
some
-
fn -
context
Executes the function once for each node until a true value is returned.
Parameters:
-
fnFunctionThe function to apply. It receives 3 arguments: the current node instance, the node's index, and the NodeList instance
-
contextObjectoptional An optional context to execute the function from. Default context is the current Node instance
Returns:
Whether or not the function returned true for any node.
splice
-
index -
howMany
Parameters:
-
indexNumberIndex at which to start changing the array. If negative, will begin that many elements from the end.
-
howManyNumberAn integer indicating the number of old array elements to remove. If howMany is 0, no elements are removed. In this case, you should specify at least one new element. If no howMany parameter is specified (second syntax above, which is a SpiderMonkey extension), all elements after index are removed. {Node | HTMLElement| element1, ..., elementN The elements to add to the array. If you don't specify any elements, splice simply removes elements from the array.
Returns:
The element(s) removed.
toFrag
()
Node
Creates a documenFragment from the nodes bound to the NodeList instance
Returns:
a Node instance bound to the documentFragment
toggleClass
-
className
For each node, if the className exists on the node it is removed, if it doesn't exist it is added.
Parameters:
-
classNameStringthe class name to be toggled
toggleView
-
[on] -
[callback]
Displays or hides each node. If the "transition" module is loaded, toggleView optionally animates the toggling of the nodes using given named effect.
Parameters:
-
[on]Boolean optionalAn optional boolean value to force the nodes to be shown or hidden
-
[callback]Function optionalAn optional function to run after the transition completes.
transition
-
config -
callback -
callbackOnce
Animate one or more css properties to a given value. Requires the "transition" module. <pre>example usage: Y.all('.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'
}
});
</pre>
Parameters:
-
configObjectAn object containing one or more style properties, a duration and an easing.
-
callbackFunctionA function to run after the transition has completed. The callback fires once per item in the NodeList.
-
callbackOnceBooleanIf true, the callback will be called only after the last transition has completed
unplug
-
plugin
Removes a plugin from all nodes in the NodeList. This will destroy the plugin instance and delete the namespace each node.
Parameters:
-
pluginString | FunctionThe namespace of the plugin, or the plugin class with the static NS namespace property defined. If not provided, all registered plugins are unplugged.
unwrap
()
chainable
Removes the parent node from node in the list.
wrap
-
html
Wraps the given HTML around each node.
Parameters:
-
htmlStringThe markup to wrap around the node.
Properties
_nodes
Unknown
private
The underlying array of DOM nodes bound to the Y.NodeList instance