The DOMMNodeCollection class

Introduction

The DOMMNodeCollection class represents an immutable collection of Nodes. It is the library equivalent of a NodeList. The DOMMNodeCollection, like the DOMMNode class, accepts only ELEMENT_NODE and DOCUMENT_NODE types. The following article describes some of the DOMMNodeCollection methods in detail.

Basic Methods

Creating a DOMMNodeCollection

• DOMMNodeCollection(nodeCollection { Array of DOMMNode objects | Array of Node objects | NodeList}): {DOMMNodeCollection} (Constructor): Creates a new DOMMNodeCollection instance. The DOMMNodeCollection is an immutable collection of native Node objects. It is important to note that the contructor will return a collection containing only nodes which are of type ELEMENT_NODE or DOCUMENT_NODE.

Inserting Items

• push(node {DOMMNode | Node}): {DOMMNodeCollection}: Returns a new collection with the added (pushed) node in the last position. The push() function works only with one input.

  var firstElement = new DOMMNode('<span>');
  var collection = new DOMMNodeCollection([firstElement]);
  var secondElement = new DOMMNode('<div>');
  var newCollection = collection.push(secondElement);
  
  //newCollection -> DOMMNodeCollection {0: span, 1: div, _isImmutable: true, length: 2}

• unshift(node {DOMMNode | Node}): {DOMMNodeCollection}: Returns a new collection with the added (pushed) node in the first position. The unshift() function works only with one input.

  var firstElement = new DOMMNode('<span>');
  var collection = new DOMMNodeCollection([firstElement]);
  var secondElement = new DOMMNode('<div>');
  var newCollection = collection.unshift(secondElement);
  
  //newCollection -> DOMMNodeCollection {0: div, 1: span, _isImmutable: true, length: 2}

Removing Items

• pop(item {DOMMNode | Node}): {DOMMNodeCollection}: Returns a new collection without the top element.

  var firstElement = new DOMMNode('<span>');
  var secondElement = new DOMMNode('<div>');
  var collection = new DOMMNodeCollection([firstElement, secondElement]);
  var newCollection = collection.pop();
  
  //newCollection -> DOMMNodeCollection {0: span, _isImmutable: true, length: 1}

• removeAt(index {integer}): {DOMMNodeCollection}: Returns a cloned collection with one removed node at the input index.

  var firstElement = new DOMMNode('<span>');
  var secondElement = new DOMMNode('<div>');
  var thirdElement = new DOMMNode('<p>');
  var collection = new DOMMNodeCollection([firstElement, secondElement, thirdElement]);
  var newCollection = collection.removeAt(1);//removing the second element
  
  //newCollection -> DOMMNodeCollection {0: span, 1: p, _isImmutable: true, length: 2}

• empty(): {DOMMNodeCollection}: Returns an empty DOMMNodeCollection instance. Note that this method does not change the original collection in any way, because the collection is immutable by definition. This method actually returns a reference to a new empty collection, so it works identically to new DOMMNodeCollection([]).

Accessing Items

There are several methods for getting an element reference. We will examine each of these methods using the following example collection:

var collection = new DOMMNodeCollection([new DOMMNode('<span>'),  new DOMMNode('<div>'), new DOMMNode('<p>'), new DOMMNode('<pre>')]);

• get(index {integer}): {DOMMNode}: Returns the element at the input index wrapped as DOMMNode.

  collection.get(2); //=> DOMMNode { _node: <p> }

• first(): {DOMMNode}: Returns the first element from the collection wrapped as DOMMNode.

  collection.first(); //=> DOMMNode { _node: <span> }

• last(): {DOMMNode}: Returns the last element from the collection wrapped as DOMMNode.

  collection.last(); //=> DOMMNode { _node: <p> }

• peek(): {DOMMNode}: Returns the last (top) element from the collection wrapped as DOMMNode.

  collection.peek(); //=> DOMMNode { _node: <p> }

• hasIndex(index {integer}): {boolean}: Checks if the input index is withing range of the collection indices.

  collection.hasIndex(0); //=> true
  collection.hasIndex(100); //=> false

Merging collections

• concat(right {DOMMNodeCollection}): {DOMMNodeCollection}: Returns a new DOMMNodeCollection instance, containing the current collection (this) to the left of the input collection (the right argument).

  var coll1 = new DOMMNodeCollection([new DOMMNode('<span>'), new DOMMNode('<div>')]);
  var coll2= new DOMMNodeCollection([new DOMMNode('<p>'), new DOMMNode('<pre>')]);
  var newColl = coll1.conca(coll2);//DOMMNodeCollection�{0: p, 1: pre, 2: span, 3: div, _isImmutable: true, length: 4}

