Skip to Content | Skip to Navigation


NodeList

A NodeList is a JavaScript Array that has been decorated with many helpful functions that operate on each member of the array. It is what gets returned as the results of a dojo/query() call.

Usage

When using dojo/query, it returns an instance of NodeList:

require(["dojo/query"], function(query){
  var nodelist = query(".something");
  // nodelist contains an instance of NodeList
});

You can also create an instance of NodeList directly:

require(["dojo/query", "dojo/dom"], function(query, dom){
  var nodelist = query.NodeList();
  nodelist.push(dom.byId("someId"));
  nodelist.push(dom.byId("someOtherId"));
  // nodelist now contains the two DOM nodes
});

Most of the functions that decorate NodeList return the same instance, therefore easily allowing method chaining:

require(["dojo/query", "dojo/NodeList-dom"], function(query){
      // get all "li" elements
    query("ul > li").
      // make them visible but, slightly transparent
      style({ opacity: 0.5, visibility: "visible" }).
      // and set a handler to make a clicked item fully opaque
      onclick(function(e){
        // a node to dojo.query() is a fast way to get a list
        query(e.target).style({ opacity:1 }).toggleClass("clicked");
      });
});

Beyond the basic functionality defined in dojo/query, there are also several other modules which add additional functionality:

Features

The following sections provide an overview of the base functionality provide by dojo/query.

at()

Returns a new NodeList with the items specified by index assuming a 0 based array. Negative values will return values from the end of the NodeList.

require(["dojo/query"], function(query){
  var nodelist = query("ul > li").at(0, -1);
  // nodelist contains first and last nodes of an unordered list
});

The method has the following signature:

NameTypeDescription
indexInteger...

One or more 0-based indices of items in the current NodeList. A negative index will start at the end of the list and go backwards.

concat()

Returns a new NodeList which contains the original list in addition to any passed arguments.

require(["dojo/query"], function(query)){
  var nodelist = query("h1").concat(query("h2"));
  // nodelist contains all the documents headers that are level 1 and 2
}

The signature of the method is:

NameTypeDescription
itemObject

Any number of optional parameters may be passed in to be spliced into the NodeList

end()

Used when “chaining” to revert back to the previous NodeList that generated the current NodeList.

require(["dojo/query", "dojo/NodeList-dom"], function(query){
  query("a")
    // Contains all anchors
      .filter(".disabled")
      // Only contains anchors with class "disabled"
        .style("color", "grey")
   .end()
      // Reverts back to all anchors now
      .style("fontSize", "14px");
});

This function takes no arguments.

every()

Returns true if every node of the NodeList returns true for the supplied function, or false if any element returns false for the supplied function. This works just like dojo/_base/array::every() except the target is implied to be the NodeList.

require(["dojo/query"], function(query){
  if(query(".someclass").every(function(node){
    return node.innerHTML == "hello";
  })){
    // function is true for every node
  }else{
    // function is not true for every node
  }
});

The function has the following signature:

NameTypeDescription
callbackFunction

the callback

thisObjectObject

the context

forEach()

Iterates over every node of the NodeList passing the nodes to a function. This function will process each node. If you want the ability to “short circuit” see every() or some() instead.

require(["dojo/query"], function(query){
  query(".someclass").forEach(function(node){
    // node will be each node in the list.
  });
});

The function has the following signature:

NameTypeDescription
callbackundefined
thisObjundefined

indexOf()

Returns the index of the first occurance of a node in a NodeList. If not found, it returns -1.

require(["dojo/query", "dojo/dom"], function(query, dom){
  var node = dom.byId("someId");
  var idx = query(".someClass").indexOf(node);
  // if idx >= 0 then node has a class of someClass
  // if idx = -1 then node doesn't have class of someClass
});

The function has the following signature:

NameTypeDescription
valueObject

The value to search for.

fromIndexInteger

The location to start searching from. Optional. Defaults to 0.

instantiate()

Instantiates objects for each class, passing the optional configuration object to the constructor. This is similiar to the functionality of the :ref:dojo/parser <dojo/parser> but instead of scanning the DOM for marked up nodes, it uses the nodes in the NodeList.

require(["dojo/query", "dijit/form/Button"], function(query, Button){
  // Converts all button nodes to dijit/form/Buttons
  query("button").instantiate(Button, {
    showLabel: true
  });
});

The function has the following signature:

NameTypeDescription
declaredClassString|Object
propertiesObject

The function returns a NodeList where the members are the instantiated objects.

lastIndexOf()

Returns the index of the last occurance of a node in a NodeList. If the node is not found, the value of -1 is returned.

require(["dojo/query", "dojo/dom"], function(query, dom){
  var node = dom.byId("someId");
  var idx = query(".someClass").lastIndexOf(node);
  // if idx >= 0 then the value is the last occurance of node
  // if idx = -1 then node was not found in the NodeList
});

The function has the following signature:

NameTypeDescription
valueObject

The value to search for.

fromIndexInteger

The location to start searching from. Optional. Defaults to 0.

map()

map() interates all the nodes in the NodeList, passing them to the callback function and then returning a new NodeList with any of the modified results.

