Let's warm up to dojo.query with a page containing some simple markup as part of a storybook structure. For brevity, only one full scene is included:

<div id="introduction" class="intro">
    <p>
        Once upon a time, long ago...
    </p>
</div>

<div id="scene1" class="scene">...</div>

<div id="scene2" class="scene">
    <p>
        At the table in the <span class="place">kitchen</span>, there were three
bowls of <span class="food">porridge</span>. <span class="person">Goldilocks</span>
was hungry. She tasted the <span class="food">porridge</span> from the first bowl.
    </p>
    <p>
        "This <span class="food">porridge</span> is too hot!" she exclaimed.
    </p>

    <p>
        So, she tasted the <span class="food">porridge</span> from the second bowl.
    </p>

    <p>
        "This <span class="food">porridge</span> is too cold," she said
    </p>
    <p>
        So, she tasted the last bowl of <span class="food">porridge</span>.
    </p>

    <p>
        "Ahhh, this <span class="food">porridge</span> is just right," she said
happily and she ate it all up.
    </p>
</div>

<div id="scene3" class="scene">...</div>

As was demonstrated in our earlier example, getElementsByTagName returns an array of DOM nodes for a given type. The dojo.query equivalent is to simply provide the tag name as the argument string; so, in order to query a page for all of the div elements, you'd simply use dojo.query("div"), like so:

dojo.query("div")
//Returns [div#introduction.intro, div#scene1.scene, div#scene2.scene,
//div#scene3.scene]

Note that if you want to query against only the children of a particular node instead of the entire page, you can specify a second argument to query using that second argument as the root of the tree. For example, to query only scene2 for paragraph elements instead of the entire page for paragraph elements, provide the second parameter as a node or the id of a node, like so:

dojo.query("p", "scene2")
//Returns [p, p, p, p, p, p]

Querying a page for elements of a specific class is just as simple; just indicate the class you're looking for using CSS query syntax, which, according to the specification, means prefixing the class name with a leading dot. For example, you could query all of the elements that currently have the food class applied to them, like so:

dojo.query(".food")
//Returns [span.food, span.food, span.food, span.food, span.food,
//span.food, span.food]

Combining the ability to query by tag and class is just as easy: combine the two constructs. Consider the case of wanting to query for span elements that have the place class applied:

dojo.query("span.place")
//Returns [span.place]

Selecting a class is handy and all, but there are plenty of times when you'll want to select more than one class. Fortunately, you can accomplish this task using the same simple approach that you've already grown to love. For example, you could select all of the elements having food and place applied thusly:

dojo.query(".food,.place")
//Returns [span.food, span.food, span.food, span.food, span.food, span.food,
//span.food, span.place]

As a final example of the versatility of query, consider the case of finding descendants of a particular node. For our story, let's say that you want to find all of the nodes with the food class applied that are a descendant of scene2 :

dojo.query("#scene2 .food")
//Returns [span.food, span.food, span.food, span.food, span.food, span.food,
//span.food]

Note that the child combinator using the > operator would have returned an empty list because there are no nodes reflecting the food class that are direct children of scene2 :

dojo.query("#scene2 > .food")
//Returns []

Although this example was necessarily brief, a final word worth mentioning is that reducing the search space as much as possible by providing the most specific query that you can has a significant impact on performance.

In addition to the obvious case of finding nodes in the DOM, a powerful facility like dojo.query tends to change the way you solve a lot of common problems because it expands the creative possibilities. As a simple illustration, consider the problem of tracking state in an application, a very common piece of any reasonably complex application's design. Perhaps it involves determining whether a particular section of text is highlighted or not, or perhaps it involves knowing whether some action has already been triggered. While you could introduce explicit variables to track every facet of state, using CSS classes to track state often provides a much more elegant solution to the problem.

For example, suppose that you're developing a cutting-edge new search engine for the web that is capable of tagging entities in the document, and that you've indicated that you'd like to explicitly view people in your search results. Let's assume that your search results contained Shakespeare's play Macbeth, and that you had requested that "people" be tagged in it. You might get the following results:

...
<a rel="person">First Witch</a>
When shall we three meet again
In thunder, lightning, or in rain?

<a rel="person">Second Witch</a>
When the hurlyburly's done,
When the battle's lost and won.

<a rel="person">Third Witch</a>
That will be ere the set of sun.

<a rel="person">First Witch</a>
Where the place?

<a rel="person">Second Witch</a>
Upon the heath.

<a rel="person">Third Witch</a>
There to meet with <a rel="person">Macbeth</a>.

...

function addHighlighting(entityType) {
  var nodes  = document.getElementsByTagName("a");
  for (var i=0; i < nodes.length; i++) {
    if (nodes[i].getAttribute('rel')==entityType) {
      nodes[i].className="highlighted";
    }
  }
}

