query.js
This code was ported from the Dojo Toolkit
http://dojotoolkit.org and modified slightly for Closure.
goog.dom.query is a relatively full-featured CSS3 query function. It is
designed to take any valid CSS3 selector and return the nodes matching
the selector. To do this quickly, it processes queries in several
steps, applying caching where profitable.
The steps (roughly in reverse order of the way they appear in the code):
1.) check to see if we already have a "query dispatcher"
- if so, use that with the given parameterization. Skip to step 4.
2.) attempt to determine which branch to dispatch the query to:
- JS (optimized DOM iteration)
- native (FF3.1, Safari 3.2+, Chrome, some IE 8 doctypes). If native,
skip to step 4, using a stub dispatcher for QSA queries.
3.) tokenize and convert to executable "query dispatcher"
assembled as a chain of "yes/no" test functions pertaining to
a section of a simple query statement (".blah:nth-child(odd)"
but not "div div", which is 2 simple statements).
4.) the resulting query dispatcher is called in the passed scope
(by default the top-level document)
- for DOM queries, this results in a recursive, top-down
evaluation of nodes based on each simple query section
- querySelectorAll is used instead of DOM where possible. If a query
fails in this mode, it is re-run against the DOM evaluator and all
future queries using the same selector evaluate against the DOM branch
too.
5.) matched nodes are pruned to ensure they are unique
Useful links
File Location
_party/closure/goog/dojo/dom/query.js
Public
Protected
Private
Global Functions
goog.dom.query(query, opt_root)
⇒ {length: number}
Returns nodes which match the given CSS3 selector, searching the
entire document by default but optionally taking a node to scope
the search by.
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 preceded-by sibling selector
`+`, the preceded-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 empty selector
`:empty` content empty 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.
Unsupported Selectors:
----------------------
While dojo.query handles many CSS3 selectors, some fall outside of
what's reasonable for a programmatic node querying engine to
handle. Currently unsupported selectors include:
namespace-differentiated selectors of any form
all `::` pseudo-element selectors
certain pseudo-selectors which don't get a lot of day-to-day use:
| * `:root`, `:lang()`, `:target`, `:focus`
all visual and state selectors:
| * `:root`, `:active`, `:hover`, `:visited`, `: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]
(http://trac.dojotoolkit.org/ticket/3866)
Non-selector Queries:
---------------------
If something other than a String is passed for the query,
`dojo.query` will return a new array constructed from
that parameter alone and all further processing will stop. This
means that if you have a reference to a node or array or nodes, you
can quickly construct a new array of nodes from the original by
calling `dojo.query(node)` or `dojo.query(array)`.
example:
search the entire document for elements with the class "foo":
| dojo.query(".foo");
these elements will match:
|
|
|
example:
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:
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: find 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)");
Arguments:
Returns:
{length: number}
The elements that matched the query.
|
code » |