dojo.query
dojo.query() is the swiss army knife of DOM node manipulation in Dojo. Much like Prototype's "$$" (bling-bling) function or JQuery's "$" function, dojo.query provides robust, high-performance CSS-based node selector support with the option of scoping searches to a particular sub-tree of a document.
Supported Selectors:
dojo.query() supports a rich set of CSS3 selectors, including:
-
class selectors (e.g.,
.foo
) -
node type selectors like
span
-
descendant selectors
-
>
child element selectors -
#foo
style ID selectors -
*
universal selector -
~
, the immediately preceeded-by sibling selector -
+
, the preceeded-by sibling selector -
attribute queries:
-
[foo]
attribute presence selector -
[foo='bar']
attribute value exact match -
[foo~='bar']
attribute value list item match -
[foo^='bar']
attribute start match -
[foo$='bar']
attribute end match -
[foo*='bar']
attribute substring match
-
-
:first-child
,:last-child
positional selectors -
:empty
content emtpy selector -
:empty
content emtpy selector -
:nth-child(n)
,:nth-child(2n+1)
style positional calculations -
:nth-child(even)
,:nth-child(odd)
positional selectors -
:not(...)
negation pseudo selectors
Any legal combination of these selectors will work with
dojo.query()
, including compound selectors ("," delimited).
Very complex and useful searches can be constructed with this
palette of selectors and when combined with functions for
maniplation presented by dojo.NodeList, many types of DOM
manipulation operations become very straightforward.
Unsupported Selectors:
While dojo.query handles many CSS3 selectors, some fall outside of what's resaonable for a programmatic node querying engine to handle. Currently unsupported selectors include:
- namespace-differentiated selectors of any form
-
all
::
pseduo-element selectors -
certain pseduo-selectors which don't get a lot of day-to-day use:
-
:root
,:lang()
,:target
,:focus
-
-
all visual and state selectors:
-
:root
,:active
,:hover
,:visisted
,:link
,:enabled
,:disabled
,:checked
-
-
:*-of-type
pseudo selectors
dojo.query and XML Documents:
dojo.query
currently only supports searching XML documents
whose tags and attributes are 100% lower-case. This is a known
limitation and will be addressed soon
Non-selector Queries:
If something other than a String is passed for the query,
dojo.query
will return a new dojo.NodeList
constructed from
that parameter alone and all further processing will stop. This
means that if you have a reference to a node or NodeList, you
can quickly construct a new NodeList from the original by
calling dojo.query(node)
or dojo.query(list)
.
parameter | type | description |
---|---|---|
query | String | The CSS3 expression to match against. For details on the syntax of CSS3 selectors, see <http://www.w3.org/TR/css3-selectors/#selectors> |
root | String|DOMNode | Optional. A DOMNode (or node id) to scope the search from. Optional. |
Examples
Example 1
search the entire document for elements with the class "foo":
dojo.query(".foo");
these elements will match:
Example 2
search the entire document for elements with the classes "foo" and "bar":
dojo.query(".foo.bar");
these elements will match:
while these will not:
Example 3
find `
...
` elements which are descendants of paragraphs and which have a "highlighted" class:
dojo.query("p span.highlighted");
the innermost span in this fragment matches:
Example 4
set an "odd" class on all odd table rows inside of the table
#tabular_data
, using the >
(direct child) selector to avoid
affecting any nested tables:
dojo.query("#tabular_data > tbody > tr:nth-child(odd)").addClass("odd");
Example 5
remove all elements with the class "error" from the document and store them in a list:
var errors = dojo.query(".error").orphan();
Example 6
add an onclick handler to every submit button in the document which causes the form to be sent via Ajax instead:
dojo.query("input[type='submit']").onclick(function(e){
dojo.stopEvent(e); // prevent sending the form
var btn = e.target;
dojo.xhrPost({
form: btn.form,
load: function(data){
// replace the form with the response
var div = dojo.doc.createElement("div");
dojo.place(div, btn.form, "after");
div.innerHTML = data;
dojo.style(btn.form, "display", "none");
}
});
});