Add Filters

The add filter is a little strange in that it doesn't remove elements from the results array it adds them. There are a number of forms of this filter depending on how you specify what is to be added.

You can use any jQuery selector and the results will be added to the existing results array.

That is:

.add(selector)

adds the jQuery object that results from evaluating the selector on the document to the existing selection.

The complication is that the selector can be almost anything that would create a jQuery result when used in $(selector).

For example:

$("p").add("div");

adds all the div elements in the document to the array of p elements.

That is, it gives you the same result as:

$("p,div")

It is surprising that the add method performs a full selection on the document and this makes it more powerful than you might expect.

A simpler use of the add method is to add existing or constructed objects.

For example:

result3=result1.add(result2);

will add the elements in result2 to the elements in result1 to give a unified result list. 

You can also add constructed objects using HTML:

$("p").add("<p>hello</p>");

adds the HTML as an element to the results array as a new results array.

The add method can sometimes be useful when you are trying to build up a list of elements that satisfy complex conditions.  

Other Filters

There are other filters which have been added to jQuery in a fairly ad-hoc way. They are useful, but they don't fit into any neat patterns or families.

:animated

Selects elements in the process of animation at the time the selector is run. Clearly this one isn't really a filter on the results array as it is tied to the time that the query is run. However, it is even faster to use:

.filter(":animated")

:contains

Selects all elements that contain the specified text. The match can be within the element or within any child element. For example:

:contains(jQuery) 

will return results that contain the string jQuery with that capitalization. 

:disabled

Selects all elements that are disabled at the time the query is run.

:enabled

Selects all elements that are enabled at the time the query is run.

:focus 

Selects the element that has the current focus. Again this isn't really a filter on the result array because it matters when the query is run. 

:header 

Selects all header elements h1,h2 and so on. This one is convertible to a true filter and it is better to use:

.filter(":header")

:image

Selects all image elements.

:lang(language)

Selects all elements with a language attribute as specified. It also extracts elements contained within language-specific elements on the assumption that they inherit the language setting unless it is overridden.

:root

Selects the root element of the document, usually html.

:selected

Selects all elements that are selected at the time of the query

:target

Selects the element with the id that matches any fragment identifier in the URL. That is, if the URL is www.mysite.com/#mycontrol, then :target selects the element, if any, with an id of mycontrol. 

:visible

Selects all elements visible at the time the query is run.

There are more miscellaneous filters but the line between filter and selector starts to be increasingly blurred. After all is :header a selector or a filter? There is a tendency in jQuery to call any non-standard selector a filter and this can be confusing. 

There are also selectors that work with forms and these are discussed in Chapter 10.

For completeness these are:

• :button – select all button elements

• :checkbox - select all checkbox elements

• :file – select all file elements

• :password – select all password elements

• :radio – select all radio buttons

• :reset – select all reset elements

• :submit – select all submit elements

• :text – select all text input elements

The Filter Stack

This is the final twist in the filter story.

If you have been following the description of how filters work then you will appreciate the idea that filters take one jQuery result array and convert it into another filtered result array. What hasn't been made clear until now is that each time you create a new result array using a filter the old original unfiltered result array is kept, just in case you want to use it again.

This is generally what happens with chained jQuery calls as explained at the end of Chapter 4. Each function call creates a new jQuery result object and the new object keeps a reference to the old result.

You can restore the old result array in a number of ways, but the simplest is to use the .end() method. For example:

$("p");

produces a result array containing all of the p elements. We can use the eq filter to reduce this to just the first p element and add some text:

$("p").eq(0).append("1");

If we now use .end we can return to the result array that had the entire set of p elements:

$("p").eq(0).append("1").end();

Now we can filter again and add some text to the second p element;

$("p").eq(0).append("1").end().eq(1).append("2");

You can continue in this way using .end to return to a previous result array whenever you need to.

Usually this is about as complicated as it gets, but each jQuery results object maintains reference to the previous object and this behaves like a stack of previous results so .end().end() returns to the result that you had before two filtering operations. 

Of course, an alternative to using end() is to simply keep the intermediate results:

var result=$("p"):

result.eq(0).append("1"):

result.eq(1).append("2");

The end function and the stack simply makes it possible for you to do the same thing but using a fluent approach.

As well as end() there is also addBack(selector) method which filters the current result and then adds it to the new results. This is, of course, a silly operation to perform if the filter doesn't select additional elements – there is no point in eliminating some of the elements and then adding them back. This means that it really only makes sense to use it after one of the traversal filters, which are covered in the next chapter. 

For example:

$("p").parent("div").addBack();

first selects all p elements, then selects all of the immediate parent div elements and then adds the original p elements back to the result array. Notice that you get all of the p elements. 

You can also add a selector to filter the elements that are added back to the results:

$("p").parent("div").addBack(":eq(0)");

adds only the first p element back to the results.   

If you want to be really advanced there is also the .pushstack() method that will push an array of elements on the results stack and the .remove() method that pops anything added back off the stack.