Using PushStack() In jQuery Plugins To Create New Collections

Posted October 29, 2009 at 9:58 AM

Tags: Javascript / DHTML

Most of the time, when creating a plugin in jQuery, I'll leverage built-in functions like filter() and each() to select from or alter the current collection. Plugins that are built in this fashion are auto-wired to have the appropriate stack connections; that is, since jQuery performs non-destructive collection augmentation, when you use a plugin that is built on top of these methods, you can then use the end() method to move back up the collection stack to the previous collection. Occassionally, however, I have the need to create a plugin that builds an entirely new collection that is not an augmented version of the current collection; as such, there is no auto-wiring of the collection chain.

In cases like that, you need to manually create the collection relationship. jQuery provides the pushStack() method for such scenarios. When you call pushStack() off of the current collection, it will take the given collection and associate it to the current collection such that calling the end() method (after the plugin exits) will return the programmer to the current collection.

Let's take a look at a small example:

 Launch code in new window » Download code as text file »

  • <!DOCTYPE HTML>
  • <html>
  • <head>
  • <title>Using PushStack In jQuery Plugins</title>
  • <script type="text/javascript" src="jquery-1.3.2.js"></script>
  • <script type="text/javascript">
  •  
  • // This plugin gets the PREV and NEXT siblings of the
  • // elements in the current collection and pushes it
  • // onto the stack so that end() will return to original
  • // collection.
  •  
  • jQuery.fn.near = function(){
  • // Get a new collection of elements consisting of the
  • // merging of the PREV and NEXT elements.
  • var newCollection = this.prev().add( this.next() );
  •  
  • // When we return this new collection, push it onto
  • // the stack. This will appropriate set the prevObject
  • // proprety of the new collection.
  • return(
  • this.pushStack(
  • newCollection,
  • "near",
  • ""
  • )
  • );
  • };
  •  
  •  
  • // --------------------------------------------------- //
  • // --------------------------------------------------- //
  •  
  •  
  • // When the DOM is ready, initialize.
  • jQuery(function( $ ){
  •  
  • $( "li.start" )
  • .near()
  • .css( "font-style", "italic" )
  • .end()
  • .css( "font-weight", "bold" )
  • ;
  •  
  • });
  •  
  • </script>
  • </head>
  • <body>
  •  
  • <h1>
  • Using PushStack In jQuery Plugins
  • </h1>
  •  
  • <ol>
  • <li>
  • First list item.
  • </li>
  • <li class="start">
  • Second list item.
  • </li>
  • <li>
  • Third list item.
  • </li>
  • </ol>
  •  
  • </body>
  • </html>

Here, we are creating a new jQuery plugin, near(), that returns the aggregation of the prev() and next() elements. When we run the above code, we get the following output:

First list item.
Second list item.
Third list item.

You'll notice that we started with the middle LI and then called the near() plugin method. This returned the first and third list items, which we italicized. We then called end(), moving back to the original collection (li.start), which we then made bold.

Of the arguments passed to the pushStack() method, only the first, which is the new collection, is critical. The second and third arguments which are the Name of the plugin and the Selector that it uses respectively, seem to be used only to set the internal "selector" property.

This is the first time that I have used the pushStack() method, so forgive me if I have gotten something wrong or provided some misinformation. However, based on my demo above, this seems to work quite nicely.

Download Code Snippet ZIP File

Post Comment  |  Ask Ben  |  Other Searches  |  Print Page



Learning ColdFusion 9 - ColdFusion 9 tutorials, samples, examples, demos

Reader Comments

Oct 30, 2009 at 7:44 AM // reply »
10 Comments

Nice write-up Ben! Before I knew about pushStack() I used to just return a new jQuery collection, i.e.

jQuery.fn.plugin = function(){ return $(something); }

It worked in most cases but obviously didn't retain the original jQuery instance. This can be misleading - the jQuery instance really shouldn't change half way through a chain.

pushStack() is the ideal way to do this because it doesn't remove or create a new object, it simply modifies the current one.

I hope others will take this into account when creating plugins that change the collection.


Oct 30, 2009 at 7:54 AM // reply »
7,572 Comments

@James,

I think the real problem is that there's like ZERO documentation on this method. In fact, if you even go to the plugin authoring section of the jQuery website, they don't even mention this. I am not sure why exactly - it seems like a really key concept.


Post Comment  |  Ask Ben

Recent Blog Comments
Mar 20, 2010 at 12:07 PM
Drawing On The iPhone Canvas With jQuery And ColdFusion
Simply awesome. Saved my day. ... read »
Mar 20, 2010 at 9:00 AM
Building A Fixed-Position Bottom Menu Bar (ala FaceBook)
I would like to say thx for an easy way to create a bottom bar. I do have a ?. Is it possible to center the bar if i want to resize it to ex 85%. Regards Offenbach ... read »
Mar 19, 2010 at 7:26 PM
MySQL 3/4 - com.mysql.jdbc.Driver And allowMultiQueries=true
Thank you very much for this post. Adding allowMultiQueries="true" in context.xml didn't help until I added it to url as allowMultiQueries=true Good idea is to use prepared statements and it will he ... read »
Jim
Mar 19, 2010 at 4:49 PM
Nobody Puts Baby In The Corner!
Wow. This is like suddenly finding a support group for your secret shame. I'm not alone! I always liked this movie, even though it is extremely cheesy. I just wish Jennifer Grey hadn't gotten the ... read »
Mar 19, 2010 at 4:47 PM
Application.cfc OnRequest() Method Affects OnError() Arguments
@Jason and @Ben, I've been doing some CF9 refactoring on our systems and noticed an odd occurrence with onError as well. Found a way to work around my problem, but what I saw was... Background: Our ... read »
Jim
Mar 19, 2010 at 4:44 PM
Shoot 'Em Up Starring Clive Owen And Paul Giamatti
I actually enjoyed this movie quite a lot. It was different, certainly, but I think they were going for more of a Quentin Tarentino-"wow, that was weird"-vibe than an actual spoof. Once I realize ... read »
Mar 19, 2010 at 4:34 PM
An Intensive Exploration Of jQuery With Ben Nadel (Video Presentation)
Hey I guess the video is down. Is there anyway you can upload to youtube or vimeo or some other service? Greatly appreciated. ... read »
Mar 19, 2010 at 4:24 PM
ColdFusion CFPOP - My First Look
@Ben Thanks for the follow up! The root of the problem had to do with being able to trace bounced emails to specific records in a DB table. Let's say you run an email campaign and you get 1,000 bou ... read »