dojo query

dojo/queryreturns a list of DOM nodes based on a CSS selector.

Introduction

dojo/requestand XHR is half of the AJAX story. Once you make a request for data and receive a response,you must change the page. Being able to change the HTML is dependent on locating nodes.

To select DOM nodes in JavaScript,you can use the browser’s native DOM API,but it’s verbose and hard to work with,slow and can differ across browser. For example,retrieving all nodes with the class “progressIndicator” uses this code:

// list every node with the class "progressIndicator":
var list = [];
var nodes = document.getElementsByTagName("*");
// iterate over every node in the document....SLOOOW
for(var x = 0; x < nodes.length; x++){
  // only nodes with the class "progressIndicator":
  if(nodes[x].className == "progressIndicator"){
    // add to array:
    list.push(nodes[x]);
  }
}
console.log(list);

dojo/querygives us a more compact way to do it,and it is often faster,particularly as we ask for more sophisticated kinds of relationships. The following is essentially equivalent to our first example:

require(["dojo/query"], function(query){
  console.log(query(".progressIndicator"));
});
 
 

Usage

Requring in the module is all that is needed:

function(query){
  var nl = query(".someClass");
});
 
 

dojo/queryreturns an instance ofNodeList,which is essentially a JavaScript Array that has been decorated with functions that make it easier to utilise. There are extensions of the baseNodeListthat are available to provide additional functionality:

dojo/NodeList-data- Allows the association of arbitrary data with items of aNodeList.
dojo/NodeList-dom- DOM related functions that are similiar functionality to thedojo/dom-*related modules.
dojo/NodeList-fx- Adds base and core FX support toNodeList.
dojo/NodeList-html- Adds advanced content setting functionality.
dojo/NodeList-manipulate- Functions that allow for manipulation of DOM nodes in similiar way to jQuery.
dojo/NodeList-traverse- Advanced node traversal functions.

The first argument is theselectorwhich is a CSS selector string that identifies the nodes that need to be retrieved. The second argument is an optionalcontextwhich limits the scope of the selector and only children of the will be considered. This can either be a string representing the node ID or a DOM node. For example:

"dojo/query", "dojo/dom"],32); font-weight:bold">function(query, dom){
  ".someClass",160)">"someId");
  // or
  var node = dom.byId("someId");
      nl node);
});
 
 

dojo/queryandNodeListare specifically designed with chaining in mind. Most functions onNodeListreturn an instance ofNodeList. For example:

"dojo/NodeList-dom"],32); font-weight:bold">function(query){
  query("li").forEach(function(node){
    node.innerHTML = "Something";
  }).style("color",160)">"red")
    .style("fontSize",160)">"12px");
});
 
 

Selector Engines

dojo/queryis responsible for loading the appropriate selector engine. There are several different modes whichdojo/querycan run in:

css2(orlite) - This will always use the lite engine,which delegates to the native selector engine if available for anything but very simple queries (like id lookups). When a native selector engine is not available ( IE7 and below),this supports simple,basic CSS2 level queries,consisting of elemental selectors:.class,#id,monospace!important">tag,and*,attribute selectors,and child (>),descendant (space),and union (,) combinators. If the native selector engine is,the engine does not support pseudo classes.
css2.1- This will always use theliteengine when a native selector engine is available. When a native selector engine is not available (IE7 and below),this will loadacme.
css3- This will always use theliteengine when a native selector engine with significant CSS3 support is available. When a CSS3 capable (supporting most features) native selector engine is not available (IE8 and below),monospace!important">acme- Theacmeselector engine with full CSS3 features will be used. This supports certain features that are not available in any native engine (albeit rarely used).

When you are running Dojo in legacy mode (async:false),monospace!important">dojo/querywill run inacmemode. When you are running withasync:truethe default selector engine level iscss3.

The summarize,the two alternate selector engines included with Dojo have the following features (which can be selected explicitly or by the module’s CSS level needs):

acme- Designed to have full CSS3 support,it is about 14KB (minified).
lite- Basic CSS2 level queries,) combinators. With a native selector engine,theliteengine does not support pseudo classes. It is about 2KB (minified).

