You know a little jQuery, you have used a few jQuery plugins, and now you want to write your own jQuery plugin. Don’t worry, it’s no big deal. In fact it’s fun.
If you have been putting off authoring your first jQuery plugin, it’s time to wrap a bandana around your head, fire up “The Eye of the Tiger” by “Survivor” and figure out how to defeat Apollo Creed. Sorry, for the cheesy 80s reference, I couldn’t resist.
But seriously, it really is no big deal. The most important thing is to get a firm grip on the fundamentals. That part is serious. If you don’t understand what you are doing from a jQuery-architecture standpoint, then you will quickly find yourself in a quagmire of muck and filth, and you don’t want that.
In this article we will discuss the absolute basics of how to author a jQuery plugin:
- Wrapping your plugin in a self-executing anonymous function
- Extending the jQuery prototype,
- Iterating over each element in the jQuery collection returned by your plugin.
This is the big stuff. Once you get your noggin around these concepts, the fun can begin.
A note about Self-executing anonymous functions
These are otherwise known as “immediate functions”. An immediate function is simply a function that is wrapped in parentheses, and followed by a pair of parentheses:
|
1 2 3 |
(function(){ //code here fires right away, you don’t need to call the function })(); |
You can learn more about immediate functions in my blog post: “Immediate Functions in JavaScript – The Basics” as well as my blog post: “Using an Immediate Function to Create a Global JavaScript Variable That Has Private Scope”
The main point here is to make sure you are comfortable with the concept of an immediate function in JavaScript. It’s important to do before reading further.
Where does my jQuery plugin code go?
Good question. The answer is: In its own file. By convention, you’ll want to create a JavaSript file named jquery.myPlugin.js. Then you’ll need to reference it just as you would any other JavaScript file:
|
1 |
<script src=”[PATH TO]/jquery.myPlugin.js”></script> |
Just make sure you reference jQuery before you reference your plugin.
For simplicity sake, we will reference our jQuery plugin via a set of SCRIPT tags, right in the page (that is perfectly valid, but definitely not practical).
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>My first jQuery Plugin</title> <script src="jquery.js"></script> </head> <body> <p>some content here...</p> <script> //our plugin code is gonna go right here! </script> <script> $(document).ready(function(){ //we're gonna invoke our plugin here! }); </script> </body> </html> |
Example # 1
|
1 2 3 4 5 6 7 |
(function(){ $.fn.myPlugin = function() { this.each(function(){ //plugin code goes here }); }; })(); |
In example # 1 we have the absolute bare-bones code needed for a jQuery plugin. Here are the important points to consider for example # 1:
Wrap your jQuery plugin in an immediate Function
This is considered a best-practice and for good reason. Taking this approach allows you to create as many variables as you need in your plugin, without polluting the global namespace. Don’t overlook this, it allows you complete freedom with regards to the number of variables you need to create, and sandboxes all of these variables very nicely.
Again, an immediate function is simply a function that is wrapped in parentheses, and followed by a pair of parentheses. It fires right away when the JavaScript is evaluated, you don’t need to (and cannot) call the function. It just fires right away and whatever code you implement in that function executes. It’s a great way to provide private variable scope to some code without a whole lotta fuss.
If you are still having a tough time with the concept of immediate functions, stop, do a google search for JavaScript Immediate Function, learn it, live it, ask it out on a date, marry it, and then come back here to keep on reading.
https://www.google.com/search?q=javascript+immediate+function
(I’m serious about this immediate function thingy)
Your jQuery plugin becomes a property of the jQuery prototype object
jQuery is a function. Actually, the code in jQuery follows the factory pattern and returns a function that in-turn returns different kinds of things, depending on what you pass into that function. Most of the time, it returns an HTML collection wrapped with jQuery (hence a jQuery collection object), but again, the actual return value depends on what you are passing in.
Every JavaScript object has a prototype property, this includes functions. jQuery exposes its prototype property as “fn”. So, you simply assign your plugin to be a property of that “fn” object. Once you have done that, jQuery now has a new method that is YOUR plugin.
|
1 2 3 |
$.fn.myPlugin = function(){ //insert awesome code here }; |
Now you can do this:
|
1 |
$(‘div’).myPlugin(); |
Inside of your plugin, the JavaScript keyword “this” is already a jQuery object
Most people know that inside of a jQuery callback, “this” usually refers to the current native DOM element that is being iterated over. When you wrap “this” in jQuery, it becomes a jQuery object. So, we often refer to “this” as “$(this)”.
Inside of your plugin, there is no need to do that because the JavaScript keyword “this” is already a jQuery object. If you refer to “this” as “$(this)”, it’s not going to kill anyone, but it is not necessary and just uses more memory than is needed.
|
1 2 3 |
$.fn.myPlugin = function(){ //”this” is already a jQuery collection object }; |
Your jQuery plugin returns a jQuery collection
What your jQuery plugin returns depends on the CSS selector that was passed-in. For example, if you do this: $(body).myPlugin(), your jquery plugin will return a jQuery collection that has exactly one element: the BODY tag of your document (unless of course you have more than one BODY element in your page, which would be a bit of a head-scratcher). So, if you have an unordered list that has for example three items, and you invoke your plugin like this: $(ul li).myPlugin(), then your plugin will return a jQuery collection that contains three elements.
Use this.each() to iterate over all of the elements that are returned by your jQuery plugin
jQuery’s .each() method is a lovely little tool that allows you to iterate over a jQuery collection and “do something” to each element. Keep in mind that a jQuery collection can always contain exactly one element, and when it does, then the .each() method will run once. But when a jQuery collection contains multiple elements, then the .each() method will run once for EACH element in that collection.
When you use the .each() method, you pass in an anonymous function, and inside that function you have access to the current element that is being iterated over. It is here that you will need to wrap “this” with jQuery if you want it to be a jQuery object: Use $(this) for the jQuery object that represents the current element, or simply “this” for the native DOM element implementation. This anonymous function takes as its first argument the index of the current element. This is surprisingly handy: what if you want to know if this the the first element in the collection? or the last? That index number will help you with that task.
Now you are ready to write some awesome jQuery plugin code
Thanks for hanging in there. The preceding details were important. I know you are anxious to write some code, but understanding the outer architecture of a jQuery plugin is critical. If you do not understand what was just covered, then you will quickly be awash in spaghetti code that is not working right and will be difficult to debug. I promise you.
Example # 2
|
1 2 3 4 5 |
//Example # 2A //run myPlugin against every A tag in the document $(document).ready(function(){ $('a').myPlugin(); }); |
In example # 2, we invoke our jQuery plugin. We wrap it in a $(document).ready() call so that it only fires once the document is ready.
Invoking our plugin is as simple as $(CSS SELECTOR).myPlugin().
This is because our plugin is a property of the jQuery prototype object, which makes it a completely valid jQuery method. Nice.
Example # 3
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
//Example # 3A //run myPlugin against every LI tag in the document $(document).ready(function(){ $('li').myPlugin(); }); //Example # 3B //run myPlugin against every LI tag in the document that is the last one in a list $(document).ready(function(){ $('li:last').myPlugin(); }); //Example # 3C //run myPlugin against the BODY tag $(document).ready(function(){ $('body').myPlugin(); }) |
In example # 3, we see how our plugin can behave differently depending on what we pass into it. In each case, the jQuery collection object returned by our plugin will differ, depending again on what CSS selector we passed-in.
Example # 4
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
(function(){ $.fn.myPlugin = function() { //for each element in the collection this.each(function(){ //make the element green, //..the background yellow, //...and the font bold 18px Comic Sans $(this).css({ 'color':'green', 'background-color': 'yellow', 'font': 'bold 18px "Comic Sans MS",cursive,sans-serif' }); }); }; })(); |
In example # 4, we have included some implementation code so that our jQuery plugin actually does something. I this case, for each element returned in the jQuery collection, we change the CSS so that the element’s color is green, the background color is yellow, and the font is “Comic Sans”. Not too pretty, but just enough so that when we run the code, we can see that our plugin is working perfectly. More importantly, if you vary the CSS selector that is passed-in, you will see that our plugin behaves differently in each case (i.e. the HTML elements that become green with yellow backgrounds and Comic Sans font will vary).
Full Working Code for this Article
http://jsfiddle.net/wdUtL/
Full Working Code for this ArticleWith Comments
http://jsfiddle.net/ewTez/
Summary
In this article we discussed the absolute basics of how to author a jQuery plugin. We covered how to wrap your plugin in a self-executing anonymous function, how to extend the jQuery prototype, and how to iterate over each element in the jQuery collection returned by your plugin.
This example provided in this article was very simple. The main purpose of the article was to provide the overview needed so that you understand how a jQuery plugin is constructed, how it works at the most basic level, and importantly how the value of the JavaScript keyword “this” will vary a bit, depending on where you are in the code.
With a firm understanding of how a jQuery plugin is constructed, we can move on to best practices and more intermediate jQuery plugin authoring techniques.
Helpful Links for jQuery plugin authoring basics
http://docs.jquery.com/Plugins/Authoring
http://coding.smashingmagazine.com/2011/10/11/essential-jquery-plugin-patterns/
http://blog.kevinchisholm.com/jquery/jquery-each-method/
