class method Element.previous
Element.previous(element[, expression[, index = 0]]) → Element
Element.previous(element[, index = 0]) → Element
-
expression
(String
) – A CSS selector.
Returns element
's first previous sibling (or the Nth, if index
is specified) that matches expression
. If no expression
is
provided, all previous siblings are considered. If none matches these
criteria, undefined
is returned.
More information
The Element.previous
method is part of Prototype's ultimate DOM
traversal toolkit (check out Element.up
, Element.down
and
Element.next
for some more Prototypish niceness). It allows precise
index-based and/or CSS expression-based selection of any of element
's
previous siblings. (Note that two elements are considered siblings if
they have the same parent, so for example, the head
and body
elements
are siblings—their parent is the html
element.)
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('p').previous('ul', 2).hide();
Walking the DOM has never been that easy!
Arguments
If no arguments are passed, element
's previous sibling is returned
(this is similar as calling previousSibling
except Element.previous
returns an already extended element).
If index
is defined, element
's corresponding previous sibling is
returned. (This is equivalent to selecting an element from the array of
elements returned by the method Element.previousSiblings
). Note that
the sibling right above element
has an index of 0.
If expression
is defined, Element.previous
will return the element
first previous sibling that matches it.
If both expression
and index
are defined, Element.previous
will
collect all of element
's previous siblings matching the given CSS
expression and will return the one at the specified index.
In all of the above cases, if no previous sibling is found,
undefined
will be returned.
Examples
<ul id="fruits">
<li id="apples">
<h3>Apples</h3>
<ul id="list-of-apples">
<li id="golden-delicious" class="yummy">Golden Delicious</li>
<li id="mutsu" class="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>
Get the first previous sibling of "#saying":
$('saying').previous();
// or:
$('saying').previous(0);
// -> ul#list-of-apples
Get the second previous sibling of "#saying":
$('saying').previous(1);
// -> h3
Get the first previous sibling of "#saying" with node name "h3":
$('saying').previous('h3');
// -> h3
Get the first previous sibling of "#ida-red" with class name "yummy":
$('ida-red').previous('.yummy');
// -> li#mutsu
Get the second previous sibling of "#ida-red" with class name "yummy":
$('ida-red').previous('.yummy', 1);
// -> li#golden-delicious
Try to get the sixth previous sibling of "#ida-red":
$('ida-red').previous(5);
// -> 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.