A Really Simple jQuery Plugin Tutorial

Written by Kevin Liew on 23 Mar 2009
289,621 Views • Tutorials

1. Introduction

Creating a jQuery Plugin is an advanced topic for a jQuery beginner. This month, I have been playing with jQuery intensively. Though I have learnt how to separate the javascript code from html document, I ain't satisfy yet. Whenever I look at my javascript file, it's messy. So, I have decided to go one step further - learn how to write a jQuery plugin to tidy up the javascript file.

This plugin is based on my previous tutorial - Navigation List menu + jQuery Animate Effect Tutorial . Last time, I wrote the script and chucked in all the code in the document.ready section, like this:

$(document).ready(function() {
	
	$('ul#menu li:even').addClass('even');
		
	$('ul#menu li a').mouseover(function() {
		
		$(this).animate( { paddingLeft:"20px" }, { queue:false, duration:500 });
		
	}).mouseout(function() {
	
		$(this).animate( { paddingLeft:"0" }, { queue:true, duration:500 });
		
	}).click(function() {
	
		$(this).animate( { fontSize:"20px" }, { queue:false, duration:500 });
	});
			
});	  

But now, I want it to display something like this:
$(document).ready(function() {
	
	$(#menu).animateMenu({
		padding:20
	})
			
});	  

It looks much more better, and easier to reuse this script for another project.

 

2. Plugin Structure

jQuery website has provided a very detailed explanation in Plugins/Authoring page. However, I found it's hard to understand.

Alright, to make your life easier, I did some research online, the following snippet will be a good structure to write a plugin.

//You need an anonymous function to wrap around your function to avoid conflict
(function($){

	//Attach this new method to jQuery
 	$.fn.extend({ 
 		
 		//This is where you write your plugin's name
 		pluginname: function() {

			//Iterate over the current set of matched elements
    		return this.each(function() {
			
				//code to be inserted here
			
    		});
    	}
	});
	
//pass jQuery to the function, 
//So that we will able to use any valid Javascript variable name 
//to replace "$" SIGN. But, we'll stick to $ (I like dollar sign: ) )		
})(jQuery);

 

2. Plugin With Options

If you look at step one - Introduction, the "padding" value for this plugin is user configurable. It good to have some settings so that user able to chage it according to their own needs. Please make sure you specify the default values for each of the variables for good practise. Now, you'll need the following code:

(function($){

 	$.fn.extend({ 
 		
		//pass the options variable to the function
 		pluginname: function(options) {


			//Set the default values, use comma to separate the settings, example:
			var defaults = {
				padding: 20,
				mouseOverColor : '#000000',
				mouseOutColor : '#ffffff'
			}
				
			var options =  $.extend(defaults, options);

    		return this.each(function() {
				var o = options;
				
				//code to be inserted here
				//you can access the value like this
				alert(o.padding);
			
    		});
    	}
	});
	
})(jQuery);

 

3. The animateMenu Plugin

Now you have learnt the plugin structure. The following is the plugin I created based on my previous tutorial. I have successfull convert the standard jQuery script to a plugin that accepts 4 configurations:

  • animatePadding : Set the padding value for the animate effect
  • defaultPadding : Set the default padding value
  • evenColor : Set the color this color if index value is even number
  • oddColor : Set the color this color if index value is odd number
(function($){
	$.fn.extend({ 
		//plugin name - animatemenu
		animateMenu: function(options) {

			//Settings list and the default values
			var defaults = {
				animatePadding: 60,
				defaultPadding: 10,
				evenColor: '#ccc',
				oddColor: '#eee'
			};
			
			var options = $.extend(defaults, options);
		
    		return this.each(function() {
				var o =options;
				
				//Assign current element to variable, in this case is UL element
				var obj = $(this);				
				
				//Get all LI in the UL
				var items = $("li", obj);
				  
				//Change the color according to odd and even rows
				$("li:even", obj).css('background-color', o.evenColor);				
			 	$("li:odd", obj).css('background-color', o.oddColor);					  
				  
				//Attach mouseover and mouseout event to the LI  
				items.mouseover(function() {
					$(this).animate({paddingLeft: o.animatePadding}, 300);
					
				}).mouseout(function() {
					$(this).animate({paddingLeft: o.defaultPadding}, 300);
				});
				
    		});
    	}
	});
})(jQuery);


 

4. Full source code

You can save the plugin in a separated file (for example, jquery.animatemenu.js). In this tutorial, I put the script in the html document.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
    
<head>
    <title></title>
    <script type="text/javascript" src="http://code.jquery.com/jquery-latest.js"></script>
	<script>