Specifying the Selector Level

The selector level can be controlled though various mechanisms. The default selector level can be specified in the build profile (seeDojo Builder). The selector engine can be specified as part of your Dojo configuration:

<script data-dojo-config="selectorEngine: 'css2.1',async: true" src="dojo/dojo.js">
</script>

Or:

type="text/javascript">
  var dojoConfig = {
    selectorEngine: "css2.1",
    async: true
  };
</script>
>
 
   

The selector engine level can be specificed as a loader plugin for each module. For example,if the module needed to do a CSS3 level query,you could write:

define(["dojo/query!css3"],32); font-weight:bold">function(query){
    query(".someClass:last-child").style("red");
});
 
   

If Dojo had started with theliteengine,this will ensure that CSS3 support is available,and will loadacmeon older browsers. It is recommended that you use this syntax for modules that explicitly need more complex queries. If your module is using a simpler query,then"dojo/query"or"dojo/query!css2.1"should be used.

Selector Support

The following tables summerize selector engine levels and their support.

Standard CSS2 Selectors

These selectors can be used with any selector engine.

Pattern	Meaning
*	any element
E	an element of type E
E F	an F element descendant of an E element
E > F	an F element child of an E element
E:link
E:visited	an E element being the source anchor of a hyperlink of which the target is not yet visited (:link) or already visited (:visited)
E:active	E:hover
E:focus	an E element during certain user actions
E[foo]	an E element with a “foo” attribute
E[foo=”bar”]	an E element whose “foo” attribute value is exactly equal to “bar”
E[foo~=”bar”]	an E element whose “foo” attribute value is a list of space-separated values,one of which is exactly equal to “bar”
E[hreflang\|=”en”]	an E element whose “hreflang” attribute has a hyphen-separated list of values beginning (from the left) with “en”
E:lang(fr)	an element of type E in language “fr” (the document language specifies how language is determined)
E.warning	an E element whose class is “warning” (the document language specifies how class is determined).
E#myid	an E element with ID equal to “myid”.
S1,S2	union of two selectors,ex: div,span

Additional Selectors Supported By Lite Engine

These selectors are not part of CSS2,but are supported by the lite engine,so effectively then can also be used with any specified selector engine.

E[foo^=”bar”]	an E element whose “foo” attribute value begins exactly with the string “bar”
E[foo$=”bar”]	an E element whose “foo” attribute value ends exactly with the string “bar”
E[foo*=”bar”]	an E element whose “foo” attribute value contains the substring “bar”

Standard CSS2.1 Selectors

To use these selectors,you must specify thecss2.1,monospace!important">css3,oracmeselector engine.

E:first-child	an E element,first child of its parent
E + F	an F element immediately preceded by an E element

Standard CSS3 Selectorscss3or`acme`selector engine.

E ~ F an F element preceded by an E element

E:nth-child(n) E:checked a user interface element E which is checked (for instance a radio-button or checkbox)

E:empty an E element that has no children (including text nodes)

E:root E:nth-last-child(n) E:nth-of-type(n) E:nth-last-of-type(n) E:last-child E:first-of-type E:last-of-type E:only-child E:only-of-type E:target an E element being the target of the referring URI

E:enabled E:disabled a user interface element E which is enabled or disabled

E::first-line the first formatted line of an E element

E::first-letter the first formatted letter of an E element

E::selection the portion of an E element that is currently selected/highlighted by the user

E::before generated content before an E element

E::after generated content after an E element

E:not(s) an E element that does not match simple selector s

Alternate Selector Engines

We can also use other selector engine levels. Both Sizzle and Slick are excellent selector engines that work withdojo/query. AMD/Dojo compatible versions (just wrapped with AMD) are available here:

Once installed,you can use the selector engine module id as specified selector engine level. We could set Sizzle as the query engine for our page:

"selectorEngine: 'sizzle/sizzle'" </script>

or set Slick as the engine for a particular module:

"dojo/query!slick/Source/slick"],160)">".someClass:custom-pseudo").style("red");
});

Note for cross-domain legacy API usage