• insertBefore(right {DOMMNodeCollection}): {DOMMNodeCollection}: Returns a new DOMMNodeCollection instance and inserts the collection as sublings before specific element.

  var parent = new DOMMNode('<span>');
  var child = new DOMMNode('<title>');
  parent.append(child);
  parent.append(document.createElement('div'));
  parent.append(document.createElement('h1'));
  
  var firstCollChild = new DOMMNode("<div>").text('First Child');
  var secondCollChild = new DOMMNode("<span>").text('Second Child');
  var coll = new DOMMNodeCollection([firstCollChild, secondCollChild]);
  
  coll.insertBefore(child);
  parent.outerHtml();//"<span><div>First Child</div><span>Second Child</span><title></title><div></div><h1></h1></span>"

• insertAfter(right {DOMMNodeCollection}): {DOMMNodeCollection}: Returns a new DOMMNodeCollection instance and inserts the collection as sublings before specific element.

  var parent = new DOMMNode('<span>');
  var child = new DOMMNode('<title>');
  parent.append(child);
  parent.append(document.createElement('div'));
  parent.append(document.createElement('h1'));
  
  var firstCollChild = new DOMMNode("<div>").text('First Child');
  var secondCollChild = new DOMMNode("<span>").text('Second Child');
  var coll = new DOMMNodeCollection([firstCollChild, secondCollChild]);
  
  coll.insertAfter(child);
  parent.outerHtml();//"<span><div></div><h1></h1><title></title><div>First Child</div><span>Second Child</span></span>"

String representation

• toString() : {string}: Returns a string representation of all collection nodes. The function returns a concatenation of the results from a toString() call on each collection item.

  var dnc = new DOMMNodeCollection([new DOMMNode("<div>").classes("fe"), new DOMMNode("<div>").classes("se")]);
  dnc.toString(); //=>"[<div class="fe"></div>, <div class="se"></div>, <div class="ze"></div>]"

Iterating and Filtering

Node Filtering

The DOMMNodeCollection instances hold references to Node objects by definition. Typically, a collection may represent the child nodes of a particular node, or an arbitrary list of nodes resulting from a query on the document. It is reasonable for the DOMMNodeCollection class to have methods for generating node subsets from the original collection, based on some rule. The following methods can be used to perform such filtering:

• filter(selector {string}): {DOMMNodeCollection} : Performs filtering, by using an input css selector string. The function performs similarly to the Element.querySelectorAll(...) (read more here). The allowed selectors, are mentioned here: sizzle. We use sizzle as a selector library.

  var dnc = new DOMMNodeCollection([new DOMMNode("<div>").classes("fe"), new DOMMNode("<div>").classes("se")]);
  var searchedElement = dnc.filter(".fe");//=>DOMMNodeCollection {0: div.fe, _isImmutable: true, length: 1}

• filter(selector {Function}): {DOMMNodeCollection} : Performs filtering, based on an input filter function. The filtering is performed by applying the filter function to each element in the collection. The filter function will receive a target element reference as its first argument. The element passes the filter if the filter function returns true.

  var dnc = new DOMMNodeCollection([new DOMMNode("<div>").classes("fe"), new DOMMNode("<div>").classes("se")]);
  var func = function(node) {
      return node.hasClasses("fe");
  }
  var result = dnc.filter(func);//=>DOMMNodeCollection {0: div.fe, _isImmutable: true, length: 1}

The Foreach Method

• foreach([arg1, arg2, ..., argN-1,] argN {Function(ittobj, arg1, arg2, ..., argN-1)}): Executes the argN function on each collection node. The foreach method can accept an arbitrary number of arguments, but the last argument must always be a function (Function).

  ...

DOMMNode Related Methods

The next group of methods are executed on each of the collection nodes. Basically all of them execute a foreach() at some point.

• detach(): {DOMMNodeCollection}: Detaches all the elements in the collection from their parents.

• remove(): {DOMMNodeCollection}: Detaches all the elements from their parents and removes them from the collection.

• clone(deep {boolean(optional)}): {DOMMNodeCollection}: Returns a deeply cloned collection. Deep - Optional Parameter(true as default). Specifies whether all descendants of the node should be cloned.

      var fe = new DOMMNode("<div>").classes("fe");
      var se = new DOMMNode("<div>").classes("se");
      var feChild = new DOMMNode("<span>");
      fe.append(feChild);
      var dnc = new DOMMNodeCollection([fe, se]);
      var dnc2 = dnc.clone();
      var dnc3 = dnc.clone(false);
      dnc2.asHtml(); //fe has feChild as a child
      //"<div class="fe"><span></span></div><div class="se"></div>"
      dnc3.asHtml(); //fe doesn't have feChild as a child 
      //"<div class="fe"></div><div class="se"></div>"

• isEmpty(): {Boolean}: Check if the DOMMNodeCollection has length

      var coll = new DOMMNodeCollection([new DOMMNode('<span>'), new DOMMNode('<div>')]);
  	coll.isEmpty();//false
  
  	var emptyColl = new DOMMNodeCollection();
  	emptyColl.isEmpty()//true

Class Manipulation