(function($){
 	$.fn.extend({ 
 		//plugin name - animatemenu
 		animateMenu: function(options) {

			var defaults = {
			    animatePadding: 60,
           		defaultPadding: 10,
           		evenColor: '#ccc',
           		oddColor: '#eee',
			};
			
			var options = $.extend(defaults, options);
		
    		return this.each(function() {
				  var o =options;
				  var obj = $(this);				
				  var items = $("li", obj);
				  
				  $("li:even", obj).css('background-color', o.evenColor);				
				  $("li:odd", obj).css('background-color', o.oddColor);					  
				  
				  items.mouseover(function() {
					  $(this).animate({paddingLeft: o.animatePadding}, 300);
					
				  }).mouseout(function() {
					  $(this).animate({paddingLeft: o.defaultPadding}, 300);
					
				  });
    		});
    	}
	});
})(jQuery);
	
	</script>
	
	<script type="text/javascript">
	$(document).ready(function() {
		$('#menu').animateMenu({animatePadding: 30, defaultPadding:10});
	});	
	</script>
	<style>
	  body {font-family:arial;font-style:bold}
	  a {color:#666; text-decoration:none}
		#menu {list-style:none;width:160px;padding-left:10px;}
		#menu li {margin:0;padding:5px;cursor:hand;cursor:pointer}
	</style>
</head>   
<body>

<ul id="menu">
	<li>Home</li>
	<li>Posts</li>
	<li>About</li>
	<li>Contact</li>
</ul>

</body>
</html>
 


I hope this tutorial will give you a better understanding. It isn't too hard at all to create a jQuery plugin. I was reluctantly to learn at first, but now, I realized how simple it is.

I will be publishing another tutorial soon - How to create a simple Accordion jQuery Plugin. So, stay tuned.

Demo
Join the discussion

Comments will be moderated and rel="nofollow" will be added to all links. You can wrap your coding with [code][/code] to make use of built-in syntax highlighter.

96 comments
freelance php developer 13 years ago
i was confusing really on plugin in jquery but now it is clear. thanks for posting this
Reply
Rahul Anand 13 years ago
Great Article. Really helps me to understand the Plugin Development in JQuery. Thanks for posting such a Nice Article.

Thanks!
Reply
Jan 13 years ago
Ahh, great. Thanx for sharing this.
Now it's time to build THAT revolutionary plugin :)
Reply
Andrei 13 years ago
Thanks from Belarus! We love it)
Reply
Ashish Vishwakarma 13 years ago
Great Example, Thanks
Reply
reyn 13 years ago
Hi,

Ive been following your tutorial and I'm having trouble converting my old scripts. How can I convert this one.

Thanks in Advance.
<pre><code>
<script type="text/javascript">
function Compute(target, currentValue){
if(parseInt(currentValue.value) == 0 || parseInt(currentValue.value) > parseInt(target.value)){
alert("That Value is not Valid");
}

}
</script>

<input type="text" id="frm1" name="frm1" onkeyup="Compute(document.getElementById('frm1a'), this);"/>
<input type="text" id="frm1a" name="frm1a" value="90"/> </code></pre>
Reply
Samin Shams 13 years ago
Awesome tutorial. One syntax error though: there is a comma after defining oddColor which is useless and will cause an error.
var defaults = {
animatePadding: 60,
defaultPadding: 10,
evenColor: '#ccc',
oddColor: '#eee',
};
Reply
Md . Faysol 13 years ago
excellent
Reply
Ricardo 13 years ago
Hy,

if someone can help me....


would like to know if anyway to access this

var defaults = {
animatePadding: 60,
defaultPadding: 10,
evenColor: '#ccc',
oddColor: '#eee'
};


For example , accessing animatePadding, to know his value .... int here

$(document).ready(function() {
$('#menu').animateMenu({animatePadding: 30, defaultPadding:10});

//here some code to get value, this is an ideia, I know is not correct
$... something. animatePadding()

});

Can you please tell me how? Thanks
Reply
Jens Törnell 13 years ago
Very useful. I created my first jQuery plugin today. Thanks!
Reply
THAKKAR KOMAL 13 years ago
thanks for providing very convenient way for jquery plugin,but it will be more attractive if the output is given with the coding simultaneously.
Reply
Totoy Bibo 13 years ago
Shoudn't

var options = $.extend(defaults, options);

be just

options = $.extend(defaults, options);

the options variable has already been declared inside the anonymous function
Reply
ecco88 12 years ago
I think the arguments are in the wrong order in this case - but gets the same result.

var options = $.extend(defaults, options);

really should be:
$.extend(defaults, options) and you work with defaults. According to the jQuery API specs - the first parameter is the target of the merge. You use var something = $.extend(param1, param2,...paramN) when you want to keep param1 unchanged and force the result to be a new object. In your case doesn't seem really you want a new object.
Reply
UlaÅŸ Can Cengiz 13 years ago
not $(this).animate,

prefer

$(this).stop().animate

because of the animation queue problem.

By the way, great tutorial, thanks.
Reply