dojo/query

Summary

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>

Usage

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 context will be scanned.

Returns: instance

See the dojo/query reference documentation for more information.

Examples

Example 1

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");
        });
    });
});

Methods

load(id,parentRequire,loaded)

Defined by dojo/query

can be used as AMD plugin to conditionally load new query engine

Parameter	Type	Description
id	undefined
parentRequire	undefined
loaded	undefined

Examples

Example 1

require(["dojo/query!custom"], function(qsa){
    // loaded selector/custom.js as engine
    qsa("#foobar").forEach(...);
});

NodeList(array)

Defined by dojo/query

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

Returns: Array

Examples

Example 1

create a node list from a node

require(["dojo/query", "dojo/dom"
], function(query, dom){
    query.NodeList(dom.byId("foo"));
});

Example 2

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);
    });
});

Example 3

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
});

Example 4

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);
});