• classes(class {string}): {this}: Sets class to all the elements in the collection.

      var fe = new DOMMNode("<div>").classes("fe");
      var se = new DOMMNode("<div>").classes("se");
      var feChild = new DOMMNode("<span>");
      fe.append(feChild);
      var dnc = new DOMMNodeCollection([fe, se]);
  
      dnc.classes("someClass");
      dnc.asHtml(); //=>"<div class="fe someClass"><span></span></div><div class="se someClass"></div>"

• classes(class1 [, class2, class3 ... classN] {string}): {this}: Adds classes to all elements in the collection.

      var fe = new DOMMNode("<div>").classes("fe");
      var se = new DOMMNode("<div>").classes("se");
      var feChild = new DOMMNode("<span>");
      fe.append(feChild);
      var dnc = new DOMMNodeCollection([fe, se]);
  
      dnc.classes("someClass someOtherClass");
      dnc.asHtml(); //=>"<div class="fe someClass someOtherClass"><span></span></div><div class="se someClass someOtherClass"></div>"

• toggleClasses(class1 [, class2, class3 ... classN] {string}): {this}: Toggles the input classes of all elements in the collection.

      var fe = new DOMMNode("<div>").classes("fe");
      var se = new DOMMNode("<div>").classes("se");
      var feChild = new DOMMNode("<span>");
      fe.append(feChild);
      var dnc = new DOMMNodeCollection([fe, se]);
  
      dnc.toggleClasses("someClass someOtherClass");
      dnc.asHtml(); //=>"<div class="fe someClass someOtherClass"><span></span></div><div class="se someClass someOtherClass"></div>"
  
      dnc.toggleClasses("someClass someOtherClass");
      dnc.asHtml(); //=>"<div class="fe"><span></span></div><div class="se"></div>"

• removeClasses(class1 [, class2, class3 ... classN] {string}): {this}: Removes the input classes of all elements in the collection.

      var fe = new DOMMNode("<div>").classes("fe");
      var se = new DOMMNode("<div>").classes("se");
      var feChild = new DOMMNode("<span>");
      fe.append(feChild);
      var dnc = new DOMMNodeCollection([fe, se]);
  
      dnc.classes("someClass someOtherClass");
      dnc.asHtml(); //=>"<div class="fe someClass someOtherClass"><span></span></div><div class="se someClass someOtherClass"></div>"
  
      dnc.removeClasses("someClass someOtherClass");
      dnc.asHtml(); //=>"<div class="fe"><span></span></div><div class="se"></div>"

• hasClasses(class1 [, class2, class3 ... classN] {string}): {boolean}: Checks if all the input classes are set for all the elements in the collection.

      var fe = new DOMMNode("<div>").classes("fe");
      var se = new DOMMNode("<div>").classes("se");
      var feChild = new DOMMNode("<span>");
      fe.append(feChild);
      var dnc = new DOMMNodeCollection([fe, se]);
      dnc.classes("someClass someOtherClass");
  
      dnc.hasClasses("someClass someOtherClass"); //=>true       
      dnc.hasClasses("someClass"); //=>true       
      dnc.hasClasses("nonExistingClass"); //=>false       
      dnc.hasClasses("nonExistingClass someClass"); //=>false        

Styles Manipulation

• styles(...): {this}: Sets the input styles to all the elements in the collection.

    var fe = new DOMMNode("<div>").classes("fe");
    var se = new DOMMNode("<div>").classes("se");
    var feChild = new DOMMNode("<span>");
    fe.append(feChild);
    var dnc = new DOMMNodeCollection([fe, se]);

    dnc.styles("color", "red");
    dnc.asHtml(); //=>"<div class="fe" style="color: red;"><span></span></div><div class="se" style="color: red;"></div>"

• removeStyles(...): {this}: Remove the styles if they exist in the current node or add them to it if they don't.

    var fe = new DOMMNode("<div>").classes("fe");
    var se = new DOMMNode("<div>").classes("se");
    var feChild = new DOMMNode("<span>");
    fe.append(feChild);
    var dnc = new DOMMNodeCollection([fe, se]);

    dnc.styles("color", "red");
    dnc.asHtml(); //=>"<div class="fe" style="color: red;"><span></span></div><div class="se" style="color: red;"></div>"
    dnc.removeStyles("color");
    dnc.asHtml(); //=>"<div class="fe"><span></span></div><div class="se"></div>"

String representation

• asHtml() : {string}: Returns a string with html representation of the collection.

    var fe = new DOMMNode("<div>").classes("fe");
    var se = new DOMMNode("<div>").classes("se");
    var feChild = new DOMMNode("<span>");
    fe.append(feChild);
    var dnc = new DOMMNodeCollection([fe, se]);
    dnc.asHtml(); //=>"<div class="fe"><span></span></div><div class="se"></div>"

Converting a DOMMNodeCollection to Array

• toArray() : {Array}: Returns an array with the DOMMNodeCollection members.

       var coll = new DOMMNodeCollection([new DOMMNode('<span>'), new DOMMNode('<div>')]);
   	var asArray = coll.toArray();
   	asArray//(2)�[span, div]
   	Array.isArray(asArray)//true