Selecting Nodes by Tag, ID or Class

The most popular methods for selecting nodes are by tag name, or the class and id attributes of the tag. Those are the most popular selectors for CSS files too. So, as you'd expect, dojo.query makes these easy:

As with CSS, you can combine selectors in dojo.query to create Compound Selectors. By smooshing the selectors "a" and "b" against each other, you say "select nodes that have both properties a and b", as in: /* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #000066; font-weight: bold;} .geshifilter .kw2 {color: #003366; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .co1 {color: #009900; font-style: italic;} .geshifilter .coMULTI {color: #009900; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #3366CC;} .geshifilter .nu0 {color: #CC0000;} .geshifilter .me1 {color: #006600;} .geshifilter .re0 {color: #0066FF;}

Things to Make and Do With Queries

dojo.query, like CSS3, can do very complex selecting. But first ... what can you do with the retrieved nodes?

dojo.query returns a standard DOM NodeList, which can be traversed with regular JavaScript array techniques. It has a .length property like any array, and you can loop through it with a for loop. But Dojo provides some more convenient methods:

Applying a Dojo Function to Each Element

Since dojo.query returns a NodeList object, you can feed the results into any NodeList method. Some popular Dojo methods can be tacked right onto a dojo.query. Take for example style() which applies a style to each element queried. The following turns the background color of each element in class disableAble to gray:

Here is a complete list of Dojo methods that can be used in this manner.

• indexOf()
• lastIndexOf()
• coords()
• style()
• styles()
• addClass()
• removeClass()
• place()
• connect()
• orphan()
• adopt()
• addContent()

For Dojo 1.0: if you do a dojo.require("dojo.NodeList-fx"), the following methods will be added to the NodeList object (see API documentation for more information):

• wipeIn()
• wipeOut()
• slideTo()
• fadeIn()
• fadeOut()
• animateProperty()

More General Functions - forEach

New for 1.0forEach() applies a snippet of JavaScript to each node, as described in Functions Used Everywhere. This snippet can use the following "magic" variables:

• item is the DOM node currently being examined
• index is its position in the NodeList, starting from 0
• arr is the entire array of nodes. You can use this to perform lookahead or look-behind. arr[index] === item is always true.

The following code disables all INPUT tags

This call style is supported by forEach(), map(), every(), and some(). dojo.filter() also supports it but the NodeList filter() method does not since it accepts a CSS string expression to filter by instead.

The above only works for Dojo 1.0, but in either 0.9 or 1.0 you can pass a function name or a function literal. The function must take at least one parameter, the first of which is the element being examined. (The rest of the parameters are ignored). So the following code is equivalent to the first example:

Filter

filter() uses a JavaScript function to pare down a list of nodes. The function provided to filter must take a node as input (similar to forEach) and return true if the node is to be kept. It returns a nodeList, just like query. This is especially useful for element selections you cannot express in CSS selector language. For example, odd/even row coloring can be performed this way:

Note that, as we said before, NodelList filter cannot use the new 1.0 snippet syntax. You must pass in a function literal or function name.

Event Handlers

You can attach event handlers to all the nodes of a query. For example, to bind an onclick handler to all elements with the "deadLink" class:

NodeList methods are chainable:

The following are event handler binders available on a NodeList object (the object returned from a dojo.query() call -- see dojo.NodeList API documentation for more information):

• onblur()
• onclick()
• onkeydown()
• onkeypress()
• onkeyup()
• onmousedown()
• onmouseenter()
• onmouseleave()
• onmousemove()
• onmouseout()
• onmouseover()
• onmouseup()

Relative Position Query

An optional second parameter to dojo.query indicates the root node for searching. If a string is passed, dojo.query() assumes it to be the ID of the element to use as the search root, otherwise it will expect a DOM node. In all of our examples so far, the second parameter has been left out, and defaults to document, the root of the HTML page. (Actually, it's dojo.doc, which is "document", but can be modified with dojo.withDocument).

The following shows how the second parameter affects the result:

Standard CSS3 Selectors

Because dojo.query adopts the CSS3 standard for selecting nodes, you can use any CSS reference guide for help on choosing the right queries. Eric Meyer's CSS: The Definitive Guide is a good resource. For convenience, here's a chart of the standard CSS3 selectors, taken from the current working draft RFC.