jQuery: The Write Less, Do More JavaScript Library

API/1.1.2/DOM/Traversing

From jQuery JavaScript Library

(Redirected from DOM/Traversing)
Jump to: navigation, search


[edit]

add( expr )

Adds more elements, matched by the given expression, to the set of matched elements.

Return value: jQuery
Parameters:

  • expr (String): An expression whose matched elements are added

Example:

Compare the above result to the result of $('p'), which would just result in [ <p>Hello</p> ]. Using add(), matched elements of $('span') are simply added to the returned jQuery-object.

 $("p").add("span")
Before: 
 (HTML) <p>Hello</p><span>Hello Again</span>
Result: 
 (jQuery object matching 2 elements) [ <p>Hello</p>, <span>Hello Again</span> ]


[edit]

add( html )

Adds more elements, created on the fly, to the set of matched elements.

Return value: jQuery
Parameters:

  • html (String): A string of HTML to create on the fly.

Example: 

 $("p").add("<span>Again</span>")
Before: 
 <p>Hello</p>
Result: 
 [ <p>Hello</p>, <span>Again</span> ]


[edit]

add( elements )

Adds one or more Elements to the set of matched elements.

Return value: jQuery
Parameters:

  • elements (Element|Array<Element>): One or more Elements to add

Example: 

 $("p").add( document.getElementById("a") )
Before: 
 <p>Hello</p><p><span id="a">Hello Again</span></p>
Result: 
 [ <p>Hello</p>, <span id="a">Hello Again</span> ]


Example: 

 $("p").add( document.forms[0].elements )
Before: 
 <p>Hello</p><p><form><input/><button/></form>
Result: 
 [ <p>Hello</p>, <input/>, <button/> ]


[edit]

children( expr )

Get a set of elements containing all of the unique children of each of the matched set of elements.

This set can be filtered with an optional expression that will cause only elements matching the selector to be collected.

Return value: jQuery
Parameters:

  • expr (String): (optional) An expression to filter the child Elements with

Example:

Find all children of each div.

 $("div").children()
Before: 
 <p>Hello</p><div><span>Hello Again</span></div><p>And Again</p>
Result: 
 [ <span>Hello Again</span> ]


Example:

Find all children with a class "selected" of each div.

 $("div").children(".selected")
Before: 
 <div><span>Hello</span><p class="selected">Hello Again</p><p>And Again</p></div>
Result: 
 [ <p class="selected">Hello Again</p> ]


[edit]

contains( str )

Filter the set of elements to those that contain the specified text.

Return value: jQuery
Parameters:

  • str (String): The string that will be contained within the text of an element.

Example: 

 $("p").contains("test")
Before: 
 <p>This is just a test.</p><p>So is this</p>
Result: 
 [ <p>This is just a test.</p> ]


[edit]

end()

Revert the most recent 'destructive' operation, changing the set of matched elements to its previous state (right before the destructive operation).

If there was no destructive operation before, an empty set is returned.

A 'destructive' operation is any operation that changes the set of matched jQuery elements. These functions are: add, children, clone, filter, find, not, next, parent, parents, prev and siblings.

Return value: jQuery
Example:

Selects all paragraphs, finds span elements inside these, and reverts the selection back to the paragraphs.

 $("p").find("span").end();
Before: 
 <p><span>Hello</span>, how are you?</p>
Result: 
 [ <p>...</p> ]


[edit]

filter( expression )

Removes all elements from the set of matched elements that do not match the specified expression(s). This method is used to narrow down the results of a search.

Provide a comma-separated list of expressions to apply multiple filters at once.

Return value: jQuery
Parameters:

  • expression (String): Expression(s) to search with.

Example:

Selects all paragraphs and removes those without a class "selected".

 $("p").filter(".selected")
Before: 
 <p class="selected">Hello</p><p>How are you?</p>
Result: 
 [ <p class="selected">Hello</p> ]


Example:

Selects all paragraphs and removes those without class "selected" and being the first one.

 $("p").filter(".selected, :first")
Before: 
 <p>Hello</p><p>Hello Again</p><p class="selected">And Again</p>
Result: 
 [ <p>Hello</p>, <p class="selected">And Again</p> ]


[edit]

filter( filter )

Removes all elements from the set of matched elements that do not pass the specified filter. This method is used to narrow down the results of a search.

Return value: jQuery
Parameters:

  • filter (Function): A function to use for filtering

Example:

Remove all elements that have a child ol element

 $("p").filter(function(index) {
   return $("ol", this).length == 0;
 })
Before: 
 <p><ol><li>Hello</li></ol></p><p>How are you?</p>
Result: 
 [ <p>How are you?</p> ]


[edit]

find( expr )

Searches for all elements that match the specified expression. This method is a good way to find additional descendant elements with which to process.

All searching is done using a jQuery expression. The expression can be written using CSS 1-3 Selector syntax, or basic XPath.

Return value: jQuery
Parameters:

  • expr (String): An expression to search with.

Example:

Starts with all paragraphs and searches for descendant span elements, same as $("p span")

 $("p").find("span");
Before: 
 <p><span>Hello</span>, how are you?</p>
Result: 
 [ <span>Hello</span> ]


[edit]

is( expr )

Checks the current selection against an expression and returns true, if at least one element of the selection fits the given expression.

Does return false, if no element fits or the expression is not valid.

filter(String) is used internally, therefore all rules that apply there apply here, too.

Return value: Boolean
Parameters:

  • expr (String): The expression with which to filter

Example:

Returns true, because the parent of the input is a form element

 $("input[@type='checkbox']").parent().is("form")
Before: 
 <form><input type="checkbox" /></form>
