Tutorial: Creating a jQuery plugin

最新推荐文章于 2020-07-19 10:14:44 发布

besley

最新推荐文章于 2020-07-19 10:14:44 发布

阅读量839

点赞数

分类专栏： jQuery

jQuery 专栏收录该内容

12 篇文章

订阅专栏

Learn how to create a jQuery plugin from scratch – the basics, options, compatibility and examples.

http://devheart.org/articles/tutorial-creating-a-jquery-plugin/

The Basics

A plugin is written as a method or function.

Creating a jQuery Function

Syntax

The function has to return this.each(..) to maintain chainability – so that the function can be used with a single or several jQuery objects.

      jQuery.fn.myFunction =  
     function 
     ( 
     ) 
     { 
     
     return  
     this.each 
     ( 
     function 
     ( 
     ) 
     { 
     
     // element-specific code here 
     
     } 
     ); 
     
     };

Example

      jQuery.fn.makeTextRed =  
     function 
     ( 
     ) 
     { 
     
     return  
     this.each 
     ( 
     function 
     ( 
     ) 
     { 
     
              $ 
     ( 
     this 
     ).css 
     ( 
     'color',  
     'red' 
     ); 
     
     } 
     ); 
     
     }; 
     
     // Example usage 
     
      $ 
     ( 
     '#my-div' 
     ).makeTextRed 
     ( 
     );  
     // make text in "my-div" red 
     
      $ 
     ( 
     'p' 
     ).makeTextRed 
     ( 
     );  
     // make all paragraphs red

Creating a jQuery Method

Syntax

      jQuery.myMethod =  
     function 
     ( 
     ) 
     { 
     
     // code here 
     
     };

Example

      jQuery.sayHelloWorld =  
     function 
     ( 
     ) 
     { 
     
     alert 
     ( 
     'Hello World' 
     ); 
     
     }; 
     
     // Example usage 
     
      $.sayHelloWorld 
     ( 
     );  
     // alerts "Hello World"

Options

Make your plugin as flexible and user friendly as possible using options. The $.extend() method takes two or more objects as arguments and merges the contens of them into the first object.

Example

A function that set text color (red by default).

      jQuery.fn.makeTextColored =  
     function 
     (settings 
     ) 
     { 
     
     var config =  
     { 
     
     'color':  
     'red' 
     
     }; 
     
     if  
     (settings 
     ) 
     {$.extend 
     (config, settings 
     ); 
     } 
     
     return  
     this.each 
     ( 
     function 
     ( 
     ) 
     { 
     
              $ 
     ( 
     this 
     ).css 
     ( 
     'color', config.color 
     ); 
     
     } 
     ); 
     
     };

We can now choose use this function passing the settings parameter or not.

      $ 
     ( 
     '#my-div' 
     ).makeTextColored 
     ( 
     );  
     // make text red (default) 
     
 
    

      $ 
     ( 
     '#my-div' 
     ).makeTextColored 
     ( 
     'blue' 
     );  
     // make text blue 
    

Compatibility

As the $ variable might be used by other plugins, use a alias technique to make your plugin forward-compatible.

 
     ( 
     function 
     ($ 
     ) 
     { 
     
      $.fn.myFunction =  
     function 
     ( 
     )  
     { 
     
     return  
     this.each 
     ( 
     function 
     ( 
     )  
     { 
     
     // element-specific code here 
     
     } 
     ); 
     
     }; 
     
     } 
     ) 
     (jQuery 
     );

We pass jQuery to the function and can now use whatever alias for jQuery we like. So instead of $ you could also use any other valid JavaScript variable name.

The jQuery Plugin Checklist

This is a list of important points to remember when developing a jQuery plugin (from jQuery.com).

Name your file jquery.[insert name of plugin].js, eg. jquery.debug.js
All new methods are attached to the jQuery.fn object, all functions to the jQuery object.
inside methods, this is a reference to the current jQuery object.
Any methods or functions you attach must have a semicolon (;) at the end – otherwise the code will break when compressed.
Your method must return the jQuery object, unless explicity noted otherwise.
Use this.each to iterate over the current set of matched elements.
Always attach the plugin to jQuery instead of $, so users can use a custom alias via noConflict().

jQuery Plugin Templates

These are two good code templates to start from when developing a jQuery plugin.

Function Template

 
     ( 
     function 
     ($ 
     ) 
     { 
     
          $.fn.myPlugin =  
     function 
     (settings 
     ) 
     { 
     
     var config =  
     { 
     
     'foo':  
     'bar' 
     
     }; 
     
     if  
     (settings 
     ) 
     {$.extend 
     (config, settings 
     ); 
     } 
     
     return  
     this.each 
     ( 
     function 
     ( 
     ) 
     { 
     
     // element-specific code here 
     
     } 
     ); 
     
     }; 
     
     } 
     ) 
     (jQuery 
     );

