Using PushStack() In jQuery Plugins To Create New Collections
Posted October 29, 2009 at 9:58 AM
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
Newer Post
Building A Fixed-Position Bottom Menu Bar (ala FaceBook)
Older Post
Caching ColdFusion Component Methods Has Negligible Performance Improvements
Reader 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.
@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.