Result: 
 true


Example:

Returns false, because the parent of the input is a p element

 $("input[@type='checkbox']").parent().is("form")
Before: 
 <form><p><input type="checkbox" /></p></form>
Result: 
 false


[edit]

next( expr )

Get a set of elements containing the unique next siblings of each of the matched set of elements.

It only returns the very next sibling for each element, not all next siblings.

You may provide an optional expression to filter the match.

Return value: jQuery
Parameters:

  • expr (String): (optional) An expression to filter the next Elements with

Example:

Find the very next sibling of each paragraph.

 $("p").next()
Before: 
 <p>Hello</p><p>Hello Again</p><div><span>And Again</span></div>
Result: 
 [ <p>Hello Again</p>, <div><span>And Again</span></div> ]


Example:

Find the very next sibling of each paragraph that has a class "selected".

 $("p").next(".selected")
Before: 
 <p>Hello</p><p class="selected">Hello Again</p><div><span>And Again</span></div>
Result: 
 [ <p class="selected">Hello Again</p> ]


[edit]

not( el )

Removes the specified Element from the set of matched elements. This method is used to remove a single Element from a jQuery object.

Return value: jQuery
Parameters:

  • el (Element): An element to remove from the set

Example:

Removes the element with the ID "selected" from the set of all paragraphs.

 $("p").not( $("#selected")[0] )
Before: 
 <p>Hello</p><p id="selected">Hello Again</p>
Result: 
 [ <p>Hello</p> ]


[edit]

not( expr )

Removes elements matching the specified expression from the set of matched elements. This method is used to remove one or more elements from a jQuery object.

Return value: jQuery
Parameters:

  • expr (String): An expression with which to remove matching elements

Example:

Removes the element with the ID "selected" from the set of all paragraphs.

 $("p").not("#selected")
Before: 
 <p>Hello</p><p id="selected">Hello Again</p>
Result: 
 [ <p>Hello</p> ]


[edit]

not( elems )

Removes any elements inside the array of elements from the set of matched elements. This method is used to remove one or more elements from a jQuery object.

Please note: the expression cannot use a reference to the element name. See the two examples below.

Return value: jQuery
Parameters:

  • elems (jQuery): A set of elements to remove from the jQuery set of matched elements.

Example:

Removes all elements that match "div p.selected" from the total set of all paragraphs.

 $("p").not( $("div p.selected") )
Before: 
 <div><p>Hello</p><p class="selected">Hello Again</p></div>
Result: 
 [ <p>Hello</p> ]


[edit]

parent( expr )

Get a set of elements containing the unique parents of the matched set of elements.

You may use an optional expression to filter the set of parent elements that will match.

Return value: jQuery
Parameters:

  • expr (String): (optional) An expression to filter the parents with

Example:

Find the parent element of each paragraph.

 $("p").parent()
Before: 
 <div><p>Hello</p><p>Hello</p></div>
Result: 
 [ <div><p>Hello</p><p>Hello</p></div> ]


Example:

Find the parent element of each paragraph with a class "selected".

 $("p").parent(".selected")
Before: 
 <div><p>Hello</p></div><div class="selected"><p>Hello Again</p></div>
Result: 
 [ <div class="selected"><p>Hello Again</p></div> ]


[edit]

parents( expr )

Get a set of elements containing the unique ancestors of the matched set of elements (except for the root element).

The matched elements can be filtered with an optional expression.

Return value: jQuery
Parameters:

  • expr (String): (optional) An expression to filter the ancestors with

Example:

Find all parent elements of each span.

 $("span").parents()
Before: 
 <html><body><div><p><span>Hello</span></p><span>Hello Again</span></div></body></html>
Result: 
 [ <body>...</body>, <div>...</div>, <p><span>Hello</span></p> ]


Example:

Find all parent elements of each span that is a paragraph.

 $("span").parents("p")
Before: 
 <html><body><div><p><span>Hello</span></p><span>Hello Again</span></div></body></html>
Result: 
 [ <p><span>Hello</span></p> ]


[edit]

prev( expr )

Get a set of elements containing the unique previous siblings of each of the matched set of elements.

Use an optional expression to filter the matched set.

Only the immediately previous sibling is returned, not all previous siblings.

Return value: jQuery
Parameters:

  • expr (String): (optional) An expression to filter the previous Elements with

Example:

Find the very previous sibling of each paragraph.

 $("p").prev()
Before: 
 <p>Hello</p><div><span>Hello Again</span></div><p>And Again</p>
Result: 
 [ <div><span>Hello Again</span></div> ]


Example:

Find the very previous sibling of each paragraph that has a class "selected".

 $("p").prev(".selected")
Before: 
 <div><span>Hello</span></div><p class="selected">Hello Again</p><p>And Again</p>
Result: 
 [ <p class="selected">Hello Again</p> ]


[edit]

siblings( expr )

Get a set of elements containing all of the unique siblings of each of the matched set of elements.

Can be filtered with an optional expressions.

Return value: jQuery
Parameters:

  • expr (String): (optional) An expression to filter the sibling Elements with

Example:

Find all siblings of each div.

 $("div").siblings()
Before: 
 <p>Hello</p><div><span>Hello Again</span></div><p>And Again</p>
Result: 
 [ <p>Hello</p>, <p>And Again</p> ]


Example:

Find all siblings with a class "selected" of each div.

 $("div").siblings(".selected")
Before: 
 <div><span>Hello</span></div><p class="selected">Hello Again</p><p>And Again</p>
Result: 
 [ <p class="selected">Hello Again</p> ]


Retrieved from "http://docs.jquery.com/API/1.1.2/DOM/Traversing"