require(["dojo/query"], function(query){
  var nodelist = query("h1").map(function(node){
    return node.parentNode;
  });
  // nodelist contains all the parent nodes of every heading level 1 node
});

The function has the following signature:

Name Type Description
callback Function|String The function (or function name in the optional scope object) to apply to each node
thisObj Object The optional scope object to be used as this.

The function returns a NodeList with the returned values of the callback function.

on()

Attaches an event listener to the nodes of the NodeList. This feature leverages dojo/on to provide this mechanism. Please refer to that for additional information.

require("dojo/query", function(query){
  query("button").on("click", function(e){
    console.log("click!");
  });
  // Every button will log "click!" to the console when clicked
});

on() supports event delegation by using selectors as the first argument with the event names as pseudo selectors. For example:

require("dojo/query", function(query){
  query("#mylist").on("li:click", function(e){
    console.log("click!");
  });
  // Listens for onclick events on list items in the list with an ID of "myList"
});

Because on() supports CSS selector syntax, comma deliminated events can be used as well:

require("dojo/query", function(query){
  query("#mylist").on("li button:mouseover, li:click", function(e){
    console.log("hello!");
  });
});

The function has the following signature:

NameTypeDescription
eventNameundefined
listenerundefined

This function returns a NodeList where each node has a remove() function that can be used to remove any listeners.

slice()

Returns a new NodeList that is a “slice” of the source NodeList. Like all array type functions, the indexes are zero based.

require("dojo/query", function(query){
  var nodelist = query("div").slice(0, 3);
  // nodelist contains the first 4 <div> elements
});

The function has the following signature:

NameTypeDescription
beginInteger

Can be a positive or negative integer, with positive integers noting the offset to begin at, and negative integers denoting an offset from the end (i.e., to the left of the end)

endInteger

Optional parameter to describe what position relative to the NodeList's zero index to end the slice at. Like begin, can be positive or negative.

some()

Returns true if any node of the NodeList returns true for the supplied function, or false if no elements return false for the supplied function. This works just like dojo/_base/array::some() except the target is implied to be the NodeList.

require(["dojo/query"], function(query){
  if(query(".someclass").some(function(node){
    return node.innerHTML == "hello";
  })){
    // function is true for at least one node
  }else{
    // function is not true for any node
  }
});

The function has the following signature:

NameTypeDescription
callbackFunction

the callback

thisObjectObject

the context

splice()

Returns a new NodeList that is a manipulated version based on the passed arguments that may insert new nodes or remove nodes.

require(["dojo/query"], function(query){
  var nodelist = query("div").splice(0, 3);
  // nodelist contains a list with the first 3 elements spliced out
  // from the source
});

The function has the following signature:

NameTypeDescription
indexInteger

begin can be a positive or negative integer, with positive integers noting the offset to begin at, and negative integers denoting an offset from the end (i.e., to the left of the end)

howmanyInteger

Optional parameter to describe what position relative to the NodeList's zero index to end the slice at. Like begin, can be positive or negative.

itemObject...

Any number of optional parameters may be passed in to be spliced into the NodeList

Other

In addition, standard JavaScript Array functions will also work, like push(), pop(), shift() and unshift(). Since NodeList is essentially a JavaScript array that has been extended, these core array functions are provided by the underlying JavaScript engine.

Extending

NodeList is specifically designed to be extended, which is exactly what the other dojo/NodeList-* modules do. By using dojo/_base/lang::extend() you can add functionality to the NodeList quite easily. It is recommended that you do this via creating an AMD module.

For example, create a custom module named myapp/NodeList-custom.js:

define(["dojo/_base/lang", "dojo/query", "dojo/NodeList-dom"], function(lang, query){
  lang.extend(query.NodeList, {
    makeRed: function(){
      this.style({ color: "red" });
      return this;
    }
  });
});

And then to use the extension:

require(["dojo/query", "myapp/NodeList-custom"], function(query){
  query(".geenText").makeRed();
});

It is important that you return an instance of NodeList for chaining to work as expected, which in most cases will be return this;.

Examples

Provides an example of working with a NodeList in an array like fashion.

require(["dojo/query", "dojo/dom", "dojo/dom-construct", "dojo/json", "dojo/on", "dojo/domReady!"],
function(query, dom, domConst, JSON, on){
  query("button").on("click", function(e){
    var nodelist = query("li");
    domConst.place("<p>Length: " + nodelist.length, dom.byId("output"));
    var ih = [];
    nodelist.slice(0, 3).forEach(function(node){
      ih.push(node.innerHTML);
    });
    domConst.place("<pre>" + JSON.stringify(ih) + "</pre>", dom.byId("output"));
  });
});
<button id="start" type="button">Start</button>
<div id="content">
  <div class="test1"></div>
  <div class="test1">
    <ul>
      <li>Item 1</li>
      <li>Item 2</li>
      <li>Item 3</li>
      <li>Item 4</li>
      <li>Item 5</li>
      <li>Item 6</li>
    </ul>
  </div>
</div>
<h2>Output</h2>
<div id="output"></div>

See Also