src/ComponentQuery.js

   1 /*
   2
   3 This file is part of Ext JS 4
   4
   5 Copyright (c) 2011 Sencha Inc
   6
   7 Contact:  http://www.sencha.com/contact
   8
   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.
  11
  12 If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
  13
  14 */
  15 /**
  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.
  18  *
  19  * Components can be retrieved by using their {@link Ext.Component xtype} with an optional . prefix
  20  *
  21  * - `component` or `.component`
  22  * - `gridpanel` or `.gridpanel`
  23  *
  24  * An itemId or id must be prefixed with a #
  25  *
  26  * - `#myContainer`
  27  *
  28  * Attributes must be wrapped in brackets
  29  *
  30  * - `component[autoScroll]`
  31  * - `panel[title="Test"]`
  32  *
  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:
  35  *
  36  *     var disabledFields = myFormPanel.query("{isDisabled()}");
  37  *
  38  * Pseudo classes may be used to filter results in the same way as in {@link Ext.DomQuery DomQuery}:
  39  *
  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()) {
  45  *                 result.push(c);
  46  *             }
  47  *         }
  48  *         return result;
  49  *     };
  50  *
  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");
  56  *         }
  57  *     }
  58  *
  59  * Default pseudos include:
  60  *
  61  * - not
  62  * - last
  63  *
  64  * Queries return an array of components.
  65  * Here are some example queries.
  66  *
  67  *     // retrieve all Ext.Panels in the document by xtype
  68  *     var panelsArray = Ext.ComponentQuery.query('panel');
  69  *
  70  *     // retrieve all Ext.Panels within the container with an id myCt
  71  *     var panelsWithinmyCt = Ext.ComponentQuery.query('#myCt panel');
  72  *
  73  *     // retrieve all direct children which are Ext.Panels within myCt
  74  *     var directChildPanel = Ext.ComponentQuery.query('#myCt > panel');
  75  *
  76  *     // retrieve all grids and trees
  77  *     var gridsAndTrees = Ext.ComponentQuery.query('gridpanel, treepanel');
  78  *
  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}.
  82  */
  83 Ext.define('Ext.ComponentQuery', {
  84     singleton: true,
  85     uses: ['Ext.ComponentManager']
  86 }, function() {
  87
  88     var cq = this,
  89
  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.
  92         filterFnPattern = [
  93             'var r = [],',
  94                 'i = 0,',
  95                 'it = items,',
  96                 'l = it.length,',
  97                 'c;',
  98             'for (; i < l; i++) {',
  99                 'c = it[i];',
 100                 'if (c.{0}) {',
 101                    'r.push(c);',
 102                 '}',
 103             '}',
 104             'return r;'
 105         ].join(''),
 106
 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));
 112         },
 113
 114         getItems = function(items, mode) {
 115             var result = [],
 116                 i = 0,
 117                 length = items.length,
 118                 candidate,
 119                 deep = mode !== '>';
 120
 121             for (; i < length; i++) {
 122                 candidate = items[i];
 123                 if (candidate.getRefItems) {
 124                     result = result.concat(candidate.getRefItems(deep));
 125                 }
 126             }
 127             return result;
 128         },
 129
 130         getAncestors = function(items) {
 131             var result = [],
 132                 i = 0,
 133                 length = items.length,
 134                 candidate;
 135             for (; i < length; i++) {
 136                 candidate = items[i];
 137                 while (!!(candidate = (candidate.ownerCt || candidate.floatParent))) {
 138                     result.push(candidate);
 139                 }
 140             }
 141             return result;
 142         },
 143
 144         // Filters the passed candidate array and returns only items which match the passed xtype
 145         filterByXType = function(items, xtype, shallow) {
 146             if (xtype === '*') {
 147                 return items.slice();
 148             }
 149             else {
 150                 var result = [],
 151                     i = 0,
 152                     length = items.length,
 153                     candidate;
 154                 for (; i < length; i++) {
 155                     candidate = items[i];
 156                     if (candidate.isXType(xtype, shallow)) {
 157                         result.push(candidate);
 158                     }
 159                 }
 160                 return result;
 161             }
 162         },
 163
 164         // Filters the passed candidate array and returns only items which have the passed className
 165         filterByClassName = function(items, className) {
 166             var EA = Ext.Array,
 167                 result = [],
 168                 i = 0,
 169                 length = items.length,
 170                 candidate;
 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);
 175                 }
 176             }
 177             return result;
 178         },
 179
 180         // Filters the passed candidate array and returns only items which have the specified property match
 181         filterByAttribute = function(items, property, operator, value) {
 182             var result = [],
 183                 i = 0,
 184                 length = items.length,
 185                 candidate;
 186             for (; i < length; i++) {
 187                 candidate = items[i];
 188                 if (!value ? !!candidate[property] : (String(candidate[property]) === value)) {
 189                     result.push(candidate);
 190                 }
 191             }
 192             return result;
 193         },
 194
 195         // Filters the passed candidate array and returns only items which have the specified itemId or id
 196         filterById = function(items, id) {
 197             var result = [],
 198                 i = 0,
 199                 length = items.length,
 200                 candidate;
 201             for (; i < length; i++) {
 202                 candidate = items[i];
 203                 if (candidate.getItemId() === id) {
 204                     result.push(candidate);
 205                 }
 206             }
 207             return result;
 208         },
 209
 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);
 213         },
 214
 215         // Determines leading mode
 216         // > for direct child, and ^ to switch to ownerCt axis
 217         modeRe = /^(\s?([>\^])\s?|\s|$)/,
 218
 219         // Matches a token with possibly (true|false) appended for the "shallow" parameter
 220         tokenRe = /^(#)?([\w\-]+|\*)(?:\((true|false)\))?/,
 221
 222         matchers = [{
 223             // Checks for .xtype with possibly (true|false) appended for the "shallow" parameter
 224             re: /^\.([\w\-]+)(?:\((true|false)\))?/,
 225             method: filterByXType
 226         },{
 227             // checks for [attribute=value]
 228             re: /^(?:[\[](?:@)?([\w\-]+)\s?(?:(=|.=)\s?['"]?(.*?)["']?)?[\]])/,
 229             method: filterByAttribute
 230         }, {
 231             // checks for #cmpItemId
 232             re: /^#([\w\-]+)/,
 233             method: filterById
 234         }, {
 235             // checks for :<pseudo_class>(<selector>)
 236             re: /^\:([\w\-]+)(?:\(((?:\{[^\}]+\})|(?:(?!\{)[^\s>\/]*?(?!\})))\))?/,
 237             method: filterByPseudo
 238         }, {
 239             // checks for {<member_expression>}
 240             re: /^(?:\{([^\}]+)\})/,
 241             method: filterFnPattern
 242         }];
 243
 244     // @class Ext.ComponentQuery.Query
 245     // This internal class is completely hidden in documentation.
 246     cq.Query = Ext.extend(Object, {
 247         constructor: function(cfg) {
 248             cfg = cfg || {};
 249             Ext.apply(this, cfg);
 250         },
 251
 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,
 262                 i = 0,
 263                 length = operations.length,
 264                 operation,
 265                 workingItems;
 266
 267             // no root, use all Components in the document
 268             if (!root) {
 269                 workingItems = Ext.ComponentManager.all.getArray();
 270             }
 271             // Root is a candidate Array
 272             else if (Ext.isArray(root)) {
 273                 workingItems = root;
 274             }
 275
 276             // We are going to loop over our operations and take care of them
 277             // one by one.
 278             for (; i < length; i++) {
 279                 operation = operations[i];
 280
 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]);
 289                 }
 290                 else if (operation.mode) {
 291                     workingItems = getItems(workingItems || [root], operation.mode);
 292                 }
 293                 else {
 294                     workingItems = filterItems(workingItems || getItems([root]), operation);
 295                 }
 296
 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) {
 300                     return workingItems;
 301                 }
 302             }
 303             return [];
 304         },
 305
 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],
 311                 ln, i;
 312
 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) {
 318                             return false;
 319                         }
 320                     }
 321                 }
 322                 return true;
 323             }
 324             return false;
 325         }
 326     });
 327
 328     Ext.apply(this, {
 329
 330         // private cache of selectors and matching ComponentQuery.Query objects
 331         cache: {},
 332
 333         // private cache of pseudo class filter functions
 334         pseudos: {
 335             not: function(components, selector){
 336                 var CQ = Ext.ComponentQuery,
 337                     i = 0,
 338                     length = components.length,
 339                     results = [],
 340                     index = -1,
 341                     component;
 342
 343                 for(; i < length; ++i) {
 344                     component = components[i];
 345                     if (!CQ.is(component, selector)) {
 346                         results[++index] = component;
 347                     }
 348                 }
 349                 return results;
 350             },
 351             last: function(components) {
 352                 return components[components.length - 1];
 353             }
 354         },
 355
 356         /**
 357          * Returns an array of matched Components from within the passed root object.
 358          *
 359          * This method filters returned Components in a similar way to how CSS selector based DOM
 360          * queries work using a textual selector string.
 361          *
 362          * See class summary for details.
 363          *
 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.
 367          *
 368          * This parameter may also be an array of Components to filter according to the selector.</p>
 369          * @returns {Ext.Component[]} The matched Components.
 370          *
 371          * @member Ext.ComponentQuery
 372          */
 373         query: function(selector, root) {
 374             var selectors = selector.split(','),
 375                 length = selectors.length,
 376                 i = 0,
 377                 results = [],
 378                 noDupResults = [],
 379                 dupMatcher = {},
 380                 query, resultsLn, cmp;
 381
 382             for (; i < length; i++) {
 383                 selector = Ext.String.trim(selectors[i]);
 384                 query = this.cache[selector];
 385                 if (!query) {
 386                     this.cache[selector] = query = this.parse(selector);
 387                 }
 388                 results = results.concat(query.execute(root));
 389             }
 390
 391             // multiple selectors, potential to find duplicates
 392             // lets filter them out.
 393             if (length > 1) {
 394                 resultsLn = results.length;
 395                 for (i = 0; i < resultsLn; i++) {
 396                     cmp = results[i];
 397                     if (!dupMatcher[cmp.id]) {
 398                         noDupResults.push(cmp);
 399                         dupMatcher[cmp.id] = true;
 400                     }
 401                 }
 402                 results = noDupResults;
 403             }
 404             return results;
 405         },
 406
 407         /**
 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
 413          */
 414         is: function(component, selector) {
 415             if (!selector) {
 416                 return true;
 417             }
 418             var query = this.cache[selector];
 419             if (!query) {
 420                 this.cache[selector] = query = this.parse(selector);
 421             }
 422             return query.is(component);
 423         },
 424
 425         parse: function(selector) {
 426             var operations = [],
 427                 length = matchers.length,
 428                 lastSelector,
 429                 tokenMatch,
 430                 matchedChar,
 431                 modeMatch,
 432                 selectorMatch,
 433                 i, matcher, method;
 434
 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;
 440
 441                 // First we check if we are dealing with a token like #, * or an xtype
 442                 tokenMatch = selector.match(tokenRe);
 443
 444                 if (tokenMatch) {
 445                     matchedChar = tokenMatch[1];
 446
 447                     // If the token is prefixed with a # we push a filterById operation to our stack
 448                     if (matchedChar === '#') {
 449                         operations.push({
 450                             method: filterById,
 451                             args: [Ext.String.trim(tokenMatch[2])]
 452                         });
 453                     }
 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 === '.') {
 457                         operations.push({
 458                             method: filterByClassName,
 459                             args: [Ext.String.trim(tokenMatch[2])]
 460                         });
 461                     }
 462                     // If the token is a * or an xtype string, we push a filterByXType
 463                     // operation to the stack.
 464                     else {
 465                         operations.push({
 466                             method: filterByXType,
 467                             args: [Ext.String.trim(tokenMatch[2]), Boolean(tokenMatch[3])]
 468                         });
 469                     }
 470
 471                     // Now we slice of the part we just converted into an operation
 472                     selector = selector.replace(tokenMatch[0], '');
 473                 }
 474
 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
 477                 // has to comply to.
 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;
 485
 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.
 489                         if (selectorMatch) {
 490                             operations.push({
 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))))
 496                                     : matcher.method,
 497                                 args: selectorMatch.slice(1)
 498                             });
 499                             selector = selector.replace(selectorMatch[0], '');
 500                             break; // Break on match
 501                         }
 502                         //<debug>
 503                         // Exhausted all matches: It's an error
 504                         if (i === (length - 1)) {
 505                             Ext.Error.raise('Invalid ComponentQuery selector: "' + arguments[0] + '"');
 506                         }
 507                         //</debug>
 508                     }
 509                 }
 510
 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!
 516                     operations.push({
 517                         mode: modeMatch[2]||modeMatch[1]
 518                     });
 519                     selector = selector.replace(modeMatch[0], '');
 520                 }
 521             }
 522
 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
 527             });
 528         }
 529     });
 530 });