This use case should be quite rare,but presents a wrinkle worth noting.

When loadingdojo.jscross-domain and electing to use an alternate selector engine not included indojo.jsitself,legacy APIs will not immediately work,since Dojo base does not finish loading until the selector engine is pulled in asynchronously. In this case,it will be necessary to userequire. In a pinch,legacy code can simply be wrapped like so:

"dojo"],32); font-weight:bold">function(dojo){
  dojo.require(/* ... */);
  // etc...
});
 
   

Again,this issueonlyaffects use of legacy APIs when a selector engine is used which is not baked intodojo.js.

Examples

Example Selector Queries

The following tables provide example selector queries and what sort of nodes they would select.

Query	Description
`h3`	All nodes that are heading level 3
h3:first-child	All nodes that are the first children of a`<h3>`header
#main	A node with`id="main"`[1]
#mainh3	All`<h3>`nodes that are contained by a node with`id="main"`[1]
div#main	Only select a node with`id="main"`if it is a`<div>`
div#mainh3	All nodes that are`<h3>`contained in a`<div>`with an`id="main"`
#maindiv>h3	<h3>nodes that are immediate children of a`<div>`contained within a node that has`id="main"`.foo	All nodes with a`class="foo"`
.foo.bar	All nodes that have both`foo`and`bar`classes
#main>h3	<h3>nodes that are immediate children of a node with`id="main"`#main>*	All immediate children of a node with`id="main"`.foo>*	All immediate children of a nodes with a`.foo,.bar`	class="foo"or a`class="bar"`
[foo]	All nodes with an attribute of`foo`
[foo$=\"thud\"]	foowhere the value ends in`thud`
[foo$=thud]	thud
[foo$=\"thudish\"]	thudish
#main[foo$=thud]	thudthat are contained within a node with an`id="main"`#main[title$=thud]	titlewhere the value ends in`id="main"`#mainspan[title$=thud]	<span>nodes with an attribute of`id="main"`[foo\|=\"bar\"]	foowhere the value contains`bar`in a dash seperated list (e.g.`foo="baz-bar-qat"`)
[foo\|=\"bar-baz\"]	bar-bazin a dash seperated list (e.g.`foo="qat-bar-baz-qip"`)
.foo:nth-child(2)	The 2nd children of nodes with a`style="foo"`
>	All immediate childen
>*	All immediate children
>[qux]	All immediate children that have an attribute of`qux`
.foo+span	All nodes that are a`<span>`that are directly after a node with a`.foo~span`	<span>that are siblings that follow a node with a`style="foo"`
#foo~*	All nodes that are siblings that follow a node with an`id="foo"`#foo~	id="foo"#mainspan.foo:not(span:first-child)	<span>with a`class="foo"`but not a`<span>`and the first child of a node with an`id="foo"`.
#mainspan.foo:not(:first-child)	class="foo"but not the first child of a node with an`id="foo"`.#main>h3:nth-child(odd)	<h3>and the odd immediate children of a node with an`id="main"`#mainh3:nth-child(odd)	<h3>and are odd children contained within a node with an`id="main"`#mainh3:nth-child(2n+1)	<h3>
#mainh3:nth-child(even)
#mainh3:nth-child(2n)	Every other nodes that are`#main2>:checked`	#main2>input[type=checkbox]:checked
#main2>input[type=radio]:checked

E ~ F	an F element preceded by an E element
E:nth-child(n)		E:checked	a user interface element E which is checked (for instance a radio-button or checkbox)
E:empty	an E element that has no children (including text nodes)
E:root		E:nth-last-child(n)		E:nth-of-type(n)	E:nth-last-of-type(n)	E:last-child	E:first-of-type	E:last-of-type	E:only-child	E:only-of-type	E:target	an E element being the target of the referring URI
E:enabled	E:disabled	a user interface element E which is enabled or disabled
E::first-line	the first formatted line of an E element
E::first-letter	the first formatted letter of an E element
E::selection	the portion of an E element that is currently selected/highlighted by the user
E::before	generated content before an E element
E::after	generated content after an E element
E:not(s)	an E element that does not match simple selector s