3 This file is part of Ext JS 4
5 Copyright (c) 2011 Sencha Inc
7 Contact: http://www.sencha.com/contact
9 GNU General Public License Usage
10 This file may be used under the terms of the GNU General Public License version 3.0 as published by the Free Software Foundation and appearing in the file LICENSE included in the packaging of this file. Please review the following information to ensure the GNU General Public License version 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
12 If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
16 * Provides searching of Components within Ext.ComponentManager (globally) or a specific
17 * Ext.container.Container on the document with a similar syntax to a CSS selector.
19 * Components can be retrieved by using their {@link Ext.Component xtype} with an optional . prefix
21 * - `component` or `.component`
22 * - `gridpanel` or `.gridpanel`
24 * An itemId or id must be prefixed with a #
28 * Attributes must be wrapped in brackets
30 * - `component[autoScroll]`
31 * - `panel[title="Test"]`
33 * Member expressions from candidate Components may be tested. If the expression returns a *truthy* value,
34 * the candidate Component will be included in the query:
36 * var disabledFields = myFormPanel.query("{isDisabled()}");
38 * Pseudo classes may be used to filter results in the same way as in {@link Ext.DomQuery DomQuery}:
40 * // Function receives array and returns a filtered array.
41 * Ext.ComponentQuery.pseudos.invalid = function(items) {
42 * var i = 0, l = items.length, c, result = [];
43 * for (; i < l; i++) {
44 * if (!(c = items[i]).isValid()) {
51 * var invalidFields = myFormPanel.query('field:invalid');
52 * if (invalidFields.length) {
53 * invalidFields[0].getEl().scrollIntoView(myFormPanel.body);
54 * for (var i = 0, l = invalidFields.length; i < l; i++) {
55 * invalidFields[i].getEl().frame("red");
59 * Default pseudos include:
64 * Queries return an array of components.
65 * Here are some example queries.
67 * // retrieve all Ext.Panels in the document by xtype
68 * var panelsArray = Ext.ComponentQuery.query('panel');
70 * // retrieve all Ext.Panels within the container with an id myCt
71 * var panelsWithinmyCt = Ext.ComponentQuery.query('#myCt panel');
73 * // retrieve all direct children which are Ext.Panels within myCt
74 * var directChildPanel = Ext.ComponentQuery.query('#myCt > panel');
76 * // retrieve all grids and trees
77 * var gridsAndTrees = Ext.ComponentQuery.query('gridpanel, treepanel');
79 * For easy access to queries based from a particular Container see the {@link Ext.container.Container#query},
80 * {@link Ext.container.Container#down} and {@link Ext.container.Container#child} methods. Also see
81 * {@link Ext.Component#up}.
83 Ext.define('Ext.ComponentQuery', {
85 uses: ['Ext.ComponentManager']
90 // A function source code pattern with a placeholder which accepts an expression which yields a truth value when applied
91 // as a member on each item in the passed array.
98 'for (; i < l; i++) {',
107 filterItems = function(items, operation) {
108 // Argument list for the operation is [ itemsArray, operationArg1, operationArg2...]
109 // The operation's method loops over each item in the candidate array and
110 // returns an array of items which match its criteria
111 return operation.method.apply(this, [ items ].concat(operation.args));
114 getItems = function(items, mode) {
117 length = items.length,
121 for (; i < length; i++) {
122 candidate = items[i];
123 if (candidate.getRefItems) {
124 result = result.concat(candidate.getRefItems(deep));
130 getAncestors = function(items) {
133 length = items.length,
135 for (; i < length; i++) {
136 candidate = items[i];
137 while (!!(candidate = (candidate.ownerCt || candidate.floatParent))) {
138 result.push(candidate);
144 // Filters the passed candidate array and returns only items which match the passed xtype
145 filterByXType = function(items, xtype, shallow) {
147 return items.slice();
152 length = items.length,
154 for (; i < length; i++) {
155 candidate = items[i];
156 if (candidate.isXType(xtype, shallow)) {
157 result.push(candidate);
164 // Filters the passed candidate array and returns only items which have the passed className
165 filterByClassName = function(items, className) {
169 length = items.length,
171 for (; i < length; i++) {
172 candidate = items[i];
173 if (candidate.el ? candidate.el.hasCls(className) : EA.contains(candidate.initCls(), className)) {
174 result.push(candidate);
180 // Filters the passed candidate array and returns only items which have the specified property match
181 filterByAttribute = function(items, property, operator, value) {
184 length = items.length,
186 for (; i < length; i++) {
187 candidate = items[i];
188 if (!value ? !!candidate[property] : (String(candidate[property]) === value)) {
189 result.push(candidate);
195 // Filters the passed candidate array and returns only items which have the specified itemId or id
196 filterById = function(items, id) {
199 length = items.length,
201 for (; i < length; i++) {
202 candidate = items[i];
203 if (candidate.getItemId() === id) {
204 result.push(candidate);
210 // Filters the passed candidate array and returns only items which the named pseudo class matcher filters in
211 filterByPseudo = function(items, name, value) {
212 return cq.pseudos[name](items, value);
215 // Determines leading mode
216 // > for direct child, and ^ to switch to ownerCt axis
217 modeRe = /^(\s?([>\^])\s?|\s|$)/,
219 // Matches a token with possibly (true|false) appended for the "shallow" parameter
220 tokenRe = /^(#)?([\w\-]+|\*)(?:\((true|false)\))?/,
223 // Checks for .xtype with possibly (true|false) appended for the "shallow" parameter
224 re: /^\.([\w\-]+)(?:\((true|false)\))?/,
225 method: filterByXType
227 // checks for [attribute=value]
228 re: /^(?:[\[](?:@)?([\w\-]+)\s?(?:(=|.=)\s?['"]?(.*?)["']?)?[\]])/,
229 method: filterByAttribute
231 // checks for #cmpItemId
235 // checks for :<pseudo_class>(<selector>)
236 re: /^\:([\w\-]+)(?:\(((?:\{[^\}]+\})|(?:(?!\{)[^\s>\/]*?(?!\})))\))?/,
237 method: filterByPseudo
239 // checks for {<member_expression>}
240 re: /^(?:\{([^\}]+)\})/,
241 method: filterFnPattern
244 // @class Ext.ComponentQuery.Query
245 // This internal class is completely hidden in documentation.
246 cq.Query = Ext.extend(Object, {
247 constructor: function(cfg) {
249 Ext.apply(this, cfg);
252 // Executes this Query upon the selected root.
253 // The root provides the initial source of candidate Component matches which are progressively
254 // filtered by iterating through this Query's operations cache.
255 // If no root is provided, all registered Components are searched via the ComponentManager.
256 // root may be a Container who's descendant Components are filtered
257 // root may be a Component with an implementation of getRefItems which provides some nested Components such as the
258 // docked items within a Panel.
259 // root may be an array of candidate Components to filter using this Query.
260 execute : function(root) {
261 var operations = this.operations,
263 length = operations.length,
267 // no root, use all Components in the document
269 workingItems = Ext.ComponentManager.all.getArray();
271 // Root is a candidate Array
272 else if (Ext.isArray(root)) {
276 // We are going to loop over our operations and take care of them
278 for (; i < length; i++) {
279 operation = operations[i];
281 // The mode operation requires some custom handling.
282 // All other operations essentially filter down our current
283 // working items, while mode replaces our current working
284 // items by getting children from each one of our current
285 // working items. The type of mode determines the type of
286 // children we get. (e.g. > only gets direct children)
287 if (operation.mode === '^') {
288 workingItems = getAncestors(workingItems || [root]);
290 else if (operation.mode) {
291 workingItems = getItems(workingItems || [root], operation.mode);
294 workingItems = filterItems(workingItems || getItems([root]), operation);
297 // If this is the last operation, it means our current working
298 // items are the final matched items. Thus return them!
299 if (i === length -1) {
306 is: function(component) {
307 var operations = this.operations,
308 components = Ext.isArray(component) ? component : [component],
309 originalLength = components.length,
310 lastOperation = operations[operations.length-1],
313 components = filterItems(components, lastOperation);
314 if (components.length === originalLength) {
315 if (operations.length > 1) {
316 for (i = 0, ln = components.length; i < ln; i++) {
317 if (Ext.Array.indexOf(this.execute(), components[i]) === -1) {
330 // private cache of selectors and matching ComponentQuery.Query objects
333 // private cache of pseudo class filter functions
335 not: function(components, selector){
336 var CQ = Ext.ComponentQuery,
338 length = components.length,
343 for(; i < length; ++i) {
344 component = components[i];
345 if (!CQ.is(component, selector)) {
346 results[++index] = component;
351 last: function(components) {
352 return components[components.length - 1];
357 * Returns an array of matched Components from within the passed root object.
359 * This method filters returned Components in a similar way to how CSS selector based DOM
360 * queries work using a textual selector string.
362 * See class summary for details.
364 * @param {String} selector The selector string to filter returned Components
365 * @param {Ext.container.Container} root The Container within which to perform the query.
366 * If omitted, all Components within the document are included in the search.
368 * This parameter may also be an array of Components to filter according to the selector.</p>
369 * @returns {Ext.Component[]} The matched Components.
371 * @member Ext.ComponentQuery
373 query: function(selector, root) {
374 var selectors = selector.split(','),
375 length = selectors.length,
380 query, resultsLn, cmp;
382 for (; i < length; i++) {
383 selector = Ext.String.trim(selectors[i]);
384 query = this.cache[selector];
386 this.cache[selector] = query = this.parse(selector);
388 results = results.concat(query.execute(root));
391 // multiple selectors, potential to find duplicates
392 // lets filter them out.
394 resultsLn = results.length;
395 for (i = 0; i < resultsLn; i++) {
397 if (!dupMatcher[cmp.id]) {
398 noDupResults.push(cmp);
399 dupMatcher[cmp.id] = true;
402 results = noDupResults;
408 * Tests whether the passed Component matches the selector string.
409 * @param {Ext.Component} component The Component to test
410 * @param {String} selector The selector string to test against.
411 * @return {Boolean} True if the Component matches the selector.
412 * @member Ext.ComponentQuery
414 is: function(component, selector) {
418 var query = this.cache[selector];
420 this.cache[selector] = query = this.parse(selector);
422 return query.is(component);
425 parse: function(selector) {
427 length = matchers.length,
435 // We are going to parse the beginning of the selector over and
436 // over again, slicing off the selector any portions we converted into an
437 // operation, until it is an empty string.
438 while (selector && lastSelector !== selector) {
439 lastSelector = selector;
441 // First we check if we are dealing with a token like #, * or an xtype
442 tokenMatch = selector.match(tokenRe);
445 matchedChar = tokenMatch[1];
447 // If the token is prefixed with a # we push a filterById operation to our stack
448 if (matchedChar === '#') {
451 args: [Ext.String.trim(tokenMatch[2])]
454 // If the token is prefixed with a . we push a filterByClassName operation to our stack
455 // FIXME: Not enabled yet. just needs \. adding to the tokenRe prefix
456 else if (matchedChar === '.') {
458 method: filterByClassName,
459 args: [Ext.String.trim(tokenMatch[2])]
462 // If the token is a * or an xtype string, we push a filterByXType
463 // operation to the stack.
466 method: filterByXType,
467 args: [Ext.String.trim(tokenMatch[2]), Boolean(tokenMatch[3])]
471 // Now we slice of the part we just converted into an operation
472 selector = selector.replace(tokenMatch[0], '');
475 // If the next part of the query is not a space or > or ^, it means we
476 // are going to check for more things that our current selection
478 while (!(modeMatch = selector.match(modeRe))) {
479 // Lets loop over each type of matcher and execute it
480 // on our current selector.
481 for (i = 0; selector && i < length; i++) {
482 matcher = matchers[i];
483 selectorMatch = selector.match(matcher.re);
484 method = matcher.method;
486 // If we have a match, add an operation with the method
487 // associated with this matcher, and pass the regular
488 // expression matches are arguments to the operation.
491 method: Ext.isString(matcher.method)
492 // Turn a string method into a function by formatting the string with our selector matche expression
493 // A new method is created for different match expressions, eg {id=='textfield-1024'}
494 // Every expression may be different in different selectors.
495 ? Ext.functionFactory('items', Ext.String.format.apply(Ext.String, [method].concat(selectorMatch.slice(1))))
497 args: selectorMatch.slice(1)
499 selector = selector.replace(selectorMatch[0], '');
500 break; // Break on match
503 // Exhausted all matches: It's an error
504 if (i === (length - 1)) {
505 Ext.Error.raise('Invalid ComponentQuery selector: "' + arguments[0] + '"');
511 // Now we are going to check for a mode change. This means a space
512 // or a > to determine if we are going to select all the children
513 // of the currently matched items, or a ^ if we are going to use the
514 // ownerCt axis as the candidate source.
515 if (modeMatch[1]) { // Assignment, and test for truthiness!
517 mode: modeMatch[2]||modeMatch[1]
519 selector = selector.replace(modeMatch[0], '');
523 // Now that we have all our operations in an array, we are going
524 // to create a new Query using these operations.
525 return new cq.Query({
526 operations: operations