How to develop a jQuery plugin

Lately I started a new project at a German ISP where we (the team and me) have to develop several extensions to jQuery in order to build a framework to work with in this project. I am using jQuery for several years now but never had to develop my own extensions, because most of the plugins available solved problems I came a cross. This time I have to do my own and started questioning uncle google about how to do it. No surprise there are several approaches to do a plugin for jQuery, but none of the tutorials I found answered all my Questions completely, so I decided to write this sum up of what I learned.

First of all you will need the basic wrapping:

(function($){
   // your js code goes here
})(jQuery);

This wrapping adds your code to the jQuery library if you add the js file to your page.
Next thing you will have to do is add the basic functionality to your plugin.

$.fn.yourPlugin = function(options){
}

By adding those lines to your js file within the first code snippet you now can access your plugin by:

$('#yourDomElement').yourPlugin();

Next you need to know the difference between private and public vars within the class you are developing. If you write something like:

   /**
     * default options for plugin
     * private
     * @var array defaultOptions
     */
    var defaultOptions = {
        action:       false,
        debug:        false
    }

This would be a private var witch is only accessible within the class it self. If you need to have a var of your class to be public you have to write something like this:

   /**
     * default options for plugin
     * public
     * @var array defaultOptions
     */
    $.fn.yourPlugin.defaultOptions = {
        action:       false,
        debug:        false
    }

One word has to be said by now, public variables can only be defined after the declaration of the constructor of your plugin, otherwise the compiler will throw a nice little javascript error because “yourPlugin” was not defined yet.
Now that we have learned this we can go on with the possibility of configuration for the plugin. Like in every other language we will need to have some basic properties for the class that can be overwritten by your needs. To do something like that is quite simple:

   /**
     * yourPlugin base constructor
     *
     * @param [] options
     * @return void
     */
    $.fn.yourPlugin = function(options){
        // extend default options with overrides
        var opts = $.extend({}, defaultOptions, options);
    }

So by now you can set the options you need by writing something like this:

   $('#yourDomElement').yourPlugin({
      action:       myAction
    });

In this case you would have set opts.action from “false” to “myAction”.
Next we will go to private and public class methods. It is allmost the same as defining public and private member variables of your class.
Something like this would be private:

   /**
     * private
     * method to do some vodoo
     */
    function yourPrivateClassMethod()
    {
        // the methods code
    }

And something like this is a public method:

   /**
     * public
     * method to do some vodoo
     */
    $.fn.yourPlugin.yourPublicClassMethod = function()
    {
        // the methods code
    }

Same rules like for the public member variables,… they have to be declared after your constructor, otherwise you will get an error. Another word of advise,.. as a developer I thought to access variables and methods within a class I can go by “this”,.. forget “this”,.. private methods and vars are accessed directly by their name, the public one you can access either by $(this).yourPlugin.yourPublicClassMethod() or $.fn.yourPlugin.yourPublicClassMethod().

So by now, if we put together the things we learned, we can do something like this:

(function($){
   /**
     * default options for plugin
     * private
     * @var array defaultOptions
     */
    var defaultOptions = {
        action:       false,
        debug:        false
    }

    /**
     * yourPlugin base constructor
     *
     * @param [] options
     * @return void
     */
    $.fn.yourPlugin = function(options){
        // extend default options with overrides
        var opts = $.extend({}, defaultOptions, options);

        switch(opts.action)
        {
        	case 'private':
        		yourPrivateClassMethod();
        		break;

        	case 'public':
        		$.fn.yourPlugin.yourPublicClassMethod();
        		break;
        }
    }

    /**
     * public
     * method to do some vodoo
     */
    $.fn.yourPlugin.yourPublicClassMethod = function()
    {
    	// should alert 'false', 'false',
    	//because the public vars where not set

        alert($.fn.yourPlugin.defaultOptions.action);
        alert($.fn.yourPlugin.defaultOptions.debug);
    }

    /**
     * default options for plugin
     * public
     * @var array defaultOptions
     */
    $.fn.yourPlugin.defaultOptions = {
        action:       false,
        debug:        false
    }

    /**
     * private
     * method to do some vodoo
     */
    function yourPrivateClassMethod()
    {
        alert('This method is private');
    }

})(jQuery);

I hope this little summary helped a little in understanding how javascript classes and jQuery work.
If you have any suggestion or did see some errors in this tutorial please let me know about it.