Hierarchy
Ext.BaseExt.ComponentQuery
Requires
Ext.ComponentManager
Ext.dom.Query
Files
ComponentQuery.js

Provides searching of Components within Ext.ComponentManager (globally) or a specific\nExt.container.Container on the document with a similar syntax to a CSS selector.\nReturns Array of matching Components, or empty Array.

\n\n

Basic Component lookup

\n\n

Components can be retrieved by using their xtype:

\n\n

component
gridpanel

\n\n\n

Matching by xtype matches inherited types, so in the following code, the previous field\nof any type which inherits from TextField will be found:

\n\n

prevField = myField.previousNode('textfield');\n

\n\n

To match only the exact type, pass the \"shallow\" flag by adding (true) to xtype\n(See AbstractComponent's isXType method):

\n\n

prevTextField = myField.previousNode('textfield(true)');\n

\n\n

You can search Components by their id or itemId property, prefixed with a #:

\n\n

#myContainer\n

\n\n

Component xtype and id or itemId can be used together to avoid possible\nid collisions between Components of different types:

\n\n

panel#myPanel\n

\n\n

Traversing Component tree

\n\n

Components can be found by their relation to other Components. There are several\nrelationship operators, mostly taken from CSS selectors:

\n\n

E F All descendant Components of E that match F
E > F All direct children Components of E that match F
E ^ F All parent Components of E that match F

\n\n\n

Expressions between relationship operators are matched left to right, i.e. leftmost\nselector is applied first, then if one or more matches are found, relationship operator\nitself is applied, then next selector expression, etc. It is possible to combine\nrelationship operators in complex selectors:

\n\n

