getElementsBySelector(element, selector...) -> [HTMLElement...]

Takes an arbitrary number of CSS selectors (strings) and returns an array of extended children of element that match any of them.

As of Prototype 1.6, Element#getElementsBySelector has been deprecated in favor of the more concise Element#select.

This method is very similar to $$() but can be used within the context of one element, rather than the whole document. The supported CSS syntax is identical, so please refer to the $$() docs for details.

Examples

<ul id="fruits">
  <li id="apples">
    <h3 title="yummy!">Apples</h3>
    <ul id="list-of-apples">
      <li id="golden-delicious" title="yummy!" >Golden Delicious</li>
      <li id="mutsu" title="yummy!">Mutsu</li>
      <li id="mcintosh">McIntosh</li>
      <li id="ida-red">Ida Red</li>
    </ul>
    <p id="saying">An apple a day keeps the doctor away.</p>  
  </li>
</ul>

$('apples').getElementsBySelector('[title="yummy!"]');
// -> [h3, li#golden-delicious, li#mutsu]

$('apples').getElementsBySelector( 'p#saying', 'li[title="yummy!"]');
// -> [li#golden-delicious, li#mutsu,  p#saying]

$('apples').getElementsBySelector('[title="disgusting!"]');
// -> []

Tip

Element#getElementsBySelector can be used as a pleasant alternative to getElementsByTagName:

var nodes  = $A(someUL.getElementsByTagName('li')).map(Element.extend);
var nodes2 = someUL.getElementsBySelector('li');

In the first example, you must explicitly convert the result set to an Array (so that Prototype’s Enumerable methods can be used) and must manually call Element.extend on each node (so that custom instance methods can be used on the nodes). Element#getElementsBySelector takes care of both concerns on its own.

If you’re using 1.5.1 or above (and the performance optimizations therein), the speed difference between these two examples is negligible.