To match only the exact type, pass the "shallow" flag by adding
(true) to xtype (See AbstractComponent's isXType method):
You can search Components by their
itemId property, prefixed with a #:
itemId can be used together to avoid possible id collisions between Components of different types:
xtype contains dots, you can escape them in your selector:
Traversing Component tree
Components can be found by their relation to other Components. There are several relationship operators, mostly taken from CSS selectors:
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
Expressions between relationship operators are matched left to right, i.e. leftmost selector is applied first, then if one or more matches are found, relationship operator itself is applied, then next selector expression, etc. It is possible to combine relationship operators in complex selectors:
That selector can be read this way: Find a window with title "Input form", in that window find a TextField with name "login" at any depth (including subpanels and/or FieldSets), then find an
Ext.form.Panel that is a parent of the TextField, and in that form find a direct child that is a button with custom property
action set to value "submit".
Whitespace on both sides of
> operators is non-significant, i.e. can be omitted, but usually is used for clarity.
Searching by Component attributes
Components can be searched by their object property values (attributes). To do that, use attribute matching expression in square brackets:
component[autoScroll] - matches any Component that has
autoScroll property with any truthy (non-empty, not
panel[title="Test"] - matches any Component that has
title property set to "Test". Note that if the value does not contain spaces, the quotes are optional.
Attributes can use any of the operators in DomQuery's operators to compare values.
Prefixing the attribute name with an at sign
@ means that the property must be the object's
ownProperty, not a property from the prototype chain.
[propName] check that the property is a truthy value. To check that the object has an
ownProperty of a certain name, regardless of the value use the form
The specified value is coerced to match the type of the property found in the candidate Component using Ext.coerce.
If you need to find Components by their
itemId property, use the
#id form; it will do the same as
[itemId=id] but is easier to read.
If you need to include a metacharacter like (, ), [, ], etc., in the query, escape it by prefixing it with a backslash:
Attribute matching operators
The '=' operator will return the results that exactly match the specified object property (attribute):
Will match the following Component:
But will not match the following Component, because 'my-cls' is one value among others:
You can use the '~=' operator instead, it will return Components with the property that exactly matches one of the whitespace-separated values. This is also true for properties that only have one value:
Will match both Components:
Generally, '=' operator is more suited for object properties other than CSS classes, while '~=' operator will work best with properties that hold lists of whitespace-separated CSS classes.
The '^=' operator will return Components with specified attribute that start with the passed value:
Will match the following Component:
The '$=' operator will return Components with specified properties that end with the passed value:
Will match the following Component:
The '/=' operator will return Components with specified properties that match the passed regular expression:
Will match the following Components with a custom
When you need to use meta characters like , (), etc. in your query, make sure to escape them with back slashes:
The following test will find panels with their
ownProperty collapsed being equal to
false. It will not match a collapsed property from the prototype chain.
Member expressions from candidate Components may be tested. If the expression returns a truthy value, the candidate Component will be included in the query:
Such expressions are executed in Component's context, and the above expression is similar to running this snippet for every Component in your application:
It is important to use only methods that are available in every Component instance to avoid run time exceptions. If you need to match your Components with a custom condition formula, you can augment
Ext.Component to provide custom matcher that will return
false by default, and override it in your custom classes:
After that you can use a selector with your custom matcher to find all instances of
However if you really need to use a custom matcher, you may find it easier to implement a custom Pseudo class instead (see below).
Attribute matchers can be combined to select only Components that match all conditions (logical AND operator):
E.g., the query above will match only a Panel-descended Component that has 'my-cls' CSS class and is floating and with a title that ends with "sales data".
Expressions separated with commas will match any Component that satisfies either expression (logical OR operator):
E.g., the query above will match any field with field label starting with "User", or any field that has "password" in its label.
If you need to include a comma in an attribute matching expression, escape it with a backslash:
Pseudo classes may be used to filter results in the same way as in Ext.dom.Query. There are five default pseudo classes:
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 focus.
nth-child Filters Components by ordinal position in the selection.
These pseudo classes can be used with other matchers or without them:
nth-child can be used to find any child Component by its position relative to its siblings. This class' handler takes one argument that specifies the selection formula as
Pseudo classes can be combined to further filter the results, e.g., in the form example above we can modify the query to exclude hidden fields:
Note that when combining pseudo classes, whitespace is significant, i.e. there should be no spaces between pseudo classes. This is a common mistake; if you accidentally type a space between
:not, the query will not return any result because it will mean "find field's children Components that are not hidden fields...".
Custom pseudo classes
It is possible to define your own custom pseudo classes. In fact, a pseudo class is just a property in
Ext.ComponentQuery.pseudos object that defines pseudo class name (property name) and pseudo class handler (property value):
Pseudo class handlers can be even more flexible, with a selector argument used to define the logic:
Be careful when using custom pseudo classes with MVC Controllers: when you use a pseudo class in Controller's
listen component selectors, the pseudo class' handler function will be called very often and may slow down your application significantly. A good rule of thumb is to always specify Component xtype with the pseudo class so that the handlers are only called on Components that you need, and try to make the condition checks as cheap in terms of execution time as possible. Note how in the example above, handler function checks that Component has a title first, before running regex test on it.
Queries return an array of Components. Here are some example queries:
For easy access to queries based from a particular Container see the Ext.container.Container.query, Ext.container.Container.down andExt.container.Container.child methods. Also see Ext.Component.up.