Tutorial: Creating a jQuery plugin

来源：互联网发布：淘宝开店运费怎么弄编辑：程序博客网时间：2024/06/04 19:57

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 ExampleDownload Example

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

Published by Viktor Persson at June 7th, 2010.

jQuery
plugins
slideshow

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