These methods provide other mechanisms for manipulating the set of matched DOM elements in a jQuery object.
|
Adds elements to the set of matched elements. .add(selector) .add(elements) .add(html) |
Given a jQuery object that represents a set of DOM elements, the .add method constructs a new jQuery object from the union of those elements and the ones passed into the method. The argument to .add can be pretty much anything that $() accepts, including a jQuery selector expression, references to DOM elements, or an HTML snippet.
Consider a page with a simple list and a paragraph following it:
<ul> <li>list item 1</li> <li>list item 2</li> <li>list item 3</li> </ul> <p>a paragraph</p>
We can select the list items and then the paragraph by using either a selector or a reference to the DOM element itself as the .add method's argument:
$('li').add('p') or
$('li').add(document.getElementsByTagName('p')[0])
The result of this call is a jQuery object wrapping all four elements.
Using an HTML snippet as the .add method's argument (as in the third version) we can create additional elements on the fly and add those elements to the matched set of elements. Let's say, for example, that we want to add a class foo to the list items, the paragraph, and a newly created paragraph:
$('li').add('p').add('<p id="new">new paragraph</p>').addClass('foo')
Although the new paragraph has been created and its foo class added, it still does not appear on the page. To place it on the page, we can add one of the insertion methods to the chain.
For more information about the insertion methods please refer to Chapter 4.
|
Checks the current matched set of elements against a selector and returns .is(selector) |
Unlike the rest of the methods in this chapter, .is() does not create a new jQuery object. Instead, it allows us to test the contents of a jQuery object without modification. This is often useful in callbacks, such as event handlers.
Suppose we have a list, with two of its items containing a child element:
<ul> <li>list <strong>item 1</strong></li> <li><span>list item 2</span></li> <li>list item 3</li> </ul>
We can attach a click handler to the <ul> element, and then limit the code to be triggered only when a list item itself, not one of its children, is clicked:
$('ul').click(function(event) {
if ($(event.target).is('li') ) {
$(event.target).remove();
}
});Now, when the user clicks on the word list in the first item or anywhere in the third item, the clicked list item will be removed from the document. However, when the user clicks on item 1 in the first item or anywhere in the second item, nothing will occur, because for those target of the event would be <strong> and <span> respectively.
|
Ends the most recent filtering operation in the current chain and returns the set of matched elements to its previous state. .end() |
Most of the methods in this chapter operate on a jQuery object and produce a new one, matching a different set of DOM elements. When this happens, it is as if a new set of elements is pushed onto a stack that is maintained inside the object. Each successive filtering method pushed a new element set onto the stack. If we need an older element set, we can use .end() to pop the sets back off of the stack.
Suppose we have a couple of short lists on a page:
<ul class="first"> <li class="foo">list item 1</li> <li>list item 2</li> <li class="bar">list item 3</li> </ul> <ul class="second"> <li class="foo">list item 1</li> <li>list item 2</li> <li class="bar">list item 3</li> </ul>
The .end method is useful primarily when exploiting jQuery's chaining properties. When not using chaining, we can usually just call up a previous object by variable name, so that we don't need to manipulate the stack. With .end(), though, we can string all the method calls together:
$('ul.first').find('.foo').addClass('some-class').end() .find('.bar').addClass('another-class');
This chain searches for items with the class foo within the first list only and adds the class some-class to them. Then .end() returns the object to its state before the call to .find(), so the second .find() looks for .bar inside <ul class="first">, not just inside that list's <li class="foo">, and adds the class another-class to the matching element. The result is that items 1 and 3 of the first list have a class added to them, and none of the items from the second list do.
A long jQuery chain can be visualized as a structured code block, with filtering methods providing the openings of nested blocks and .end methods closing them:
$('#example-traversing-end ul.first').find('.foo')
.addClass('some-class')
.end()
.find('.bar')
.addClass('another-class');
.end();The last .end() is unnecessary, as we are discarding the jQuery object immediately thereafter. However, when the code is written in this form the .end() provides visual symmetry and closure—making the program, at least to the eyes of some developers, more readable.