window[title=\"Input form\"] textfield[name=login] ^ form > button[action=submit]\n

\n\n

That selector can be read this way: Find a window with title \"Input form\", in that\nwindow find a TextField with name \"login\" at any depth (including subpanels and/or\nFieldSets), then find an Ext.form.Panel that is a parent of the TextField, and in\nthat form find a direct child that is a button with custom property action set to\nvalue \"submit\".

\n\n

Whitespace on both sides of ^ and > operators is non-significant, i.e. can be\nomitted, but usually is used for clarity.

\n\n

Searching by Component attributes

\n\n

Components can be searched by their object property values (attributes). To do that,\nuse attribute matching expression in square brackets:

\n\n

component[autoScroll] - matches any Component that has autoScroll property with\nany truthy (non-empty, not false) value.
panel[title=\"Test\"] - matches any Component that has title property set to\n\"Test\". Note that if the value does not contain spaces, the quotes are optional.

\n\n\n

Attributes can use any of the operators in DomQuery's\noperators to compare values.

\n\n

Prefixing the attribute name with an at sign @ means that the property must be\nthe object's ownProperty, not a property from the prototype chain.

\n\n

Specifications like [propName] check that the property is a truthy value. To check\nthat the object has an ownProperty of a certain name, regardless of the value use\nthe form [?propName].

\n\n

The specified value is coerced to match the type of the property found in the\ncandidate Component using Ext.coerce.

\n\n

If you need to find Components by their itemId property, use #id form; it will\ndo the same but is easier to read.

\n\n

Attribute matching operators

\n\n

The '=' operator will return the results that exactly match the\nspecified object property (attribute):

\n\n

Ext.ComponentQuery.query('panel[cls=my-cls]');\n

\n\n

Will match the following Component:

\n\n

Ext.create('Ext.window.Window', {\n    cls: 'my-cls'\n});\n

\n\n

But will not match the following Component, because 'my-cls' is one value\namong others:

\n\n

 Ext.create('Ext.panel.Panel', {\n     cls: 'foo-cls my-cls bar-cls'\n });\n

\n\n

You can use the '~=' operator instead, it will return Components with\nthe property that exactly matches one of the whitespace-separated\nvalues. This is also true for properties that only have one value:

\n\n

Ext.ComponentQuery.query('panel[cls~=my-cls]');\n

\n\n

Will match both Components:

\n\n

Ext.create('Ext.panel.Panel', {\n    cls: 'foo-cls my-cls bar-cls'\n});\n\nExt.create('Ext.window.Window', {\n    cls: 'my-cls'\n});\n

\n\n

Generally, '=' operator is more suited for object properties other than\nCSS classes, while '~=' operator will work best with properties that\nhold lists of whitespace-separated CSS classes.

\n\n

The '^=' operator will return Components with specified attribute that\nstart with the passed value:

\n\n

Ext.ComponentQuery.query('panel[title^=Sales]');\n

\n\n

Will match the following Component:

\n\n

Ext.create('Ext.panel.Panel', {\n    title: 'Sales estimate for Q4'\n});\n

\n\n

The '$=' operator will return Components with specified properties that\nend with the passed value:

\n\n

Ext.ComponentQuery.query('field[fieldLabel$=name]');\n

\n\n

Will match the following Component:

\n\n

Ext.create('Ext.form.field.Text', {\n    fieldLabel: 'Enter your name'\n});\n

\n\n

The following test will find panels with their ownProperty collapsed being equal to\nfalse. It will not match a collapsed property from the prototype chain.

\n\n

Ext.ComponentQuery.query('panel[@collapsed=false]');\n

\n\n

Member expressions from candidate Components may be tested. If the expression returns\na truthy value, the candidate Component will be included in the query:

\n\n

var disabledFields = myFormPanel.query(\"{isDisabled()}\");\n

\n\n

Such expressions are executed in Component's context, and the above expression is\nsimilar to running this snippet for every Component in your application:

\n\n

 if (component.isDisabled()) {\n     matches.push(component);\n }\n

\n\n

It is important to use only methods that are available in every Component instance\nto avoid run time exceptions. If you need to match your Components with a custom\ncondition formula, you can augment Ext.Component to provide custom matcher that\nwill return false by default, and override it in your custom classes:

\n\n

 Ext.define('My.Component', {\n     override: 'Ext.Component',\n     myMatcher: function() { return false; }\n });\n\n Ext.define('My.Panel', {\n     extend: 'Ext.panel.Panel',\n     requires: ['My.Component'],     // Ensure that Component override is applied\n     myMatcher: function(selector) {\n         return selector === 'myPanel';\n     }\n });\n

\n\n

After that you can use a selector with your custom matcher to find all instances\nof My.Panel:

\n\n

 Ext.ComponentQuery.query(\"{myMatcher('myPanel')}\");\n

\n\n

However if you really need to use a custom matcher, you may find it easier to implement\na custom Pseudo class instead (see below).

\n\n

Conditional matching

\n\n

Attribute matchers can be combined to select only Components that match all\nconditions (logical AND operator):

\n\n

Ext.ComponentQuery.query('panel[cls~=my-cls][floating=true][title$=\"sales data\"]');\n

\n\n

E.g., the query above will match only a Panel-descended Component that has 'my-cls'\nCSS class and is floating and with a title that ends with \"sales data\".

\n\n

Expressions separated with commas will match any Component that satisfies\neither expression (logical OR operator):

\n\n

Ext.ComponentQuery.query('field[fieldLabel^=User], field[fieldLabel*=password]');\n

\n\n

E.g., the query above will match any field with field label starting with \"User\",\nor any field that has \"password\" in its label.

\n\n

Pseudo classes

\n\n

Pseudo classes may be used to filter results in the same way as in\nExt.dom.Query. There are five default pseudo classes:

\n\n

not Negates a selector.
first Filters out all except the first matching item for a selector.
last Filters out all except the last matching item for a selector.
focusable Filters out all except Components which are currently able to recieve\nfocus.
nth-child Filters Components by ordinal position in the selection.

\n\n\n

These pseudo classes can be used with other matchers or without them:

\n\n

 // Select first direct child button in any panel\n Ext.ComponentQuery.query('panel > button:first');\n\n // Select last field in Profile form\n Ext.ComponentQuery.query('form[title=Profile] field:last');\n\n // Find first focusable Component in a panel and focus it\n panel.down(':focusable').focus();\n\n // Select any field that is not hidden in a form\n form.query('field:not(hiddenfield)');\n

\n\n

Pseudo class nth-child can be used to find any child Component by its\nposition relative to its siblings. This class' handler takes one argument\nthat specifies the selection formula as Xn or Xn+Y:

\n\n

 // Find every odd field in a form\n form.query('field:nth-child(2n+1)'); // or use shortcut: :nth-child(odd)\n\n // Find every even field in a form\n form.query('field:nth-child(2n)');   // or use shortcut: :nth-child(even)\n\n // Find every 3rd field in a form\n form.query('field:nth-child(3n)');\n

\n\n

Pseudo classes can be combined to further filter the results, e.g., in the\nform example above we can modify the query to exclude hidden fields:

\n\n

 // Find every 3rd non-hidden field in a form\n form.query('field:not(hiddenfield):nth-child(3n)');\n

\n\n

Note that when combining pseudo classes, whitespace is significant, i.e.\nthere should be no spaces between pseudo classes. This is a common mistake;\nif you accidentally type a space between field and :not, the query\nwill not return any result because it will mean \"find field's children\nComponents that are not hidden fields...\".

\n\n

Custom pseudo classes

\n\n

It is possible to define your own custom pseudo classes. In fact, a\npseudo class is just a property in Ext.ComponentQuery.pseudos object\nthat defines pseudo class name (property name) and pseudo class handler\n(property value):

\n\n

// Function receives array and returns a filtered array.\nExt.ComponentQuery.pseudos.invalid = function(items) {\n    var i = 0, l = items.length, c, result = [];\n    for (; i < l; i++) {\n        if (!(c = items[i]).isValid()) {\n            result.push(c);\n        }\n    }\n    return result;\n};\n\nvar invalidFields = myFormPanel.query('field:invalid');\nif (invalidFields.length) {\n    invalidFields[0].getEl().scrollIntoView(myFormPanel.body);\n    for (var i = 0, l = invalidFields.length; i < l; i++) {\n        invalidFields[i].getEl().frame(\"red\");\n    }\n}\n

\n\n

Pseudo class handlers can be even more flexible, with a selector\nargument used to define the logic:

\n\n

 // Handler receives array of itmes and selector in parentheses\n Ext.ComponentQuery.pseudos.titleRegex = function(components, selector) {\n     var i = 0, l = components.length, c, result = [], regex = new RegExp(selector);\n     for (; i < l; i++) {\n         c = components[i];\n         if (c.title && regex.test(c.title)) {\n             result.push(c);\n         }\n     }\n     return result;\n }\n\n var salesTabs = tabPanel.query('panel:titleRegex(\"sales\\\\s+for\\\\s+201[123]\")');\n

\n\n

Be careful when using custom pseudo classes with MVC Controllers: when\nyou use a pseudo class in Controller's control or listen component\nselectors, the pseudo class' handler function will be called very often\nand may slow down your application significantly. A good rule of thumb\nis to always specify Component xtype with the pseudo class so that the\nhandlers are only called on Components that you need, and try to make\nthe condition checks as cheap in terms of execution time as possible.\nNote how in the example above, handler function checks that Component\nhas a title first, before running regex test on it.

\n\n

Query examples

\n\n

Queries return an array of Components. Here are some example queries:

\n\n

// retrieve all Ext.Panels in the document by xtype\nvar panelsArray = Ext.ComponentQuery.query('panel');\n\n// retrieve all Ext.Panels within the container with an id myCt\nvar panelsWithinmyCt = Ext.ComponentQuery.query('#myCt panel');\n\n// retrieve all direct children which are Ext.Panels within myCt\nvar directChildPanel = Ext.ComponentQuery.query('#myCt > panel');\n\n// retrieve all grids or trees\nvar gridsAndTrees = Ext.ComponentQuery.query('gridpanel, treepanel');\n\n// Focus first Component\nmyFormPanel.child(':focusable').focus();\n\n// Retrieve every odd text field in a form\nmyFormPanel.query('textfield:nth-child(odd)');\n\n// Retrieve every even field in a form, excluding hidden fields\nmyFormPanel.query('field:not(hiddenfield):nth-child(even)');\n

\n\n

For easy access to queries based from a particular Container see the\nExt.container.Container.query, Ext.container.Container.down and\nExt.container.Container.child methods. Also see\nExt.Component.up.

Properties

Defined By

Hierarchy

Requires

Files

Basic Component lookup

Traversing Component tree

Searching by Component attributes

Attribute matching operators

Conditional matching

Pseudo classes

Custom pseudo classes

Query examples

Properties

Instance Properties

Static Properties

Methods

Instance Methods

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Returns

Static Methods

Parameters

Parameters

Parameters

Parameters

Parameters

Returns

Parameters

Parameters

Returns

Returns

Parameters

Parameters

Returns

Parameters

Parameters

Parameters

Returns