This modules provides DOM querying functionality. The module export is a function that can be used to query for DOM nodes by CSS selector and returns a NodeList representing the matching nodes.
dojo/query is responsible for loading the appropriate query engine and wrapping
its results with a NodeList. You can use dojo/query with a specific selector engine
by using it as a plugin. For example, if you installed the sizzle package, you could
use it as the selector engine with:
require(["dojo/query!sizzle"], function(query){
query("div")...
The id after the ! can be a module id of the selector engine or one of the following values:
acme: This is the default engine used by Dojo base, and will ensure that the full Acme engine is always loaded.
css2: If the browser has a native selector engine, this will be used, otherwise a very minimal lightweight selector engine will be loaded that can do simple CSS2 selectors (by #id, .class, tag, and [name=value] attributes, with standard child or descendant (>) operators) and nothing more.
css2.1: If the browser has a native selector engine, this will be used, otherwise the full Acme engine will be loaded.
css3: If the browser has a native selector engine with support for CSS3 pseudo selectors (most modern browsers except IE8), this will be used, otherwise the full Acme engine will be loaded.
Or the module id of a selector engine can be used to explicitly choose the selector engine
For example, if you are using CSS3 pseudo selectors in module, you can specify that you will need support them with:
require(["dojo/query!css3"], function(query){
query('#t > h3:nth-child(odd)')...
You can also choose the selector engine/load configuration by setting the query-selector: For example:
<script data-dojo-config="query-selector:'css3'" src="dojo.js"></script>
| Parameter | Type | Description |
|---|---|---|
| selector | String | A CSS selector to search for. |
| context | String | DomNode |
Optional An optional context to limit the searching scope. Only nodes under |
See the dojo/query reference documentation for more information.
add an onclick handler to every submit button in the document which causes the form to be sent via Ajax instead:
require(["dojo/query", "dojo/request", "dojo/dom-form", "dojo/dom-construct", "dojo/dom-style"
], function(query, request, domForm, domConstruct, domStyle){
query("input[type='submit']").on("click", function(e){
e.preventDefault(); // prevent sending the form
var btn = e.target;
request.post("http://example.com/", {
data: domForm.toObject(btn.form)
}).then(function(response){
// replace the form with the response
domConstruct.create(div, {innerHTML: response}, btn.form, "after");
domStyle.set(btn.form, "display", "none");
});
});
});
| Parameter | Type | Description |
|---|---|---|
| nodes | undefined | |
| selector | undefined | |
| root | undefined |
can be used as AMD plugin to conditionally load new query engine
| Parameter | Type | Description |
|---|---|---|
| id | undefined | |
| parentRequire | undefined | |
| loaded | undefined |
require(["dojo/query!custom"], function(qsa){
// loaded selector/custom.js as engine
qsa("#foobar").forEach(...);
});
Array-like object which adds syntactic sugar for chaining, common iteration operations, animation, and node manipulation. NodeLists are most often returned as the result of dojo/query() calls.
NodeList instances provide many utilities that reflect core Dojo APIs for Array iteration and manipulation, DOM manipulation, and event handling. Instead of needing to dig up functions in the dojo package, NodeLists generally make the full power of Dojo available for DOM manipulation tasks in a simple, chainable way.
| Parameter | Type | Description |
|---|---|---|
| array | undefined |
create a node list from a node
require(["dojo/query", "dojo/dom"
], function(query, dom){
query.NodeList(dom.byId("foo"));
});
get a NodeList from a CSS query and iterate on it
require(["dojo/on", "dojo/dom"
], function(on, dom){
var l = query(".thinger");
l.forEach(function(node, index, nodeList){
console.log(index, node.innerHTML);
});
});
use native and Dojo-provided array methods to manipulate a NodeList without needing to use dojo.* functions explicitly:
require(["dojo/query", "dojo/dom-construct", "dojo/dom"
], function(query, domConstruct, dom){
var l = query(".thinger");
// since NodeLists are real arrays, they have a length
// property that is both readable and writable and
// push/pop/shift/unshift methods
console.log(l.length);
l.push(domConstruct.create("span"));
// dojo's normalized array methods work too:
console.log( l.indexOf(dom.byId("foo")) );
// ...including the special "function as string" shorthand
console.log( l.every("item.nodeType == 1") );
// NodeLists can be [..] indexed, or you can use the at()
// function to get specific items wrapped in a new NodeList:
var node = l[3]; // the 4th element
var newList = l.at(1, 3); // the 2nd and 4th elements
});
chainability is a key advantage of NodeLists:
require(["dojo/query", "dojo/NodeList-dom"
], function(query){
query(".thinger")
.onclick(function(e){ /* ... */ })
.at(1, 3, 8) // get a subset
.style("padding", "5px")
.forEach(console.log);
});