down
down(element[, cssRule][, index = 0]) -> HTMLElement | undefined
Returns element’s first descendant (or the n-th descendant if index
is specified) that matches cssRule
. If no cssRule
is provided, all descendants are considered. If no descendant matches these criteria, undefined
is returned.
The Element.down
method is part of Prototype’s ultimate DOM traversal toolkit (check out Element.up
, Element.next
and Element.previous
for some more Prototypish niceness). It allows precise index-based and/or CSS rule-based selection of any of the element’s descendants.
As it totally ignores text nodes (it only returns elements), you don’t have to worry about whitespace nodes.
And as an added bonus, all elements returned are already extended allowing chaining:
$(element).down(1).next('li', 2).hide();
Walking the DOM has never been that easy!
Arguments
If no argument is passed, element
’s first descendant is returned (this is similar as calling firstChild
except Element.down
returns an already extended element.
If an index is passed, element
’s corresponding descendant is returned. (This is equivalent to selecting an element from the array of elements returned by the method Element.descendants
.) Note that the first element has an index of 0.
If cssRule
is defined, Element.down
will return the first descendant that matches it. This is a great way to grab the first item in a list for example (just pass in ‘li’ as the method’s first argument).
If both cssRule
and index
are defined, Element.down
will collect all the descendants matching the given CSS rule and will return the one specified by the index.
In all of the above cases, if no descendant is found, undefined
will be returned.
Examples
<ul id="fruits">
<li id="apples">
<ul>
<li id="golden-delicious">Golden Delicious</li>
<li id="mutsu" class="yummy">Mutsu</li>
<li id="mcintosh" class="yummy">McIntosh</li>
<li id="ida-red">Ida Red</li>
</ul>
</li>
</ul>
$('fruits').down();
// equivalent:
$('fruits').down(0);
// -> li#apple
$('fruits').down(3);
// -> li#golden-delicious
$('apples').down('li');
// -> li#golden-delicious
$('apples').down('li.yummy');
// -> li#mutsu
$('fruits').down('.yummy', 1);
// -> li#mcintosh
$('fruits').down(99);
// -> undefined