jQuery Plugin Boilerplate, revisited

Get the latest updates on this jQuery plugin via RSS
 
Please refer to the new version of the jQuery Plugin Boilerplate
 

A boilerplate for jump-starting jQuery plugins development.

Contains lots of comments to help you get going easily. It implements public and private methods, as well as public and private properties making it the ideal candidate for when building both simple and complex jQuery plugins.

It does not adhere to the suggestions made by the jQuery documentation regarding Plugins/Authoring.

The jQuery Plugin Boilerplate took some inspiration from Doug Neiner‘s Starter.

With comments:

// jQuery Plugin Boilerplate
// A boilerplate for jumpstarting jQuery plugins development
// version 1.1, May 14th, 2011
// by Stefan Gabos

// remember to change every instance of "pluginName" to the name of your plugin!
(function($) {

    // here we go!
    $.pluginName = function(element, options) {

        // plugin's default options
        // this is private property and is  accessible only from inside the plugin
        var defaults = {

            foo: 'bar',

            // if your plugin is event-driven, you may provide callback capabilities
            // for its events. execute these functions before or after events of your 
            // plugin, so that users may customize those particular events without 
            // changing the plugin's code
            onFoo: function() {}

        }

        // to avoid confusions, use "plugin" to reference the 
        // current instance of the object
        var plugin = this;

        // this will hold the merged default, and user-provided options
        // plugin's properties will be available through this object like:
        // plugin.settings.propertyName from inside the plugin or
        // element.data('pluginName').settings.propertyName from outside the plugin, 
        // where "element" is the element the plugin is attached to;
        plugin.settings = {}

        var $element = $(element), // reference to the jQuery version of DOM element
             element = element;    // reference to the actual DOM element

        // the "constructor" method that gets called when the object is created
        plugin.init = function() {

            // the plugin's final properties are the merged default and 
            // user-provided options (if any)
            plugin.settings = $.extend({}, defaults, options);

            // code goes here

        }

        // public methods
        // these methods can be called like:
        // plugin.methodName(arg1, arg2, ... argn) from inside the plugin or
        // element.data('pluginName').publicMethod(arg1, arg2, ... argn) from outside 
        // the plugin, where "element" is the element the plugin is attached to;

        // a public method. for demonstration purposes only - remove it!
        plugin.foo_public_method = function() {

            // code goes here

        }

        // private methods
        // these methods can be called only from inside the plugin like:
        // methodName(arg1, arg2, ... argn)

        // a private method. for demonstration purposes only - remove it!
        var foo_private_method = function() {

            // code goes here

        }

        // fire up the plugin!
        // call the "constructor" method
        plugin.init();

    }

    // add the plugin to the jQuery.fn object
    $.fn.pluginName = function(options) {

        // iterate through the DOM elements we are attaching the plugin to
        return this.each(function() {

            // if plugin has not already been attached to the element
            if (undefined == $(this).data('pluginName')) {

                // create a new instance of the plugin
                // pass the DOM element and the user-provided options as arguments
                var plugin = new $.pluginName(this, options);

                // in the jQuery version of the element
                // store a reference to the plugin object
                // you can later access the plugin and its methods and properties like
                // element.data('pluginName').publicMethod(arg1, arg2, ... argn) or
                // element.data('pluginName').settings.propertyName
                $(this).data('pluginName', plugin);

            }

        });

    }

})(jQuery);

Without comments:

// jQuery Plugin Boilerplate
// A boilerplate for jumpstarting jQuery plugins development
// version 1.1, May 14th, 2011
// by Stefan Gabos

(function($) {

    $.pluginName = function(element, options) {

        var defaults = {
            foo: 'bar',
            onFoo: function() {}
        }

        var plugin = this;

        plugin.settings = {}

        var $element = $(element),
             element = element;

        plugin.init = function() {
            plugin.settings = $.extend({}, defaults, options);
            // code goes here
        }

        plugin.foo_public_method = function() {
            // code goes here
        }

        var foo_private_method = function() {
            // code goes here
        }

        plugin.init();

    }

    $.fn.pluginName = function(options) {

        return this.each(function() {
            if (undefined == $(this).data('pluginName')) {
                var plugin = new $.pluginName(this, options);
                $(this).data('pluginName', plugin);
            }
        });

    }

})(jQuery);

Usage

$(document).ready(function() {

    // attach the plugin to an element
    $('#element').pluginName({'foo': 'bar'});

    // call a public method
    $('#element').data('pluginName').foo_public_method();

    // get the value of a property
    $('#element').data('pluginName').settings.foo;

});

Top

Requirements

jQuery 1.5.2+

It’s the only version I’ve tested the boilerplate with; it may be applicable to earlier versions, too. If you can test, please let me know. Thanks!

Top

54 responses to “jQuery Plugin Boilerplate, revisited”

Follow the comments via RSS
  • Pete Januarius, 2013-04-22, 01:28

    Hi Stefan,

    Thanks very much for this article. I am looking at modelling my plugins on it. One thing I noticed which would be good to get your clarification:

    When you call a private method, the scope inside the private method (ie. the ‘this’ object) is equal to the Window object. Is this intended?

    Cheers

    Pete…

    Reply
    • Stefan Gabos, 2013-04-23, 05:50

      in JavaScript the “this” keyword refers to the object on the left side of the “.” (dot). But because private methods are called without “.” (e.g. foo_private_method();) then “window” it’s considered to be the caller (although, since this is a private method, you will not be able to call it from outside the object like window.foo_private_method();).

  • Arvind, 2013-06-10, 09:00

    Thanks much for the article. Was very helpful.

    Reply
  • Tommy Fisher, 2013-08-13, 10:13

    Hi,

    Thanks for the template, it’s really going to help my development.

    I have a question, to access a public method from outside the plugin we have to use:

    $('#element').data('pluginName').foo_public_method()

    However, if I wanted it to be more like standard plugin API format, such as:

    $('#element').pluginName(foo_public_method)

    How would the above code have to be changed to allow this?
    Many thanks
    Tommy

    Reply
    • faris, 2013-11-12, 12:49

      just use

      jQuery.fn.pluginName.foo_public_method= [function]

      hope may help u

  • faris, 2013-11-12, 12:47

    working for newest jquery.. thanx bro

    Reply

Leave a Reply

Your email address will not be published
You can use <strong>, <em>, <a>, <img>, <code>
Characters are not case-sensitive