JSAPI.info

dojo.query

Dojo (1.6.1) - see full source
10057
10058
10059
10060
10061
10062
10063
10064
10065
10066
10067
10068
10069
10070
10071
10072
10073
10074
10075
10076
10077
10078
10079
10080
10081
10082
10083
10084
10085
10086
10087
10088
10089
10090
10091
10092
10093
10094
10095
10096
10097
10098
10099
10100
10101
10102
10103
10104
10105
10106
10107
10108
10109
10110
10111
10112
10113
10114
10115
10116
10117
10118
10119
10120
10121
10122
10123
10124
10125
10126
10127
10128
10129
10130
10131
10132
10133
10134
10135
10136
10137
10138
10139
10140
10141
10142
10143
10144
10145
10146
10147
10148
10149
10150
10151
10152
10153
10154
10155
10156
10157
10158
10159
10160
10161
10162
10163
10164
10165
10166
10167
10168
10169
10170
10171
10172
10173
10174
10175
10176
10177
10178
10179
10180
10181
10182
10183
10184
10185
10186
10187
10188
10189
10190
10191
10192
10193
10194
10195
10196
10197
10198
10199
10200
10201
10202
10203
10204
10205
10206
10207
10208
10209
10210
10211
10212
10213
10214
10215
10216
10217
10218
10219
10220
10221
10222
10223
10224
10225
10226
10227
10228
10229
10230
10231
10232
10233
10234
10235
10236
10237
10238
10239
10240
10241
10242
10243
10244
10245
10246
10247
10248
d.query = function(/*String*/ query, /*String|DOMNode?*/ root){
    //    summary:
    //        Returns nodes which match the given CSS3 selector, searching the
    //        entire document by default but optionally taking a node to scope
    //        the search by. Returns an instance of dojo.NodeList.
    //    description:
    //        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 preceded-by sibling selector
    //            * `+`, the immediately 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`, and `:only-child` positional selectors
    //            * `:empty` content emtpy selector
    //            * `:checked` pseudo 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
    //        manipulation 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 reasonable 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`
    //            * `:*-of-type` pseudo selectors
    //
    //        dojo.query and XML Documents:
    //        -----------------------------
    //
    //        `dojo.query` (as of dojo 1.2) supports searching XML documents
    //        in a case-sensitive manner. If an HTML document is served with
    //        a doctype that forces case-sensitivity (e.g., XHTML 1.1
    //        Strict), dojo.query() will detect this and "do the right
    //        thing". Case sensitivity is dependent upon the document being
    //        searched and not the query used. It is therefore possible to
    //        use case-sensitive queries on strict sub-documents (iframes,
    //        etc.) or XML documents while still assuming case-insensitivity
    //        for a host/root document.
    //
    //        Non-selector Queries:
    //        ---------------------
    //
    //        If something other than a String is passed for the query,
    //        `dojo.query` will return a new `dojo.NodeList` instance
    //        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)`.
    //
    //    query:
    //        The CSS3 expression to match against. For details on the syntax of
    //        CSS3 selectors, see <http://www.w3.org/TR/css3-selectors/#selectors>
    //    root:
    //        A DOMNode (or node id) to scope the search from. Optional.
    //    returns: dojo.NodeList
    //        An instance of `dojo.NodeList`. Many methods are available on
    //        NodeLists for searching, iterating, manipulating, and handling
    //        events on the matched nodes in the returned list.
    //    example:
    //        search the entire document for elements with the class "foo":
    //    |    dojo.query(".foo");
    //        these elements will match:
    //    |    <span class="foo"></span>
    //    |    <span class="foo bar"></span>
    //    |    <p class="thud foo"></p>
    //    example:
    //        search the entire document for elements with the classes "foo" *and* "bar":
    //    |    dojo.query(".foo.bar");
    //        these elements will match:
    //    |    <span class="foo bar"></span>
    //        while these will not:
    //    |    <span class="foo"></span>
    //    |    <p class="thud foo"></p>
    //    example:
    //        find `<span>` elements which are descendants of paragraphs and
    //        which have a "highlighted" class:
    //    |    dojo.query("p span.highlighted");
    //        the innermost span in this fragment matches:
    //    |    <p class="foo">
    //    |        <span>...
    //    |            <span class="highlighted foo bar">...</span>
    //    |        </span>
    //    |    </p>
    //    example:
    //        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:
    //        remove all elements with the class "error" from the document
    //        and store them in a list:
    //    |    var errors = dojo.query(".error").orphan();
    //    example:
    //        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");
    //    |            }
    //    |        });
    //    |    });
 
    //Set list constructor to desired value. This can change
    //between calls, so always re-assign here.
    qlc = d._NodeListCtor;
 
    if(!query){
        return new qlc();
    }
 
    if(query.constructor == qlc){
        return query;
    }
    if(typeof query != "string"){ // inline'd type check
        return new qlc(query); // dojo.NodeList
    }
    if(typeof root == "string"){ // inline'd type check
        root = d.byId(root);
        if(!root){ return new qlc(); }
    }
 
    root = root||getDoc();
    var od = root.ownerDocument||root.documentElement;
 
    // throw the big case sensitivity switch
 
    // NOTE:
    //         Opera in XHTML mode doesn't detect case-sensitivity correctly
    //         and it's not clear that there's any way to test for it
    caseSensitive = (root.contentType && root.contentType=="application/xml") ||
                    (d.isOpera && (root.doctype || od.toString() == "[object XMLDocument]")) ||
                    (!!od) &&
                    (d.isIE ? od.xml : (root.xmlVersion||od.xmlVersion));
 
    // NOTE:
    //        adding "true" as the 2nd argument to getQueryFunc is useful for
    //        testing the DOM branch without worrying about the
    //        behavior/performance of the QSA branch.
    var r = getQueryFunc(query)(root);
 
    // FIXME:
    //        need to investigate this branch WRT #8074 and #8075
    if(r && r.nozip && !qlc._wrap){
        return r;
    }
    return _zip(r); // dojo.NodeList
}