The HTML DOM NodeList interface. Represents a collection of DOM Nodes.
NodeLists have almost the exact same API as NodeCollection, so there are a few caveats to take note of:
1. Unlike NodeCollections, NodeLists are immutable and therefore do not have any of the following functions:
If you want to manipulate a NodeList using these functions, you must retrieve it as a NodeCollection by calling
.toNC() on the NodeList.
2. The following functions return the NodeCollection equivalent of the NodeList instead of the NodeList itself:
- copyWithin (ES6 browsers only)
- fill (ES6 browsers only)
This is because these functions will or may alter live NodeLists, as seen in this example:
var blueThings = $CLS('blue'); // ($CLS is Firebolt's alias for document.getElementsByClassName)
console.log(blueThings.length); // -> 10 (for example)
var ncBlueThings = blueThings.removeClass('blue');
blueThings.length === 0; // -> true (since now there are no elements with the 'blue' class)
ncBlueThing.length === 10; // -> true (since `removeClass` returned the NodeList as a NodeCollection)
Returning a NodeCollection allows for correct functionality when chaining calls originally made on a NodeList, but be aware that a live NodeList saved as a variable may be altered by these functions.
This, however, should not be worrisome since NodeCollections have all of the same functions as NodeLists with the added benefits of being mutable and static (not live).
4. Passing a NodeList (or HTMLCollection) as a parameter to the
NodeCollection#concat() function will add the NodeList itself to the collection instead of merging in its elements. This is because NodeLists and HTMLCollections don't directly inherit from NodeCollection/Array (they are merely given some of their functions), so they are treated as objects instead of arrays. A simple way to fix this is to call
.toNC() on the NodeList/HTMLCollection when passing it as a parameter to
concat like so:
var nodes = $QSA('div.special'),
moreNodes = $TAG('p'),
concatenation = nodes.concat( moreNodes.toNC() );