Method Template

 
     ( 
     function 
     ($ 
     ) 
     { 
     
          $.myPlugin =  
     function 
     (settings 
     ) 
     { 
     
     var config =  
     { 
     
     'foo':  
     'bar' 
     
     }; 
     
     if  
     (settings 
     ) 
     {$.extend 
     (config, settings 
     ); 
     } 
     
     // code here 
     
     return  
     this; 
     
     }; 
     
     } 
     ) 
     (jQuery 
     );

Example: jQuery Slideshow Plugin

I have chosen to use very simple examples so far in order for you to get started. The following example is a bit more complex and might help to get your inspiration going.

It uses the function setInterval() in combination with the jQuery effects fadeOut() andfadeIn() to cycle any number of images within a HTML-element.

The Setup

HTML

 
     <div id="slideshow"> 
     
     <img src="img/sample-image-1.png" alt="" /> 
     
     <img src="img/sample-image-2.png" alt="" /> 
     
     <img src="img/sample-image-3.png" alt="" /> 
     
     <img src="img/sample-image-4.png" alt="" /> 
     
     </div>

CSS

 
     #slideshow img  
     { 
     
     display 
     :  
     none 
     ; 
     
     position 
     :  
     absolute 
     ; 
     
     }

JavaScript

 
     ( 
     function 
     ($ 
     ) 
     { 
     
          $.simpleSlideShow =  
     function 
     (selector, settings 
     ) 
     { 
     
     // settings 
     
     var config =  
     { 
     
     'delay':  
     2000, 
     
     'fadeSpeed':  
     500 
     
     }; 
     
     if  
     ( settings  
     ) 
     {$.extend 
     (config, settings 
     ); 
     } 
     
     // variables 
     
     var obj = $ 
     (selector 
     ); 
     
     var img = obj.children 
     ( 
     'img' 
     ); 
     
     var count = img.length; 
     
     var i =  
     0; 
     
     // show first image 
     
              img.eq 
     ( 
     0 
     ).show 
     ( 
     ); 
     
     // run slideshow 
     
     setInterval 
     ( 
     function 
     ( 
     ) 
     { 
     
                  img.eq 
     (i 
     ).fadeOut 
     (config.fadeSpeed 
     ); 
     
                  i =  
     ( i+ 
     1 == count  
     ) ?  
     0 : i+ 
     1; 
     
                  img.eq 
     (i 
     ).fadeIn 
     (config.fadeSpeed 
     ); 
     
     }, config.delay 
     ); 
     
     return  
     this; 
     
     }; 
     
     } 
     ) 
     (jQuery 
     );

Usage

To enable slideshow on the #slideshow div, we simply call it using the following JavaScript code:

 
     <script type="text/javascript"> 
     
      $.simpleSlideShow('#slideshow'); 
     
     </script>

Because we allow settings to change the behaviour of the slideshow, we could make it wait 5 seconds between images and set the “fade” duration to 200 ms using:

 
     <script type="text/javascript"> 
     
      $.simpleSlideShow('#slideshow', {'delay':5000, 'fadeSpeed': 200}); 
     
     </script>

View Example Download Example

It’s not harder than that! Good luck in creating your own jQuery plugins!

Published by Viktor Persson at June 7th, 2010.

Comments: 7

Feel free to share your thoughts on this article.

Fernando

Thanks for this post. I was looking for something like this.

June 7th, 2010 at 18:12 | Reply »

#42
Alex W

=) thank you!

June 16th, 2010 at 19:10 | Reply »

#50
Navneet

I worked around with jQuery and now wanted to start with Plugins
and I found out this as a great way to begin.

August 4th, 2010 at 17:10 | Reply »

#58
Pavel Savchenko

hey Viktor, great article,

just noticed: in your checklist the second bullet says: # All new methods are attached to the jQuery.fn object, all functions to the jQuery object. However, from your examples it seems the opposite (methods are att to $ and function to $.fn) is correct..

I’m really not sure which is the correct terming, please do tell.

pavel

October 22nd, 2010 at 12:39 | Reply »

#75
Matt Magi

Think Im going to try my first jQuery plugin later this week, if I can get through this mass of work piling up.

January 25th, 2011 at 00:37 | Reply »

#81
Yakumaru

WoW so good, thanks you very much!

February 21st, 2011 at 01:56 | Reply »

#86
joel

Thanks! my concern about jQuery plugins development were clarified with this tutorial

April 29th, 2011 at 20:33 | Reply »

#92