Ext.ComponentQuery

Hierarchy

Requires

Files

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

Basic Component lookup

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

prevField = myField.previousNode('textfield');

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

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

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

#myContainer

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

panel#myPanel

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 ^ and > 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 false) value.

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.

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:

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

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

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

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

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:

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

Pseudo classes

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:

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

Pseudo class 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 Xn or Xn+Y:

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

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:

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

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 field and :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):

Be careful when using custom pseudo classes with MVC Controllers: when
you use a pseudo class in Controller's control or 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.

Query examples

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

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

...

Defaults to: {}

Available since: 4.1.1

...

Defaults to: true

Available since: 4.1.1

Get the reference to the current class from which this object was instantiated. ...

Get the reference to the current class from which this object was instantiated. Unlike statics,
this.self is scope-dependent and it's meant to be used for dynamic inheritance. See statics
for a detailed comparison

The arguments, either an array or the arguments object
from the current method, for example: this.callParent(arguments)

Returns

Returns the result of calling the parent method

This method is used by an override to call the superclass method but bypass any
overridden method. ...

This method is used by an override to call the superclass method but bypass any
overridden method. This is often done to "patch" a method that contains a bug
but for whatever reason cannot be fixed directly.

To patch the bug in DerivedClass.method, the typical solution is to create an
override:

The patch method cannot use callParent to call the superclass method since
that would call the overridden method containing the bug. In other words, the
above patch would only produce "Fixed" then "Good" in the console log, whereas,
using callParent would produce "Fixed" then "Bad" then "Good".

...

Available since: 4.0.0

Parameters

Returns

this

Get the reference to the class from which this object was instantiated. ...

Get the reference to the class from which this object was instantiated. Note that unlike self,
this.statics() is scope-independent and it always returns the class from which it was called, regardless of what
this points to during run-time

As of 4.1, direct use of this method is deprecated. Use Ext.define
instead:

The above accomplishes the same result but can be managed by the Ext.Loader
which can properly order the override and its target class and the build process
can determine whether the override is needed based on the required state of the
target class (My.Cat).