instance method Element#down
Element#down([expression[, index = 0]]) → Element
Element#down([index = 0]) → Element
-
expression
(String
) – A CSS selector.
Returns element
's first descendant (or the Nth descendant, if index
is specified) that matches expression
. If no expression
is
provided, all descendants are considered. If no descendant matches these
criteria, undefined
is returned.
More information
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
(see Element.extend
) allowing chaining:
$(element).down(1).next('li', 2).hide();
Walking the DOM has never been that easy!
Arguments
If no arguments are passed, element
's first descendant is returned (this
is similar to calling firstChild
except Element.down
returns an
extended element.
If index
is defined, 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 expression
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 expression
and index
are defined, Element.down
will collect
all the descendants matching the given CSS expression and will return the
one at the specified 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>
Get the first descendant of "#fruites":
$('fruits').down();
// or:
$('fruits').down(0);
// -> li#apples
Get the third descendant of "#fruits":
$('fruits').down(3);
// -> li#golden-delicious
Get the first descendant of "#apples" with the node name "li":
$('apples').down('li');
// -> li#golden-delicious
Get the first descendant of "#apples" with the node name "li" and the class name "yummy":
$('apples').down('li.yummy');
// -> li#mutsu
Get the second descendant of "#fruits" with the class name "yummy":
$('fruits').down('.yummy', 1);
// -> li#mcintosh
Try to get the ninety-ninth descendant of "#fruits":
$('fruits').down(99);
// -> undefined
This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.