"The Composite (Design pattern) allows a group of objects to be treated in the same way as a single instance of an object." (Wikipedia) Ext.CompositeElement allows you to work with a collection of zero to many elements as a single entity. CompositeElement uses the same interface as Ext.Element simplifying your job as a developer and eliminating the need for common run-time checks when dealing with a collection. CompositeElement's are typically retrieved by using the static method Ext.select. Ext.select uses DomQuery to search the entire document for any element which matches a particular selector.
For example given the following markup:
<html>
<body>
<div id="first" class="title">Sample A</div>
<div id="second" class="doesNotMatch">Lorem Ipsum</div>
<div id="third" class="title secondCSSCls">Some additional content</div>
</body>
</html>
We could use the CSS selector '.title' to search the entire page and retrieve a CompositeElement that contains references to the div's first and third.
var els = Ext.select('.title');
Note: The element third also has an additional CSS class of secondCSSCls. HtmlElement's can have multiple CSS classes by separating them with a space. This selector does not require that only title is applied and therefore both 'first' and 'third' will be returned.
After obtained a CompositeElement we can now work with this collection of Elements as a single element. For Example, we could then add a CSS class of error to the collection.
var els = Ext.select('.title'); els.addClass('error');
When you are aware of the location of the elements you want to retrieve relative to another element on the page you should first obtain a reference to that element and then search from there. This will make your search perform faster because it is searching a smaller subset of the entire document. Let's see what happens when we add an additional div with an id of 'accordion' wrapping around our first, second and third elements.
<html>
<body>
<div id="accordion">
<div id="first" class="title">Sample A</div>
<div id="second" class="doesNotMatch">Lorem Ipsum</div>
<div id="third" class="title secondCSSCls">
Some additional content
</div>
</div>
</body>
</html>
Since we know that the elements will be within a div with an id of accordion we can scope our search to only the accordion element.
var accordion = Ext.get('accordion'); accordion.select('title');
Any time that you are aware of the location of the elements within your markup you should make sure that you scope your search like this to optimize performance.
Other useful methods of CompositeElement are displayed in this code sample:
var accordion = Ext.get('accordion'); accordion.select('title'); // firstItem now has an Ext.Element pointing to the first div var firstItem = accordion.item(0); // alerts 1 or the second position alert(accordion.indexOf('third')); // alerts 2 alert(accordion.getCount()); // Removes the element from the collection and from the DOM accordion.removeElement('one', true);
Note: Methods which have been removed from CompositeElement which users of Ext JS may be familiar with: each, first, last, fill, contains, filter.