function removeHighlighting(entityType) {
  var nodes = document.getElementByTagName("a");
  for (var i=0; i < nodes.length; i++) {
    if (nodes[i].getAttribute('rel')==entityType) {
      nodes[i].className="";
    }
  }
}

function addHighlighting(entityType) {
  dojo.query("span[type="+entityType+"]").addClass("highlighted");
}

function removeHighlighting(entityType) {
  dojo.query("span[type="+entityType+"]").removeClass("highlighted");
}

As you may recall, there are several functions available for manipulating arrays that are included in Base. You'll be pleased to know that many of these same methods are available to NodeList. In particular, indexOf, lastIndexOf, every, some, forEach, map, and filter work just like the corresponding functions for an array—although NodeList 's filter function offers some additional features depending on the parameter passed. (More on that shortly.)

To get started, we'll need to create ourselves a NodeList. You can use the same syntax as you would with an array, which explicitly provides some elements to the NodeList, or you can also use a NodeList 's built-in concat method to create a NodeList from an existing Array object.

Here are a few of the possible ways to construct a new NodeList:

var nl = new dojo.NodeList(  ); //create an empty NodeList

var nl = new dojo.NodeList(foo, bar, baz);
//create a NodeList with some existing nodes

var a = [foo, bar, baz];
// suppose there is an existing Array object with some nodes in it

a = nl.concat(a); //turn the  Array into a NodeList

var nl = new dojo.NodeList([foo, bar, baz]);

var nl = new dojo.NodeList(node1,node2,node3,node4,...);

nl.map(
  /* Map some elements... */
  function(x) {
    /* ... */
  }
)
.filter(
  /* And now filter them... */
  function f(x) {
    /* ... */
  }
)
.forEach(
  function(x) {
    /* Now do something with them... */
  }
);

var a0 = new Array(node1,node2,node3,node4,...);

/* Map some elements... */
var a1 = dojo.map(a0,
  function(x) {
    /* ... */
  }
);

/* And now filter... */
var a2 = dojo.filter(a1
  function f(x) {
    /* ... */
  }
);

/* Now do something with them... */
dojo.forEach(a2
  function f(x) {
    /* ... */
  }
);

//Suppose you have a NodeList of numbers
var nums = new dojo.NodeList(1,2,3,4,5,6,7,8,9,10)

//You might benefit from this kind of syntactic sugar instead of intermediate
//state variables along the way

nums
.filter(function(x) {/* ... */})
.map(function(x) { /* ... */})
//next operation...
//you get the idea
;

//Suppose you have an existing NodeList called nl...

//Use the item identifier instead of writing out the entire function wrapper
nl.forEach("console.log(item)");

dojo.query("div")
.forEach(
  /* Print out all divs */
  function f(x) {
    console.log(x);
  })
.filter(".div2") //filter on a specific class and print again.
.forEach(
  /*Now, print only div.div2 divs*/
  function f(x) {
    console.log(x);
   }
  });

Given that you can use CSS query syntax to fetch a list of nodes, it seems entirely possible that you may want to perform style operations on them. For this very reason, NodeList includes a few methods to help you get the job done. NodeList 's style method is especially noteworthy in that it can act as a getter or as a setter depending upon whether you provide a second parameter. This behavior is just like the dojo.style function.

As a reminder of how dojo.style works, recall that dojo.style(someNode, "margin") would return the margin value of a DOM node, while dojo.style(someNode, "margin", "10px") would set the node's margin to a value of 10 pixels.

Manipulating a NodeList is just the same except that there's no need for an explicit first parameter that denotes a particular node anymore. Like any other NodeList function that processed nodes, the method is applied to each node in the list:

// dojo.style approach...
var a = [];

/* load the Array with some nodes */

// iterate over the nodes and apply style
dojo.forEach(a, function(x) {
  dojo.style(x, "margin", "10px");
});

//NodeList approach...
dojo.query( /* some query */ )
.style("margin", "10px");

NodeList also includes methods for adding and removing classes via addClass and removeClass —again, just like the corresponding dojo.addClass and dojo.removeClass functions. That is, you can manually set style properties for elements via style, or explicitly add or remove classes via addClass and removeClass. Note that the style method is especially useful when you don't actually have an existing class that accomplishes the purpose, whereas the addClass and removeClass methods are useful for those times when you already have classes that you want to toggle on or off. Just like style, the syntax is for these methods is predictable:

dojo.query("span.foo", someDomNode).addClass("foo").removeClass("bar");
dojo.query("#bar").style("color","green");

Not surprisingly, a few methods for manipulating the placement of nodes on the page are included as methods of NodeList. You may recognize the coords method, which, like its dojo counterpart, returns an Array containing the coordinate objects for each node in the list. Likewise, NodeList 's place method is similar to dojo.place in that it provides a way to insert the entire NodeList into the DOM in a sequential fashion based on a specific position.

