pushStack Basics

At its most basic level, the .pushStack() method accepts an array of DOM elements and "pushes" it onto a "stack" so that later calls to methods like .end() and .andSelf() behave correctly. (Side note: As of jQuery 1.4.2, you can pass in a jQuery object instead of an array, but that isn't documented and jQuery itself always uses an array, so that's what we'll stick to here.)

Internally, jQuery uses .pushStack() to keep track of the previous jQuery collections as you chain traversing methods such as .parents() and .filter(). This lets us traverse through the DOM, do some stuff, "back up" to previous collections within the same chain using .end(), and then do something else. Here is a somewhat contrived example:

Because .find() returns the result of a .pushStack() call to keep track of the previous collection (as does .parent()), we can use .end() in the above example to return to the container divs.

Using pushStack for Fun and Profit

So, this is great for jQuery, but what can .pushStack() do for me and my code? Well, it can help me write specialized DOM traversal plugins that act just like jQuery's own traversal methods. In other words, I can stop chaining the same sets of traversal methods together and instead write a reusable function that still works with with .end() and all that. For example, let's say I often have a need to find an element's grandparent. While I could write $('#myElement').parent().parent() every time, it might be nice to just be able to write $('#myElement').grandparent() instead. A naïve way to write a grandparent plugin would look like this (changing the method name to "grandpa" for this example):

The problem here is that two new jQuery object instances are added to the stack. So, let's see what happens when we use it:

Without seeing the plugin, we would expect to see "child son" inserted into <div class="son">, but "pa" is inserted instead. Each .parent() call in the plugin adds to the stack, so using .end() only pops the second one off.

If we use .pushStack() instead, however, we can achieve the expected behavior:

Within a plugin function, one that is a method of $.fn, the this keyword refers to the jQuery object; therefore, the els variable refers to a jQuery object, as well. To convert it to an array, we use jQuery's .get() method, and we pass that array to .pushStack(). Let's see if .grandma() works any better than .grandpa().

Here, "child daughter" is inserted, which means that .end() works as expected, changing the jQuery collection from the result of .grandma() to the result of $('div.daughter'). So, we've just successfully written a DOM traversal plugin, albeit a very simple one.

The Simplest DOM Traversal Methods

If the plugin only uses one DOM traversal method, then .pushStack() isn't really necessary. The HTML5 data filter plugin written by Elijah Manor illustrates this point nicely:

Only one new jQuery collection is added to the stack, via .filter(), so using .end() simply pops that one off, and our job is done.

Filtering grandparents

For the sake of completeness, it would be nice for this DOM traversal plugin to allow optional "filtering" of the parent and grandparent elements. After all, jQuery's .parent() and .parents() allow filtering. For example, if I were to write $('div.child').parent('.daddy'), the jQuery collection would only contain an element if div.child had a parent element and if that parent had a class of "daddy."

There are plenty of reasonable ways one could include the filters, but for my purposes I'm going to have a .grandparent() method optionally accept two arguments. If only one argument is provided, it will filter the grandparent element only; if two are provided, the first will filter the parent and the second will filter the grandparent. Here is the full plugin plugin:

Finally, we have a nice .grandparent() plugin that adheres to the contract set by other jQuery DOM traversal methods—one that works with both filters and the .end() method. Here is what it could look like in use.

The Styles

For the navigation items, I used a simple unordered list wrapped in a <div class="nav">. While the HTML structure is straightforward, the CSS is a little tricky, so I'll detail it here:

Most of the relevant CSS here has to do with positioning the nav items. I set the top <ul>'s left margin to 75 pixels less than the wrapper's width so that the top-level links appear on the right side. The 1600px width for the <ul> gives the floated list items ample room to line up horizontally next to each other.

The wrapper's overflow declaration is significant, as it hides the list items when they're sticking out to the right, but the rest is "window dressing."

Sliding the Nav

With the nav looking the way I want it at its initial state, it's time to make it do something. I'll start with a simple setup, having each "tab" (top-level item) slide to the left on the first click to reveal its sub-nav items, and slide back to its initial position when it's clicked a second time.

For this basic behavior, everything can be done inside a click handler for the top-level links. Note: Since I'm using multiple navs for this tutorial, each with its own set of behavior, I'll be referring to them by ID, unlike in the CSS snippet above, where everything is styled by class. There is nothing special about the selectors or their naming here. Name your own elements and select them however you want.

The first thing to do is set a few variables. The $parentItem variable is the <li> parent of the clicked link. The slideAmt is the width of the nested <ul>, which is the next sibling of the link. And direction will eventually determine whether the parent <li> should be slid to the left or to the right.

Notice the use of $(this). Inside the click handler, this refers to the clicked DOM element. By wrapping this in $(), we can call jQuery methods on it.

To get the sliding motion to occur, we can animate either the left property or the marginLeft property. Here, I'll animate marginLeft. So, the next thing to do is determine the direction of the animation based on the current value of marginLeft: If it's less than 0, direction is set to "+=", which increases it (back to 0); otherwise, direction is set to "-=". At the same time, an "expanded" class will be toggled so that the arrow background image can change directions.

Finally, we do the animation, plugging in the direction and slideAmt variables. The return false; line stops the default click action from occurring. Here is the finished code for the basic implementation:

Give it a try:

One at a Time

That's all well and good, but I don't really care for having more than one row of items expanded at a time. A couple simple modifications will fix that for us:

The links are stored in a variable first thing here. Whenever a link is clicked, all links have the "expanded" class removed. Of course, only one, at most, will have that class, but I'm lazy and it's easier to tell all of the links to remove the class than it is to hunt links that have the class first.

The same check is performed to set the direction of the animation. If the clicked link's parent <li> is going to be slid to the left, the link will also get the "expanded" class.

Finally, the clicked link's parent is animated in the direction and number of pixels specified by the variables. But here's the twist: all of that parent's siblings have their marginLeft property animated to 0. Again, I'm taking the lazy route, animating all of the siblings, even though one or none of them will need it.

Here's a demo of the "one at a time" version:

Auto-Collapse

Now that the expanding and collapsing are happening the way I like it, I'll add one more little touch. If the user's mouse leaves the containing <div class="tab-nav">, and stays out for a full second, any expanded list will collapse.

Line 2 declares a variable that will be used for the setTimeout(), which you can see tucked inside the .mouseleave() method near the bottom of the code. The setTimeout() function has two arguments: the first is an anonymous function that contains code for triggering the collapse of the list items, and the second is the number of milliseconds to wait (1,000 milliseconds) before the first argument (the anonymous function) is executed. The clearTimeout() inside the .mouseenter() method does what its name suggests: it clears the timeout. If the user mouses out of the nav area but then mouses back in before the 1000 milliseconds are up, the timer is stopped and the function will not be executed.

Note: The mouseenter(fn) and mouseleave(fn) shorthand methods are available as of jQuery 1.3. If you're still using jQuery 1.2.6, you can use .bind('mouseenter', fn) and .bind('mouseleave', fn) instead. Or, with just about any version of jQuery, you can use .hover(fn, fn).

Here is the final demo:

There are many ways to do this sort of thing. Just tweak the CSS or change the animation for a completely different experience.

The Bookmarklet

To use the bookmarklet, drag the following link to your bookmark/favorites list:

» jQuerify «

Then, when you're on a page in which you want to play around with jQuery in the console, just click the bookmarklet.

Problems with the Other One

The biggest problem with the former version was that it didn't work when other libraries that use the $ function, such as Prototype and Mootools, were already loaded on the page. A number of people in the comments suggested that I simply add a jQuery.noConflict(); line to the script. But I wasn't crazy about the idea of having to use jQuery() instead of $() even if no other libraries had been loaded.

Another problem, one that I noticed while testing my new version, was that sometimes the jQuery file that I was inserting from the Google CDN wouldn't fully load by the time I attempted to use it later in the bookmarklet. At least, I think that's what was going on. In any case, it was throwing a "jQuery is not defined" error.

A Few Improvements in This One

To handle the problems, I'm having the script do a few things differently:

• Set up a counter to check 10 times if jQuery is loaded before giving up.
• Use a setTimeout to put a one-quarter-second (250ms) delay interval in between attempts.
• Check if the $() function is already being used by another library. If it is:
  • use jQuery's $.noConflict function to release the $() to the other library.
  • set $jq as an alias to jQuery for convenience.
  • mention in the flash notice that jQuery is in noConflict mode and that $jq() should be used instead of $().
• If after multiple attempts jQuery still won't load for some reason, set the flash notice's message accordingly and then remove it through plain old JavaScript rather than jQuery.

Let me know if this one causes any problems.

1. Update Attribute Selectors

By far the most common stumbling block to the 1.3 upgrade has been the attribute selector. The XPath syntax for this selector — [@attribute] — has been deprecated since version 1.1.4 in August, 2007. Still, many scripts, including some prominent plugins, continued to use the old syntax, which wasn't a problem until jQuery 1.3, at which point it was no longer supported. The correct syntax (since 1.1.4) follows the CSS standard: [attribute].

The fix is quite simple. Simply search your scripts for [@. Go through the matches one by one, and if the string is being used as an attribute selector (and not, for example, in a regular expression), replace it with [.

Removed XPath Syntax

This will break your code in jQuery 1.3+:

Current CSS Syntax

Use this instead:

2. Check Custom Selectors

If you are using custom selectors, either in your own script or within a plugin, you might run across an error if the second argument's object value is a string:

This is another easy fix. Simply change that value to an anonymous function and add what was in the string to the return statement:

So, basically, you just change "jQuery(a).siblings(m[3]).length>0" to function(a,i,m) {return jQuery(a).siblings(m[3]).length>0;}.

When someone on the jQuery Google Group was having trouble with George Adamson's excellent More Selectors plugin, all I had to do to make it compatible with jQuery 1.3 was update the attribute selectors and change custom selectors (my updated script is available here temporarily until George has time to update the original).

3. Note Visible and Hidden Elements

This change didn't occur until jQuery 1.3.2, but if you are upgrading to the latest and greatest jQuery version, you'll want to be sure your scripts aren't relying on a quirk in how jQuery was determining the visibility of elements. Prior to 1.3.2, if you had an element with display:block inside a containing element with display: none, the inner element would still be reported as visible.

Before version 1.3.2, $('#inner'1).is(':visible') would return true and $('#inner1:hidden') would match 0 elements. In order to find out if an element were truly hidden, meaning you couldn't see it, you'd have to check all of its ancestors to see if they were hidden as well. Remy Sharp put together a little custom selector to check if elements were *really* visible.

With 1.3.2, $('#inner').is(':visible) returns false and $('#inner:hidden') match 1 element.

Another Visible Wrinkle

There is one more change in how visibility is detected in 1.3.2: elements with visibility: hidden are now considered visible, whereas before they were considered hidden.

Given the above div structure, jQuery 1.3.2 considers #inner2 visible while prior versions considered it hidden.

Here is a quick demo, with two iFrames showing the differences in determining visibility:

I'm not sure how I feel about the new behavior with visibility:hidden, but I think the change was important for performance reasons.

A Few Others

There are a few other issues that may affect a small minority of users, but the three above represent the lion's share of reported problems that I've seen on the Google Groups. For more information about changes, see the jQuery 1.3 Release Notes

The jQuery easing plugin offers 30 different easing methods, courtesy of Robert Penner's easing equations. Let's check some of them out.

Easing can only be applied when using the .animate() method. The effects helper methods like .show('fast'), .toggle('fast'), fadeIn('fast'), and so on all just use the default easing, "swing."

There are two ways to use easing with the .animate() method. For example, let's say we want to animate the opacity of a particular div. The first way to call .animate() is like this:

The second way is very similar and might even look the same at first glance.

The difference is that the second method signature takes only two arguments: the properties we are animating and an object literal of settings/options. The first method signature separates out the settings/options into individual arguments.

jQuery Easing Plugin

Finally, let's look at a few of the 30 easing methods provided by the easing plugin.

Ease Out Bounce

Ease Out Elastic

Ease Out Back

jQuery UI Easing

jQuery UI includes the easing plugin as part of its Effects Core. It also extends the effects helper methods to support the use of easing and even other types of effects. You can find the documentation for jQuery UI Effects here.

• jQuery UI 1.6 is shaping up to be a rock-solid re-factoring of the entire library. With RC4 released just two days ago, the UI team have further cleaned up the API while providing a set of tools that are even more extensible and configurable than they were before.
• Better project management and greater transparency. Over the last year or so, Paul Bakaus has done much more than lead the development of jQuery UI. He has shaped and nurtured a team of top-notch JavaScript developers and has opened up a lot of the decision-making process to outside scrutiny. This bodes well for the direction of the project.
• Improved jQuery UI ThemeRoller. ThemeRoller, developed and designed by the folks at Filament Group, was already an amazingly useful and elegant complement to jQuery UI. But now it's even better, with a much-improved CSS framework and lighter CSS footprint, a slick default theme, a cool icon sprite set, and more configuration options. Also, it'll soon be easier than ever to create your own UI widgets that take advantage of the ThemeRoller — with upcoming tools, documentation, and tutorials for making your site "ThemeRoller-ready."
• Improved documentation and demos. The documentation wiki has undergone some significant updates in recent months, and the demos went through a complete overhaul in coordination with the 1.6rc4 release.
• More widespread adoption. As the API changes settle down and the core UI developers have more time to spend on providing more widgets and components, such as a spinner, menu, and colorpicker, more sites are sure to join the likes of WordPress in adopting jQuery UI.
• A new blog. While most of the details are still under wraps, a brand new weblog dedicated to learning jQuery UI, similar in quality and scope to Learning jQuery, will be online soon.

Update:

Most jQuery methods return the jQuery object itself, which allows methods to be chained.

The interesting thing about the jQuery object is that while its datatype is an object, it has array-like characteristics:

• its property names (the ones that refer to DOM elements, at least) are numeric
• it has a length property

Have you ever noticed, for example, a snippet of jQuery code that directly accesses a DOM element by using the bracket operator with the jQuery function?

Now, the jQuery function returns an object, but it looks like we just treated it as an array. It can also be written like this:

If this is confusing, let's see if we can clear it up with some code. Go to the jQuery.com homepage, open up Firebug using Firefox, and run the following line of code in the console.

You should be looking at this in the console:

Looky there! The jQuery function is returning an object with a bunch of properties. If we tack on the bracket operator to the jQuery function, which returns an object, we can access the properties of that object because inside the object are properties with a numeric property name. Fascinating isn't it?

I know what you're thinking: this tutorial is about arrays, not objects. Right, so let's get to the array part. Since we now know that the jQuery function returns an object that only masquerades as a JavaScript array the question at hand is how do I get a true JavaScript array from a jQuery wrapper object. This is actually very simple. Most of you might not have been aware (if not, I showed you earlier) that $('div')[0] and $('div').get(0) return a reference to the first element in the jQuery wrapper object. But, the get() method actually has another purpose. It can quickly turn the DOM elements found in the jQuery wrapper into an array of DOM elements.

Let's return to jQuery.com and open up Firebug again. Inside the console run the following line of code.

You should now be looking at this in the firebug console:

"[{}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}, {}]"

Essentially the .get() method placed all of the DOM elements inside the jQuery wrapper into an array and returned that array. So now you can use default array methods on your array of elements. For example:

Additionally, since we now have an array we can write a statement like this:

There is something worth noting here that might not be obvious to those starting out with jQuery or JavaScript. Since we are now returning an array, the chain is broken. You can't chain any jQuery methods after using the .get() method.

But, heck, you have an array. Now you can use the utility functions that jQuery provides ($.each(), $.grep(), $.map(), $.inArray(), $.unique()), as well as core JavaScript methods and properties, to work on the array. I'm not going to demonstrate all of the jQuery utility functions that can be used on an array, but I do want to examine one of them here in this tutorial.

The $.each() utility function, not to be confused with the $('selector').each() method used to operate on a set of DOM elements in a jQuery wrapper, can be used to seamlessly iterate over an array or object. For example, let's say that you would like to store (or cache) a set of <li> elements in an array, because maybe you are going to remove them from the DOM temporarily but eventually will be placing them back on the page. To do this you could use the $.each() utility function to loop over an array and append each <li> element back to the page. In the code example below this is done on page load by converting and storing the jQuery wrapper of <li> elements to an array, and then looping over this array in order to place them back on the page.

Notice that I am forgoing the use of the .ready() event by simply placing my jQuery code before the closing body element.

So, hopefully it's obvious how extremely handy it can be at times to make an array out of a jQuery wrapper. In fact, once you are dealing with an array, you can use a handy plugin called Rich Array. This plugin provides the following additional utility functions for arrays. And yes, there is a bit of duplication here with some of the core utility functions.

$.richArray.in() //Checks whether an array contains some value
$.richArray.unique() //Produces the duplicate-free version of the array
$.richArray.diff() //Finds the difference between two arrays.
$.richArray.intersect() //Finds the intersection of two arrays
$.richArray.filter() //Applies filter to the array, using callback function
$.richArray.map() //Applies callback function for each element in the input array, and returns array of values that this function returned
$.richArray.sum() //Computes the sum of all array elements
$.richArray.product() //Calculates the production of all elements of the array
$.richArray.reduce() //Reduces the array. One-element arrays are turned into their unique element
$.richArray.compact() //Creates new version of array without null/undefined values
$.richArray.without() //Creates a new version of the array that doesn't contain the specified value

Test the hostname

To identify the external links, we test for the location.hostname against the link's hostname, which will be represented by this.hostname once we have the selector in place, and make sure the two don't match. We should also test for the mere existence of this.hostname to avoid problems or false positives with "mailto" links. our tests will look like this: this.hostname && location.hostname !== this.hostname.

Use the filter function

Now let's wrap that test in a filter function. For our example, we'll test all links inside an "extlinks" element that match the above test. Here is what it looks like:

A $(document).ready() is wrapped around the script so that it will execute when the DOM has loaded. Line 4 shows the insertion of the image after each of the external links.

Demo

Here is a little demo using the above code. Of the three links, only the second points to a different site. We should see the external-link icon next to it.

So, that's it. Short and sweet.

Here is the simple definition list structure that I'll be using for the example:

First Steps

As usual, we start the script with a "document.ready" line so that it can be fired when the DOM has finished loading. Next comes our primary selector expression. For this example, I've given the targeted <dl> element a class of "expander" so that we don't inadvertently attach the behavior to other <dl>s. And since we're manipulating the contents of each <dd> independently of one another, we can make things happen inside an .each() method:

We ought to declare some variables now. The first two will go right after the document.ready line, while the others will appear inside the .each() method because they change with each <dd> element.

• slicePoint (integer): the number of characters at which the contents will be sliced into two parts. Note: any tag names in the HTML that appear inside the <dd> before the slicePoint will be counted along with the text characters.
• widow (integer): this is a threshold of sorts for whether we want to initially hide part of the <dd>'s contents. If after slicing the contents in two there are fewer words in the second part than the value set by widow, we won't bother hiding anything.

• allText (string): the full contents of the <dd>
• startText (string): the first part of the <dd>'s contents — the part that is immediately visible. First, all characters up to the slicePoint are included, and then any "word" characters at the end of the string are removed to avoid ending with a partial word. Keep in mind that in almost every case this approach will leave us with fewer characters than we indicated in the slicePoint variable
• endText (string): the second part of the <dd>'s contents. This part is initially hidden from view, replaced by a "read more..." link.

Here is what we have so far:

Although jQuery has its own .slice() method, which operates on a jQuery object, we're using JavaScript's native method, which can operate on both strings (as is the case here) and arrays. Our first use of .slice(), declaring the startText variable, has two arguments — one for the beginning position of the string and one for the ending. Our second has only one argument, for the starting position; the (allText) string's length is the implied ending position. Also, note that for startText, we're chaining .slice() and the .replace() regular expression method.

Manipulating the Contents

Now that we have our two blocks of content, we're going to add a "read more..." link after the startText and wrap the endText in a span (with a class of "details"), but only if there are more words than the value defined by the widow variable. (tangent: am I the only one who can't type "widow" right the first time, always typing "window" instead?). There are many ways to create new elements and insert them into the DOM with jQuery. For this example, we're going to use the .html() method, create an array of strings inside it, and join those strings.

I picked up that technique of creating an array and joining its elements from the jQuery Google Group. It seems cleaner than string concatenation somehow, and rumor has it that it's a bit faster, too.

Finishing Touches

We have everything in place now, so all we need to do is hide the content inside our newly created <span class="details"> and attach a click handler to the "read more" link. Here is the completed code:

I used a .fadeIn() because I like the way it looks, but a simple .show() would do. The return false; line is important to prevent a jump to the top of the page on click.

the Demo

Here is a little demo:

Benedick's Question: I pray you, what is he?

Beatrice's Answer: Why, he is the prince's jester: a very dull fool; only his gift is in devising impossible slanders: none but libertines delight in him; and the commendation is not in his wit, but in his villany; for he both pleases men and angers them, and then they laugh at him and beat him. I am sure he is in the fleet: I would he had boarded me. (Much Ado About Nothing, II.1)

Benedick's Question: I do love nothing in the world so well as you: is not that strange?

Beatrice's Answer: As strange as the thing I know not. It were as possible for me to say I loved nothing so well as you: but believe me not; and yet I lie not; I confess nothing, nor I deny nothing. (Much Ado About Nothing, IV.1)

Karl's Question: Why aren't you using another question from Much Ado About Nothing here?

Karl's Answer: Because I'm lazy. And besides, this demo is getting a little too pretentious.

Question: Filter Function

I have this HTML:

PLAIN TEXT

HTML:

1. <p>
2.   <b>Text1</b>
3. </p>
4. <b>Text2</b>

How can I select the second <b>, which is not a child of a <p>? As I am a newbie, I played a little bit around with :not, filter(), but unfortunately...

PLAIN TEXT

JavaScript:

1. $('b').filter(":not(p> b)") // both <b> are selected.
2.  
3. $('b').not('p> b')   // both </b><b> are selected.

Any hints?

Answer

Try this:

This finds all <b> elements and then filters them. The filter returns only those that do not (!) have a parent paragraph ( $(this).parent('p').length ).

Question: Filter by Option Value

I have several options in a select element, each whose value is an integer. I would love to be able to select those above a threshold, such as something like:

$("#mySelect option[value>5]")

I know I can do this with :gt(index) but I'd rather use the actual value for less hard coding and better readability. I think this would be great in other areas too.

I'm sure there are lots of issues with this since the value is really just text, but a straight string comparison would probably do.

Answer

You could try something like this:

This should filter the option elements, selecting only those whose value is greater than 5.

Question: Puzzle of "this"

I am puzzled by the use of this somehow. For example:

PLAIN TEXT

JavaScript:

1. $('.delete').click(function() {
2.   $.post("test2.php",{id:txt},function() {
3.       this.something
4.     };
5. });

Here, if I want to refer this to the $('.delete') element, what shall I write? In the debugger I found that this refers to the function body.

Answer

You could try this:

The $thisDelete variable is now referencing the clicked element wrapped in a jQuery object. This is useful for attaching jQuery methods, chaining, etc. Oh, and by the way, the use of the "$" in $thisDelete isn't necessary, but it has become somewhat of a convention among jQuery developers, as it reminds us that we're dealing with a jQuery object.

Now, when you use $thisDelete inside your $.post, it's still referring to the clicked element.

Question: Swap an Image on Click

I have a simple accordion set up, but I want to be able to change the header's background image from an up arrow state to down arrow state and back automatically. Any ideas on where to go from here?

Answer

After the .click() line [which slides the following div up or dow], you can do something like this...

The first line here stores the clicked header's background image in the "currImage" variable. The second line then sets the background image. It uses a ternary, or conditional, operator to check if the background image is "up-arrow.jpg". If it is, the image is set to "down-arrow.jpg"; if it isn't "up-arrow.jpg", the image is set to "up-arrow.jpg".

Question: How to Center a DIV Vertically in the Viewport

Thing is I got a project on which i want to show a preloader whenever something is sent or some event has been triggered. How could I set the preloader to show itself right on the middle of the screen?? I mean how could I show it on the right middle of the screen even if I got a huge scrollbar on the right side!?

Answer

So here is one way you could get vertical centering in the viewport [with sTop code borrowed from an old copy of Dimensions plugin]:

Take a look at the demo page I put together. Click on a "center" button, and see where the div goes. Scroll down and click on another button. The div still goes to the center of the viewable area.

UPDATE: Because this didn't work properly in Opera 9.5 as reported in comment #4 below, I refactored the code for returning the scroll top and window height values. Please continue to report any errors that you discover. I also welcome suggestions for improvements to any of the code here.