The addContent method, however, is a method that doesn't have a corresponding counterpart elsewhere in the toolkit; it provides a way to add a node or text string to a relative position for each item in a NodeList.

Here's an example of using addContent to insert a text string (which gets wrapped as an inline span) after each page container. This particular example might be useful a method for an application in which you have various displays involving tab and stack containers:

/* Add a footer message after each container identifed by the pageContainer class*/
var nl = dojo.query("div.pageContainer").addContent("footer goes here!", "after");

Recalling that the place method functions by inserting the entire NodeList into the page relative to another node, you might do the following to insert the entire list inside of a container node identified by an id value of debugPane :

var nl = dojo.query("div.someDebugNodes").place("#debugPane", "last");

dojo.coords, like its counterpart, returns an object of key/value pairs that represent the coordinates for each item in the NodeList. Recall that the coords object includes keys for top and left offsets, length and height, and absolute x and y positions, which can be transformed to be relative to a viewport.

dojo.forEach(
  dojo.query("div").coords(  ),
  function(x) { console.log(x); }
);

A somewhat unique method provided by NodeList for placement that does not have a dojo counterpart is its orphan method, which applies a simple filter (single CSS selector—no commas allowed) to each of its elements, and each child element involved in a relationship that matches the filter criteria is removed from the DOM. These child elements that have been removed—or orphaned—are then returned as a new NodeList. The orphan method is often used to remove nodes from the DOM in a much less kludgy manner than the DOM accessor functions otherwise dictate, which is the following pattern for a node called foo : foo.parentNode.removeChild(foo).

For example, to remove all hyperlink elements that are children of a span from the DOM and return them as a new NodeList, you'd do the following:

var nl = dojo.query("span > a").orphan(  )

The adopt method is essentially the inverse of the orphan operator in that it allows you to insert elements back into the DOM. The function is quite flexible, allowing you to pass in a particular DOM node, a query string, or a NodeList. The nodes that will be inserted are positioned relative to the first element in the NodeList that provides the adopt method. The second parameter providing positional information allows for the usual positional information (first, last, after, and before ):

var n = document.createElement("div");
n.innerHTML="foo";
dojo.query("#bar").adopt(n, "last");

Given that you can do just about everything else with a NodeList, you probably won't be too surprised to find out that you can also batch process nodes to respond to particular DOM events such as blurs, mouse movements, and key presses. Firing custom actions in response to one or more DOM events is such a common occurrence that NodeList provides a built-in method for accomplishing this task with ease.

The following DOM events are offered as events for batch processing with NodeList s:

As an example, consider the use case of capturing mouse movement events over a particular element. You'd simply fill in the function for the onmouseover function like so:

dojo.query("#foobar").onmousemove(
  function(evt) {
    console.log(evt); // you should really do something more interesting!
  }
);

The event objects that are available via the DOM Event methods are standardized, because internally dojo.connect is being used. The event model as provided via dojo.connect is standardized in accordance with the W3C specification.

There is no direct way to manage and disconnect the connections you create with NodeList 's connect method, although a future 1.x dot release may provide that ability. If it's not enough to have these connections automatically torn down when the page unloads, you can opt to use the normal dojo.connect method inside of a NodeList 's forEach method if you have a really good reason to manage the connections yourself.

For example, if you needed to manually manage the connections from the previous example, you might do it like so:

var handles =
  dojo.query("a").map(function(x) {
    return dojo.connect(x, "onclick",
      function(evt) { /* ... */ });
  });

/* Sometime later... */
dojo.forEach(handles, function(x) {
  dojo.disconnect(x);
});

Producing animations with DHTML has often been perceived as a bit cumbersome—and it certainly can be. NodeList, however, makes this task just as simple as anything else you can do with a NodeList. From an application development standpoint, that means that you can perform fades trivially, and can even perform more complex operations via the _Animation.animateProperty method.

The methods listed in Table 5.3, “NodeList extensions for animation” involving animation are currently available, but must be explicitly retrieved via a call to dojo.require("dojo.NodeList-fx"). Each of these methods takes an associative array of key/value pairs that provide properties such as the animation duration, position information, colors, etc.

As you might already be thinking, animations are fun to toy around with. Dojo makes this so simple to do. Like anything else in the toolkit, you can just open up the Firebug console and start experimenting. You might start out with simple fades, like so:

dojo.require("dojo.NodeList-fx");

//Once NodeList-fx has loaded...
dojo.query("p").fadeOut(  ).play(  )

Then, when you're ready to begin trying more advanced animations, add some key/value pairs to the associative array and see what happens:

dojo.require("dojo.NodeList-fx");

//Once NodeList-fx has loaded...
dojo.query("div").animateProperty({
  duration: 5000,
  properties: {
    color: {start: "black", end: "green"}
  }
}).play(  );

Note that the actual result of the various effects method is an _Animation object, and that its play method is the standard mechanism for activating it.